succeeds if and only if rule_id is valid.
If rule rule_id
is a sequence rule where the proper separation flag
is set, returns 1.
On other success,
including the case
where rule rule_id
is not a sequence rule, returns 0.
does not distinguish rules without proper
separation from rules for which separation
is not defined, because they are not
Applications for which this distinction is
important should use
Failure returns: If rule_id is well-formed, but there is no such rule, returns -1. On other failure, -2.
Returns the mininum length of a sequence rule. This accessor can be also be used to test whether or not a rule is a sequence rule. -1 is returned if and only if the rule is valid but not a sequence rule.
Return value: If rule rule_id is a sequence rule, its minimum length. If rule rule_id is valid, but is not the rule ID of sequence rule, -1. If rule_id is well-formed, but there is no such rule, or on other failure, -2.
Adds a new sequence rule to grammar g. The ID of the new sequence rule will be a non-negative integer, which is unique to that rule. Sequence rules and BNF 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.
The sequence is lhs_id, and the item to be repeated in 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.
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.
Some higher-level Marpa interfaces offer the ability to discard separators in the semantics, and in fact will do this by default. At the Libmarpa level, sequences always “keep separators”. It is up to the programmer to arrange to discard separators, if that is what is desired.
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 sequences are restricted because they lead to highly ambiguous grammars. Grammars of this kind are allowed by Libmarpa, but they must be expressed using BNF rules, not sequence rules. This is for two reasons: First, sequence optimizations would not work in the presence of nullables. Second, since it is not completely clear what an application intends when it asks for a sequence of identical items, some of which are nullable, the user’s intent can be more clearly expressed directly in BNF.
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
setting the error code to
Sequence rules do not add to the classes of grammar parsed
by Libmarpa —
a sequence can always be written as BNF rules.
When a rule is created
Libmarpa will understand that it is a sequence,
and will optimize accordingly.
The speedup is often considerable.
Return value: On success, the ID of the external rule. On failure, -2.
Return value: If rule rule_id is a sequence rule, its separator. If rule rule_id is a sequence rule, but there is no separator, -1. If rule_id is not a sequence rule, does not exist or is not well-formed; or on other failure, -2.
A symbol is counted if it appears on the RHS of a sequence rule, or if it is used as the separator symbol of a sequence rule.
Success return: Returns 1 if symbol sym_id is counted, 0 if not.
Failure return: If sym_id is well-formed, but there is no such symbol, -1. If sym_id is not well-formed, and on other failure, -2.