Logging System

This particular article will provide some more information about the logging system we use in this project. It is not something 'unique' or 'magical': there are other projects out there that will use a similar if not the same approach to logging.

Nevertheless, explaining the ins and outs is always beneficial.

This document was made by Mwexim and is shared on the wiki to provide further information to potential contributors.

The main structure

The skript-parser logger is focused and based around recursivity, but what does it mean? The parser will start a process at a certain point. Most of these processes start with matching a string against a certain pattern. The logger will therefore recurse into a certain logging state or logging context. This means that the logger will say what it will be doing next and will add it to the list of things he was doing already.

Essentially, the logger has an internal LinkedList that holds the order of operations it was performing. When the logger starts matching a pattern (always the beginning of such order), it will add the ErrorContext.MATCHING to that internal list, basically saying "Hey, I'm matching some sh*t right now".

When a new process is started, it will simply replace the latest process on the list. A list of all processes, ordered by increasing priority:

• NO_MATCH: No match was found (yes, this is a context too!)
• MATCHING: When matching a string against a pattern
• INITIALIZATION: Syntax successfully matched and is now initialized
• CONSTRAINT_CHECKING: Syntax successfully initialized and is now checked for additional factors (such as types)
• RESTRICTED_SYNTAXES: All syntax checks have successfully passed and the syntax is now checked against the restrictions of the section it is currently in.

The moment an error occurs, the latest context is consulted and will be the final cause of the error. This means that errors can be precisely located in your code, which makes it very handy!

There is one exception, however, to this process. We said that we always replaced the current context with the new one when we will be doing something else, but that's not quite useful. Look at the following scenarios:

• We are parsing an expression inside an expression
• We are parsing the expressions inside a string (like "1 + 1 = %1 + 1%")

What essentially happens with this system is that all error-related information about the current element will be lost once we replace it with a new context. This is were recursivity jumps in.

Recursivity

Once we approach a new element (at first this is always to parse it against registered syntax), we recurse the logger. The logger will split the current ErrorContexts and will paste the new one behind it. This means that we can get structures like these:

ErrorContext.MATCHING + ErrorContext.RESTRICTED_SYNTAXES
ErrorContext.MATCHING + ErrorContext.MATCHING + ErrorContext.INITIALIZATION

Some of you may notice something: all the previous ErrorContexts are always 'matching'. If you think about it, this makes perfect sense: when we're parsing an expression inside an expression, we will never be at any state other than matching.

The following process essentially starts when recursing:

• The current context is always 'matching' (although it can be different theoretically, we will not cover why, since it is not important).
• The recursed context will always start with 'matching' as well. This makes sense when you think about it: if we're parsing an expression inside an expression, we're matching another expression.
• When the callback() function is executed, the recession is stopped. We return back to the context of the previous element (not the first one!).

Finalizing entries

Logged entries (errors, warnings, info) are not used by default, they need to be finalized first. Once they are, they cannot be changed anymore. This will also clear all current logs and reset the last error context to MATCHING (since we already handled the error, we need to erase the current information).

Once the parser is done, we can close() the logger to retrieve all relevant logs. This includes all warnings and information messages if no errors were present and otherwise only those specified errors. Once the logger is closed, it cannot be used anymore.