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


13.6 Sequence methods

Function: int marpa_g_rule_is_proper_separation ( Marpa_Grammar g, Marpa_Rule_ID rule_id)

[Accessor] 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 which value is undefined because rule_id is the ID of a BNF rule. Applications which 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.

Function: int marpa_g_sequence_min ( Marpa_Grammar g, Marpa_Rule_ID rule_id)

[Accessor] 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 which 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.

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 )

[Mutator] When successful, adds a new sequence rule to grammar g, and return its ID. The ID of the sequence rule will be a non-negative integer, which is unique to that rule. All rules are numbered in the same series, so that a BNF rule will never have the same rule ID as a sequence rule, and vice versa.

Sequence rules are “sugar” — their presence in the Libmarpa interface does not extend its power. Every Libmarpa grammar which can be written using sequence rules can be rewritten as a grammar without sequence rules.

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. If separator_id is non-negative, it is a separator symbol.

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.

The sequence RHS, or item, is restricted to a single symbol, and that symbol cannot be nullable. If separator_id is a symbol, it also cannot be a nullable symbol. Nullables on the RHS of sequence rules are prohibited because it is not completely clear what an application intends when it asks for a sequence of items, some of which are nullable — the most natural interpretation of this usually results in a highly ambiguous grammar.

Libmarpa allows highly ambiquous grammars and a programmer who wants a grammar with sequences containing nullable items or separators can can write that grammar using BNF rules. The use of BNF rules make it clearer that ambiguity is what the programmer intended, and allows the programmer more flexibility.

If flags & MARPA_PROPER_SEPARATION is non-zero, separation is “proper”, that is, a trailing separator is not allowed. The term proper is based on the idea that properly-speaking, separators should actually separate items. Proper separation has no effect at the Libmarpa level — it is tracked as a convenience for the higher-level interfaces to Libmarpa, which may want to offer the ability to discard separators in the semantics. (Some higher-level interfaces, in fact, may choose to discard separation by default.) At the Libmarpa level, sequences always “keep separators”.

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

Function: int marpa_g_sequence_separator ( Marpa_Grammar g, Marpa_Rule_ID rule_id)

[Accessor] 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 which 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.

Function: int marpa_g_symbol_is_counted (Marpa_Grammar g, Marpa_Symbol_ID sym_id)

[Accessor] 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]