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

11.6 Sequences

Function: int marpa_g_rule_is_proper_separation ( Marpa_Grammar g, Marpa_Rule_ID rule_id)

Success returns: marpa_g_rule_is_proper_separation() 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.

The marpa_g_rule_is_proper_separation() does not distinguish rules without proper separation from rules for which separation is not defined, because they are not sequence rules. Applications for which this distinction is important should use the marpa_g_sequence_min() method.

Failure returns: If rule_id is well-formed, but there is no such rule, returns -1. On other failure, -2.

Function: int marpa_g_sequence_min ( Marpa_Grammar g, Marpa_Rule_ID rule_id)

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.

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 )

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.

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.

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 LHS, marpa_g_sequence_new() fails, setting the error code to MARPA_ERR_SEQUENCE_LHS_NOT_UNIQUE.

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 with the marpa_g_sequence_new() method, 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.

Function: int marpa_g_sequence_separator ( Marpa_Grammar g, Marpa_Rule_ID rule_id)

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.

Function: int marpa_g_symbol_is_counted (Marpa_Grammar g, Marpa_Symbol_ID sym_id)

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.

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