25.4 Completion events

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

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

To activate or deactivate a completion symbol event use the marpa_r_completion_symbol_activate() method.

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

Allows the user to deactivate and reactivate symbol completion 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 completion event in the grammar becomes the initial activation status of a completion event in all of its child recognizers.

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

Hard fails if the sym_id is not declared as a completion 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_completion_symbol_activate ( Marpa_Recognizer r, Marpa_Symbol_ID sym_id, int reactivate )

Allows the user to deactivate and reactivate symbol completion 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 sym_id was not declared for completion events in the base grammar.

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

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

On success, returns a boolean which is 1 iff sym_id is declared as a completion event symbol in g. For more about completion events, see marpa_g_symbol_is_completion_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_completion_event_set ( Marpa_Grammar g, Marpa_Symbol_ID sym_id, int value)

On success, if value is 1,

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

On success, if value is 0,

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

Nulled rules and symbols will never cause completion events. Nullable symbols may be declared as completion event symbols, but this will have an effect only when the symbol is not nulled. Nulling symbols may be declared as completion event symbols, but no completion events will ever be triggered for a nulling symbol. Note that this implies that no completion event will ever be triggered at earleme 0, the start of parsing.

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.