Next: Prediction events, Previous: Completion events, Up: Events [Contents][Index]
Allows the user to deactivate and reactivate symbol nulled events in the grammar. When a recognizer is created, the activation status of each of its events is initialized to the activation status of that event in the base grammar. If reactivate is zero, the event is deactivated in the grammar. If reactivate is one, the event is activated in the grammar.
Symbol nulled events are active by default if the symbol was set up for nulled events in the grammar. If a symbol was not set up for nulled events in the grammar, symbol nulled events are inactive by default and any attempt to change that is a fatal error.
The activation status of a nulled event in the grammar can only be changed if the symbol is marked as a nulled event symbol in the grammar, and before the grammar is precomputed. However, if a symbol is marked as a nulled event symbol in the recognizer, the nulled event can be deactivated and reactivated in the recognizer.
Success cases: On success, the method returns the value of reactivate. The method succeeds trivially if the symbol is already set as indicated by reactivate.
Failure cases: If the active status of the nulled event for sym_id cannot be set as indicated by reactivate, the method fails. On failure, -2 is returned.
Allows the user to deactivate and reactivate symbol nulled events in the recognizer. If boolean is zero, the event is deactivated. If boolean is one, the event is activated.
Symbol nulled events are active by default if the symbol was set up for nulled events in the grammar. If a symbol was not set up for nulled events in the grammar, symbol nulled events are inactive by default and any attempt to change that is a fatal error.
Success cases: On success, the method returns the value of boolean. The method succeeds trivially if the symbol is already set as indicated by boolean.
Failure cases: If the active status of the nulled event for sym_id cannot be set as indicated by boolean, the method fails. On failure, -2 is returned.
Libmarpa can set up to generate
an MARPA_EVENT_SYMBOL_NULLED
event whenever the symbol is nulled.
A symbol is said to be nulled
when a zero length instance of that symbol
is recognized.
For nulled events to occur, the symbol must be marked
as a nulled event symbol.
The
marpa_g_symbol_is_nulled_event_set()
function
marks symbol sym_id as a nulled event symbol
if value is 1,
and unmarks it
it as a nulled event symbol if value is 0.
The
marpa_g_symbol_is_nulled_event()
method
returns the current value of the nulled event marking
for symbol sym_id.
Marking a nulled event sets its activation status to on. Unmarking a nulled event sets its activation status to off. The nulled event marking cannot be changed once the grammar is precomputed.
If a nulled event is marked,
its activation status can be changed using the
marpa_g_nulled_symbol_activate()
method.
Note that, if a symbol is marked as a nulled event symbol
in the recognizer,
its nulled event can be deactivated
and reactivated in the recognizer.
As a reminder, a symbol instance is a symbol at a specific location in the input, and with a specific length. Also, whenever a nulled symbol instance is recognized at a location, it is acceptable at that location, and vice versa.
When a symbol instance is recognized at a location, it will generate a nulled event or a prediction event, but never both. A symbol instance of zero length, when recognized at a location, generates a nulled event at that location, and does not generate a completion event. A symbol instance of non-zero length, when acceptable at a location, generates a completion event at that location, and does not generate a nulled event.
When a symbol instance is acceptable at a location, it will generate a nulled event or a prediction event, but never both. A symbol instance of zero length, when acceptable at a location, generates a nulled event at that location, and does not generate a prediction event. A symbol instance of non-zero length, when acceptable at a location, generates a prediction event at that location, and does not generate a nulled event.
While it is not possible for a symbol instance to generate both a nulled event and a completion event at a location, it is quite possible that a symbol might generate both kinds of event at that location. This is because multiple instances of the same symbol may be recognized at a given location, and these instances will have different lengths. If one instance is recognized at a given location as zero length and a second, non-zero-length, instance is recognized at the same location, the first will generate only nulled events, while the second will generate only completion events. For similar reasons, while a symbol instance will never generate both a null event and a prediction event at a location, multiple instances of the same symbol may do so.
Zero length derivations can be ambiguous. When a zero length symbol is recognized, all of its zero-length derivations are also considered to be recognized.
The
marpa_g_symbol_is_nulled_event_set()
method will
mark a symbol as a nulled event symbol,
even if the symbol is non-nullable.
This is convenient, for example,
for automatically generated grammars.
Applications which wish to treat
it as a failure if there is an
attempt to
mark a non-nullable symbol
as a nulled event symbol,
can check for this case using
the
marpa_g_symbol_is_nullable()
method.
Success: On success, 1 if symbol sym_id is a nulled event symbol after the call, 0 otherwise.
Failures: If sym_id is well-formed, but there is no such symbol, -1. If the grammar g is precomputed; or on other failure, -2.
Next: Prediction events, Previous: Completion events, Up: Events [Contents][Index]