Error codes
Both lexer and parser when invoked return an integer value. Positive return values indicate a success. Zero is never reported. Negative values are used to report errors.
Error codes come from predefined set which is common for lexer and parser. Constants for these codes are available inside parser and lexer class. If option Code.Base.OwnClass is active, error codes are defined inside base class.
User error codes
User is free to define own error codes. Custom user codes must be defined as values lower or equal constant USER_FIRST (i.e. USER_FIRST-1 , USER_FIRST-2 etc.).
User can return error codes from custom defined procedures. It is also acceptable to return error for custom code sections embedded directly in lexer and parser procedures.
User can report both custom codes as well as predefined codes normally used by lexer or parser. In later case it is best if use predefined codes matches their meaning.
Note that Alpag is not designed to handle exceptions, tunnel exceptions or use exceptions as natural way of reporting errors.
Any exception thrown by user code leaves lexer or parser in potentially unstable state. Exceptions can be used only to report critical errors which abort further processing.
Predefined error codes
Some error codes are common for lexer and parser while other are lexer or parser specific.
Nevertheless, when user invokes parser, which in turn invokes lexer, any error code reported by lexer is tunneled via parser and is reported to the user. This means that user code should be prepared to handle any error.
It can be assumed, that any returned negative value indicates an error.
Here is summary of error codes returned by lexers and parsers
Common error codes
EOF – used to report end of file. This is not an error.
User-defined code can return EOF to indicate end of input stream.
Lexer error codes
INVALID_INPUT_CODE – returned by lexer when input byte is outside of encoding range.
INCOMPLETE_INPUT_CODE – returned by lexer when multibyte input sequence is not complete.
INVALID_INPUT_SEQUENCE – returned by lexer when multibyte input sequence is not valid.
ERROR_READING_INPUT – general error when reading input
CHAR_OUT_OF_RANGE – returned when input character is outside of supported character range
NOTHING_MATCHED – returned by lexer when current input was not matched by any lexer rule. Reinvoking lexer after this code is reported skips one character and resumes analysis
LEXER_ALLOC_ERROR_IN – reported when lexer input buffer could not be allocated
LEXER_ALLOC_ERROR_LEX – reported when lexer internal buffer could not be allocated
LEXER_ALLOC_ERROR_OUT – reported when lexer output buffer could not be allocated
Parser error codes
PARSE_ERROR – returned by parser on grammar error
NEED_MORE_SYMBOLS – returned by parser in push mode, when next input token is required. This is not an error. User should provide next input token and reinvoke the parser.
SYMBOL_ALREADY_PRESENT – returned by parser in push mode to indicate, that parser already has a token. User should reinvoke the parser without token (that is with token value of zero).
PARSER_ALLOC_ERROR_STACK – reported when parser stack could not be reallocated
PARSER_ALLOC_ERROR_DATA – reported when parser value data storage could not be allocated