18.5 Rule methods

Accessor function: int marpa_g_highest_rule_id (Marpa_Grammar g)

Return value: On success, the maximum rule ID of g. On hard failure, -2.

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

On success, does the following:

• If the rule whose ID is rule_id is accessible, returns 1.
• If the rule whose ID is rule_id is inaccessible, returns 0.

Soft fails iff rule_id is well-formed (a non-negative integer), but a rule with that ID does not exist. A common hard failure is calling this method with a grammar that is not precomputed.

Return value: On success, 1 or 0. On soft failure, -1. On hard failure, -2.

Accessor function: int marpa_g_rule_is_nullable ( Marpa_Grammar g, Marpa_Rule_ID ruleid)

On success, does the following:

• If the rule whose ID is rule_id is nullable, returns 1.
• If the rule whose ID is rule_id is non-nullable, returns 0.

Soft fails iff rule_id is well-formed (a non-negative integer), but a rule with that ID does not exist. A common hard failure is calling this method with a grammar that is not precomputed.

Return value: On success, 1 or 0. On soft failure, -1. On hard failure, -2.

Accessor function: int marpa_g_rule_is_nulling (Marpa_Grammar g, Marpa_Rule_ID ruleid)

On success, does the following:

• If the rule whose ID is rule_id is nulling, returns 1.
• If the rule whose ID is rule_id is non-nulling, returns 0.

Soft fails iff rule_id is well-formed (a non-negative integer), but a rule with that ID does not exist. A common hard failure is calling this method with a grammar that is not precomputed.

Return value: On success, 1 or 0. On soft failure, -1. On hard failure, -2.

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

On success, does the following:

• If the rule whose ID is rule_id is a loop rule, returns 1.
• If the rule whose ID is rule_id is not a loop rule, returns 0.

A rule is a loop rule iff it non-trivially produces the string of length one that consists only of its LHS symbol. The presence of a loop rule indicates that g contains a cycle. Parsing with a grammar that contains a cycle is deprecated. marpa_g_rule_is_loop should only be used for diagnostic purposes, to allow a user to find the rules which cause the cycle and to change the grammar to be cycle-free. See Cycles.

Soft fails iff rule_id is well-formed (a non-negative integer), but a rule with that ID does not exist. A common hard failure is calling this method with a grammar that is not precomputed.

Return value: On success, 1 or 0. On soft failure, -1. On hard failure, -2.

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

On success, does the following:

• If the rule whose ID is rule_id is productive, returns 1.
• If the rule whose ID is rule_id is unproductive, returns 0.

Soft fails iff rule_id is well-formed (a non-negative integer), but a rule with that ID does not exist. A common hard failure is calling this method with a grammar that is not precomputed.

Return value: On success, 1 or 0. On soft failure, -1. On hard failure, -2.

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

On success, returns the length of the rule with ID rule_id. The length of a rule is the length of its RHS.

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, the length of the rule with ID rule_id, which is always a non-negative integer. On soft failure, -1. On hard failure, -2.

Accessor function: Marpa_Symbol_ID marpa_g_rule_lhs ( Marpa_Grammar g, Marpa_Rule_ID rule_id)

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 the ID of the LHS symbol of the rule with ID rule_id in grammar g. A symbol ID is always a non-negative integer. On soft failure, -1. On hard failure, -2.

Mutator function: Marpa_Rule_ID marpa_g_rule_new (Marpa_Grammar g, Marpa_Symbol_ID lhs_id, Marpa_Symbol_ID *rhs_ids, int length)

marpa_g_rule_new() is one of the rule creation methods. On success, the following are true:

• This method creates a new BNF rule in grammar g.
• This method gives the new rule an ID.
• The ID of the new rule is a non-negative integer, which is unique to that rule.
• If grammar g had no rules when this method was called, the new rule will have ID 0.
• If grammar g had one or more rules when this method was called, let n be the maximum rule ID in grammar g when this method was called. Then the new rule will have rule ID n+1.
• The ID of the LHS symbol of the new rule will be lhs_id.
• The length of the RHS of the new rule will be length.
• For 0 <= i < length, the ID of the RHS symbol with index i will be rhs_ids[i].
• The return value of this method is the ID of the new rule.

In addition to BNF rules, Marpa also allows sequence rules, which are created by the marpa_g_sequence_new() method. See marpa_g_sequence_new(). We call marpa_g_rule_new() and marpa_g_sequence_new() rule creation methods. Sequence rules and BNF rules are both rules: They share the same series of rule IDs, and are accessed and manipulated by the same methods, with the only differences being as noted in the descriptions of those methods.

Each grammar’s rule ID’s are a consecutive sequence of non-negative integers, starting at 0. The consecutive numbering of rule ID’s is intended to make it convenient for applications to store additional information about a grammar’s rules in an array.

Possible hard failures, with their error codes, include:

• MARPA_ERR_SEQUENCE_LHS_NOT_UNIQUE: The LHS symbol is the same as that of a sequence rule.
• MARPA_ERR_DUPLICATE_RULE: The new rule would duplicate another BNF rule. Another BNF rule is considered the duplicate of the new one, if its LHS symbol is the same as symbol lhs_id, if its length is the same as length, and if its RHS symbols match one for one those in the array of symbols rhs_ids.

Return value: On success, the ID of the new rule, which is always a non-negative integer. On hard failure, -2.

Accessor function: Marpa_Symbol_ID marpa_g_rule_rhs ( Marpa_Grammar g, Marpa_Rule_ID rule_id, int ix)

When successful, returns the ID of the symbol at index ix in the RHS of the rule with ID rule_id. The indexing of RHS symbols is zero-based.

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

Hard fails if ix is not a valid index of the RHS. This happens if ix is less than zero, or if ix is greater than or equal to the length of the rule.

Return value: On success, a symbol ID, which is always non-negative. On soft failure, -1. On hard failure, -2.