18.6 Sequence methods

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

When successful, returns

• 1 if rule_id is the ID of a sequence rule whose proper separation flag is set,
• 0 if rule_id is the ID of a sequence rule whose proper separation flag is not set,
• 0 if rule_id is the ID of a rule that is not a sequence rule.

Does not distinguish sequence rules without proper separation from non-sequence rules. That is, does not distinguish an unset proper separation flag from a proper separation flag whose value is unspecified because rule_id is the ID of a BNF rule. Applications that want to determine whether or not a rule is a sequence rule can use marpa_g_sequence_min() to do this. See marpa_g_sequence_min().

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, 1 or 0. On soft failure, -1. On hard failure, -2.

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

On success, returns the mininum length of a sequence rule. Soft fails iff a rule with ID rule_id exists, but is not a sequence rule. This soft failure can used to test whether or not a rule is a sequence rule.

Hard fails irrecoverably if rule_id is not well-formed (a non-negative integer). Also, hard fails irrecoverably if no rule with ID rule_id exists, even when rule_id is well formed. Note that, in its handling of the non-existence of a rule for its rule argument, this method differs from many of the other grammar methods. Grammar methods that take a rule ID argument more often treat the non-existence of rule for a well-formed rule ID as a soft, recoverable, failure.

Return value: On success, the minimum length of the sequence rule with ID rule_id, which is always non-negative. On soft failure, -1. On hard failure, -2.

Mutator function: Marpa_Rule_ID marpa_g_sequence_new (Marpa_Grammar g, Marpa_Symbol_ID lhs_id, Marpa_Symbol_ID rhs_id, Marpa_Symbol_ID separator_id, int min, int flags )

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

• This method creates a new sequence 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 ID of the symbol to be repeated on the RHS of the sequence will be rhs_id. It is a irrecoverable hard error if rhs_id is the ID of a nullable symbol.
• The sequence must be repeated at least min times. min must be 0 or 1.
• If separator_id is a non-negative integer, it is the ID of a separator symbol. It is a irrecoverable hard error if separator_id is the ID of a nullable symbol.
• flags is treated as a bit vector. The behavior when any bit other than MARPA_PROPER_SEPARATION is set is undefined.
• By default, the sequence rule recognizes a trailing separator. If flags & MARPA_PROPER_SEPARATION is non-zero, separation is “proper”. Proper separation means the the rule does not recognize a trailing separator. Specifying proper separation has no effect if a separator symbol has not been specified.
• The return value of this method is the ID of the new rule.

In addition to sequence rules, Marpa also allows BNF rules, which are created by the marpa_g_rule_new() method. See marpa_g_rule_new(). We call marpa_g_rule_new() and marpa_g_sequence_new() rule creation methods. For details on the use of sequence rules, see Sequence rules.

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.

The LHS symbol cannot be the LHS of any other rule, whether a BNF rule or a sequence rule. On an attempt to create an sequence rule with a duplicate LHS, this method hard fails, with an error code of MARPA_ERR_SEQUENCE_LHS_NOT_UNIQUE.

Return value: On success, the ID of the newly added sequence rule, which is always non-negative. On hard failure, -2.

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

On success, returns the symbol ID of the separator of the sequence rule with ID rule_id. Soft fails iff there is no separator. Hard fails if rule_id is a negative integer; if rule_id is not the ID of a rule that exists; or if rule_id is not the ID a sequence rule.

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

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

On success, returns a boolean whose value is 1 iff the symbol with ID sym_id is counted. A symbol is counted iff

• it appears on the RHS of a sequence rule, or
• it is used as the separator symbol of a sequence rule.

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

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