18.7 Rank methods

Accessor function: Marpa_Rank marpa_g_default_rank ( Marpa_Grammar g)

On success, returns the default rank of the grammar g. For more about the default rank of a grammar, see marpa_g_default_rank_set().

Return value: On success, returns the default rank of the grammar, which will be an integer, and sets the error code to MARPA_ERR_NONE. On hard failure, returns -2, and sets the error code to an appropriate value, which will never be MARPA_ERR_NONE. Note that when the default rank of the grammar 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. See marpa_g_error().

Mutator function: Marpa_Rank marpa_g_default_rank_set ( Marpa_Grammar g, Marpa_Rank rank)

On success, sets the default rank of the grammar g to rank. When a grammar is created, the default rank is 0. When rules and symbols are created, their rank is the default rank of the grammar.

Changing the grammar’s default rank does not affect those rules and symbols already created, only those that will be created. This means that the grammar’s default rank can be used to, in effect, assign ranks to groups of rules and symbols. Applications may find this behavior useful.

Return value: On success, returns rank, which will be an integer, 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. See marpa_g_error().

Accessor function: Marpa_Rank marpa_g_symbol_rank ( Marpa_Grammar g, Marpa_Symbol_ID sym_id)

When successful, returns the rank of the symbol with ID sym_id.

Return value: On success, returns a symbol rank, which will be an integer, and sets the error code to MARPA_ERR_NONE. On hard failure, returns -2, and sets the error code to an appropriate value, which will never be MARPA_ERR_NONE. Note that -2 is a valid symbol rank, so that when -2 is returned, the error code is the only way to distinguish success from failure. The error code can be determined using marpa_g_error(). See marpa_g_error().

Mutator function: Marpa_Rank marpa_g_symbol_rank_set ( Marpa_Grammar g, Marpa_Symbol_ID sym_id, Marpa_Rank rank)

When successful, sets the rank of the symbol with ID sym_id to rank.

Return value: On success, returns rank, which will be an integer, and sets the error code to MARPA_ERR_NONE. On hard failure, returns -2, and sets the error code to an appropriate value, which will never be MARPA_ERR_NONE. Note that rank may be -2, and in this case the error code is the only way to distinguish success from failure. The error code can be determined using marpa_g_error(). See marpa_g_error().

Accessor function: Marpa_Rank marpa_g_rule_rank ( Marpa_Grammar g, Marpa_Rule_ID rule_id)

When successful, returns the rank of the rule with ID rule_id.

Return value: On success, returns a rule rank, which will be an integer, and sets the error code to MARPA_ERR_NONE. On hard failure, returns -2, and sets the error code to an appropriate value, which will never be MARPA_ERR_NONE. Note that -2 is a valid rule rank, so that when -2 is returned, the error code is the only way to distinguish success from failure. The error code can be determined using marpa_g_error(). See marpa_g_error().

Mutator function: Marpa_Rank marpa_g_rule_rank_set ( Marpa_Grammar g, Marpa_Rule_ID rule_id, Marpa_Rank rank)

When successful, sets the rank of the rule with ID rule_id to rank.

Return value: On success, returns rank, which will be an integer, and sets the error code to MARPA_ERR_NONE. On hard failure, returns -2, and sets the error code to an appropriate value, which will never be MARPA_ERR_NONE. Note that -2 is a valid rule rank, so that when -2 is returned, the error code is the only way to distinguish success from failure. The error code can be determined using marpa_g_error(). See marpa_g_error().

Accessor function: int marpa_g_rule_null_high ( Marpa_Grammar g, Marpa_Rule_ID rule_id)

On success, returns a boolean whose value is 1 iff “null ranks high” is set in the rule with ID rule_id. When a rule is created, it has “null ranks high” set.

For more on the “null ranks high” setting, read the description of marpa_g_rule_null_high_set(). See marpa_g_rule_null_high_set().

Soft fails iff rule_id is well-formed (a non-negative integer), but a rule with that ID does not exist.

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

Mutator function: int marpa_g_rule_null_high_set ( Marpa_Grammar g, Marpa_Rule_ID rule_id, int flag)

On success,

• sets “null ranks high” in the rule with ID rule_id if the value of the boolean flag is 1;
• unsets “null ranks high” in the rule with ID rule_id if the value of the boolean flag is 0; and
• returns flag.

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” is set, nulled symbols rank high. If the “null ranks high” is unset (the default), nulled symbols rank low. Ranking of a null variants is done from left-to-right.

Soft fails iff rule_id is well-formed (a non-negative integer), but a rule with that ID does not exist.

Hard fails if the grammar has been precomputed.

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