Update docs on error handling
@@ -7,7 +7,7 @@ be performed it will report an error by raising an instance of
`ParseError` has the following attributes:
- **location** - an instance of the [Location class](./common.md#location-class)
- with information of the position and span of the error.
+ with information of the span of the error.
- **symbols_expected (list)** - a list of expected symbol at the location.
@@ -35,28 +35,30 @@ the valid state and continue.
To enable error recovery set `error_recovery` [parameter of parser
construction](./parser.md#error_recovery) to `True`. This will enable implicit
-error recovery strategy that will simply drop characther/object at the place of
-the error and try to continue. All errors will be collected as an `errors` list
-on the parser instance.
+error recovery strategy that will try to search for expected tokens in the input
+ahead and when the first is found the parsing will continue. All errors will be
+collected as an `errors` list on the parser instance.
Each error is an instance of [`ParseError` class](#handling-errors). In case no
-recovery is possible last `ParseError` will be raised.
+recovery is possible last `ParseError` will be raised. `ParserError` has a
+location which represents the span of the error in the input (e.g.
+`error.location.start_position` and `error.location.end_position`).
## Custom recovery strategy
-To provide a custom strategy for error recovery set `error_recovery` to a Python
-function. This function should have the following signature:
+To provide a custom strategy for error recovery set `error_recovery` parser
+constructor parameter to a Python function. This function should have the
+following signature:
def error_recovery_strategy(context, error):
...
-- **context** - the [context object](./common.md#the-context-object) at the
- place where error occurred.
+- **context***- context like object (usually the parser head).
- **error** - [`ParseError` instance](#handling-errors).
-Using the context object you can query the state of the parser. E.g. to get the
+Using the head object you can query the state of the parser. E.g. to get the
position use `context.position`, to get the parser state use `context.state`, to
get expected symbols in this state use `context.state.actions.keys()`.
@@ -64,16 +66,9 @@ To get information about the error use `error` object. E.g. to get expected
symbols at this position for which parser can succesfully continue use
`error.symbols_expected`.
-The recovery function should return the tuple `(token, position)`. `position`
-should be a new position where the parser should continue or `None` if position
-should not change. `token` should be a new token introduced at the given
-position or `None` if no new token is introduced. If both `token` and `position`
-are `None` error recovery didn't succeed.
-
-The `token` symbol should be from the `error.symbols_expected` for the parser to
-recover successfully. `token` should be an instance of
-[`parser.Token`](./parser.md#token). This class constructor accepts `symbol`,
-`value` and `length`. `symbol` should be a grammar symbol from
-`expected_symbols`, `value` should be a matched part of the input (actually, in
-the context of error recovery this value is a made-up value) and length is the
-length of the token. For introduced tokens, length should be set to 0.
+The recovery function should modify the head (e.g. its position and/or
+`token_ahead`) and bring it to a state which can continue. If the recovery is
+successful the function should return `True`, otherwise `False`.
+
+You can call a default error recovery from your custom recovery by
+`context.parser.default_error_recovery(context)`
