25.5 Symbol nulled events

This section contains methods for dealing with MARPA_EVENT_SYMBOL_NULLED events. See MARPA_EVENT_SYMBOL_NULLED.

To declare a symbol as a nulled event symbol use the marpa_g_symbol_is_nulled_event_set() method. The event will be activated by default.

To activate or deactivate a nulled symbol event use the marpa_r_nulled_symbol_activate() method.

Mutator function: int marpa_g_nulled_symbol_activate ( Marpa_Grammar g, Marpa_Symbol_ID sym_id, int reactivate )

Allows the user to deactivate and reactivate symbol nulled events in the grammar. On success, does the following:

• If reactivate is zero, deactivates the event in the grammar.
• If reactivate is one, activates the event in the grammar.

The activation status of a nulled event in the grammar becomes the initial activation status of a nulled event in all of its child recognizers.

This method is seldom needed. When a symbol is declared as a nulled event symbol in the grammar, it is activated by default. See marpa_g_symbol_is_nulled_event_set(). And a nulled event can be deactivated and reactivated in the recognizer using the marpa_r_nulled_symbol_activate method. See marpa_r_nulled_symbol_activate().

Hard fails if the sym_id is not declared as a nulled event symbol in the grammar, or if the grammar has not been precomputed.

Return value: On success, the value of reactivate, which is a boolean. On hard failure, -2.

Mutator function: int marpa_r_nulled_symbol_activate ( Marpa_Recognizer r, Marpa_Symbol_ID sym_id, int boolean )

Allows the user to deactivate and reactivate symbol nulled events in the recognizer. On success, does the following:

• If reactivate is zero, deactivates the event in the recognizer.
• If reactivate is one, activates the event in the recognizer.

Hard fails if the subtype sym_id of the MARPA_EVENT_SYMBOL_NULLED event is not declared.

Return value: On success, the value of reactivate, which is a boolean. On hard failure, -2.

Accessor function: int marpa_g_symbol_is_nulled_event ( Marpa_Grammar g, Marpa_Symbol_ID sym_id)

On success, returns a boolean which is 1 iff the subtype sym_id of the MARPA_EVENT_SYMBOL_NULLED event is declared. For more about nulled events, see marpa_g_symbol_is_nulled_event_set.

Soft fails iff sym_id is well-formed (a non-negative integer), but there is no such symbol.

Hard fails if g is precomputed.

Return value: On success, a boolean . On soft failure, -1. On hard failure, -2.

Mutator function: int marpa_g_symbol_is_nulled_event_set ( Marpa_Grammar g, Marpa_Symbol_ID sym_id, int value)

On success, if value is 1,

• declares symbol sym_id as a nulled event symbol,
• activates the nulled event for sym_id in g, and
• returns 1.

On success, if value is 0,

• declares symbol sym_id as a nulled event symbol,
• deactivates the nulled event for sym_id in g, and
• returns 0.

The marpa_g_symbol_is_nulled_event_set() method will declare a symbol as a nulled event symbol, even if the symbol is non-nullable. This is convenient, for example, for automatically generated grammars. Applications that wish to treat it as a failure when a non-nullable symbol is declared as a nulled event symbol, can check for this after precomputation, using the marpa_g_symbol_is_nulled_event() and marpa_g_symbol_is_nullable() methods.

Soft fails iff sym_id is well-formed (a non-negative integer), but there is no such symbol.

Hards fails if the grammar is precomputed.

Return value: On success, value, which is a boolean. On soft failure, -1. On hard failure, -2.