#5 setFailAction

[Peter]

Support a method setFailAction(func) taking a single
function as argument exactly as the setParseAction() does.

setFailActions should be functions having the same three
arguments as setParseActions: func(s, loc, doActions)
's' is the string to parse, 'loc' is the location at
which the failing element was called, and doActions is
the same as it was when the failing element was called.

The fail action function should be able to return one
of three instructions to the parser:

1) NO-OP: Raise the default 'did not match' exception
(as if no setFailAction had been specified

2) FATAL: Raise a fatal error to terminate parsing

3) RECOVERY: Tell the parser to try again from loc
(func having changed the input string).

I don't know if 3) is feasible/desirable with PyParsing
but it does complete the picture.

[Paul McGuire]

Logged In: YES
user_id=893320

I have implemented a setFailAction method to be included
in the next release. The fail action will be passed the
following args (from the updated docs):
- s - string being parsed
- loc - location where expression match was attempted and
failed
- expr - the parse expression that failed
- err - the exception thrown

The implementation supports your first 2 "return" options,
but uses the existing exception mechanisms. NO-OP equates
to just the fail action just returning normally with no
exception; FATAL equates to the fail action raising a
ParseFatalException. I will wait and see what kind of use
cases come up for this feature before I add support for
multiple fail actions (as has been added for parse
actions) or RECOVERY mode, but if necessary, I would
probably implemente RECOVERY as a new kind of exception to
be raised in the fail action. BTW, it is not possible to
change the input string directly in the fail action -
Python strings are still immutable and there is no way for
the fail action to change the string being parsed. But,
this could be done by passing back a modified string in
the RetryFailedExpressionException. It is also possible to
change the parser grammar dynamically. This already
exists in some of the examples, and this feature is
utilized in the implementation of the recently released
countedArray helper (if you want to see an example of a
dynamically mutable grammar).

This next release is getting rather complicated and large -
it may merit being a point release (1.5) instead of just
a subpoint release (1.4.3). I do not mean to imply any
lack of forward compatibility - other than finally getting
rid of parse actions that return both loc and tokens,
there are no intended incompatibilities in the next
release.

-- Paul

[Paul McGuire]

Logged In: YES
user_id=893320

Feature shipped in version 1.4.3.

-- Paul