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


16.6 Sequence methods

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

When successful, returns

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 if 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 if 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 number). 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 )

When successful, adds a new sequence rule to grammar g, and returns its ID. 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. This is intended to make it convenient for applications to store additional information about a grammar’s rules in an array. Within each grammar, the following is true:

The LHS of the sequence is lhs_id, and the item to be repeated on the RHS of the sequence is rhs_id. The sequence must be repeated at least min times, where min is 0 or 1. The sequence RHS, or item, is restricted to a single symbol, and that symbol cannot be nullable. If separator_id is non-negative, it is a separator symbol, which cannot be nullable. flags is a bit vector. Use of any other bit except MARPA_PROPER_SEPARATION results in undefined behavior.

By default, a 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 unless a separator symbol has also been specified.

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 if there is no separator. The causes of hard failure include rule_id not being well-formed; rule_id not being the ID of a rule that exists; and rule_id not being 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

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.


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