Next: Rank methods, Previous: Rule methods, Up: Grammar methods [Contents][Index]
[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.
[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.
[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.
[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.
[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: Rank methods, Previous: Rule methods, Up: Grammar methods [Contents][Index]