Next: , Previous: , Up: Grammar methods   [Contents]


11.7 Ranks

Function: Marpa_Rank marpa_g_rule_rank_set ( Marpa_Grammar g, Marpa_Rule_ID rule_id, Marpa_Rank rank)
Function: Marpa_Rank marpa_g_rule_rank ( Marpa_Grammar g, Marpa_Rule_ID rule_id)

These methods, respectively, set and query the rank of a rule rule_id. When rule_id is created, its rank initialized to the default rank of the grammar.

Initially, the default rank of the grammar is 0. Methods to reset the grammar’s default rank are currently in the experimental stage.

Return value: On success, returns the rank after the call, and sets the error code to MARPA_ERR_NONE. On failure, returns -2, and sets the error code to an appropriate value, which will never be MARPA_ERR_NONE. Note that when the rank is -2, the error code is the only way to distinguish success from failure. The error code can be determined by using the marpa_g_error() call.

Function: int marpa_g_rule_null_high_set ( Marpa_Grammar g, Marpa_Rule_ID rule_id, int flag)
Function: int marpa_g_rule_null_high ( Marpa_Grammar g, Marpa_Rule_ID rule_id)

These methods, respectively, set and query the “null ranks high” setting of the rule rule_id. The “null ranks high” setting is either 0 or 1. When rule_id is created, its “null ranks high” setting is initialized to 0.

The “null ranks high” setting affects the ranking of rules with properly nullable symbols on their right hand side. If a rule has properly nullable symbols on its RHS, each instance in which it appears in a parse will have a pattern of nulled and non-nulled symbols. Such a pattern is called a “null variant”.

If the “null ranks high” setting is 0 (the default), nulled symbols rank low. If the “null ranks high” setting is 1, nulled symbols rank high. Ranking of a null variants is done from left-to-right.

The marpa_g_rule_null_high_set() method will return failure after the grammar has been precomputed. If there is no other cause of failure, the marpa_g_rule_null_high() method succeeds on both precomputed and unprecomputed grammars.

Success return value: The value of the “null ranks high” flag after the call.

Failure return value: If rule_id is well-formed, but there is no such rule, -1. On all other failures, -2.

11.8 Events

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. 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 completion events are active by default if the symbol was set up for completion events in the grammar. If a symbol was not set up for completion events in the grammar, symbol completion events are inactive by default and any attempt to change that is a fatal error.

The activation status of a completion event in the grammar can only be changed if the symbol is marked as a completion event symbol in the grammar, and before the grammar is precomputed. However, if a symbol is marked as a completion event symbol in the recognizer, the completion 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 completion event for sym_id cannot be set as indicated by reactivate, the method fails. On failure, -2 is returned.

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. 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.

Function: int marpa_g_prediction_symbol_activate ( Marpa_Grammar g, Marpa_Symbol_ID sym_id, int reactivate )

Allows the user to deactivate and reactivate symbol prediction 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 prediction events are active by default if the symbol was set up for prediction events in the grammar. If a symbol was not set up for prediction events in the grammar, symbol prediction events are inactive by default and any attempt to change that is a fatal error.

The activation status of a prediction event in the grammar can only be changed if the symbol is marked as a prediction event symbol in the grammar, and before the grammar is precomputed. However, if a symbol is marked as a prediction event symbol in the recognizer, the prediction 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 prediction event for sym_id cannot be set as indicated by reactivate, the method fails. On failure, -2 is returned.

Function: int marpa_g_symbol_is_completion_event ( Marpa_Grammar g, Marpa_Symbol_ID sym_id)
Function: int marpa_g_symbol_is_completion_event_set ( Marpa_Grammar g, Marpa_Symbol_ID sym_id, int value)

Libmarpa can be set up to generate an MARPA_EVENT_SYMBOL_COMPLETED event whenever the symbol is completed. A symbol is said to be completed when a non-nulling rule with that symbol on its LHS is completed.

For completion events to occur, the symbol must be marked as a completion event symbol. The marpa_g_symbol_is_completion_event_set() function marks symbol sym_id as a completion event symbol if value is 1, and unmarks it it as a completion event symbol if value is 0. The marpa_g_symbol_is_completion_event() method returns the current value of the completion event marking for symbol sym_id.

Marking a completion event sets its activation status to on. Unmarking a completion event sets its activation status to off. The completion event marking cannot be changed once the grammar is precomputed.

If a completion event is marked, its activation status can be changed using the marpa_g_completion_symbol_activate() method. Note that, if a symbol is marked as a completion event symbol in the recognizer, its completion event can be deactivated and reactivated in the recognizer.

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

Success: On success, 1 if symbol sym_id is a completion 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.

Function: int marpa_g_symbol_is_nulled_event ( Marpa_Grammar g, Marpa_Symbol_ID sym_id)
Function: int marpa_g_symbol_is_nulled_event_set ( Marpa_Grammar g, Marpa_Symbol_ID sym_id, int value)

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.

Function: int marpa_g_symbol_is_prediction_event ( Marpa_Grammar g, Marpa_Symbol_ID sym_id)
Function: int marpa_g_symbol_is_prediction_event_set ( Marpa_Grammar g, Marpa_Symbol_ID sym_id, int value)

Libmarpa can be set up to generate a MARPA_EVENT_SYMBOL_PREDICTED event when a non-nulled symbol is predicted. A non-nulled symbol is said to be predicted when a instance of it is acceptable at the current earleme according to the grammar. Nulled symbols do not generate predictions.

For predicted events to occur, the symbol must be marked as a predicted event symbol. The marpa_g_symbol_is_predicted_event_set() function marks symbol sym_id as a predicted event symbol if value is 1, and unmarks it it as a predicted event symbol if value is 0. The marpa_g_symbol_is_predicted_event() method returns the current value of the predicted event marking for symbol sym_id.

Marking a prediction event sets its activation status to on. Unmarking a prediction event sets its activation status to off. The prediction event marking cannot be changed once the grammar is precomputed.

If a prediction event is marked, its activation status can be changed using the marpa_g_prediction_symbol_activate() method. Note that, if a symbol is marked as a prediction event symbol in the recognizer, its prediction event can be deactivated and reactivated in the recognizer.

Success: On success, 1 if symbol sym_id is a predicted 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: , Previous: , Up: Grammar methods   [Contents]