18.8 Precomputing the Grammar

Accessor function: int marpa_g_has_cycle (Marpa_Grammar g)

On success, returns a boolean which is 1 iff g has a cycle. Parsing with a grammar that contains a cycle is deprecated. See Cycles.

For diagnostic purposes, it is useful to determine which rules are in the cycle. marpa_g_rule_is_loop() can be used for for this purpose. See marpa_g_rule_is_loop.

Return value: On success, a boolean. On hard failure, -2.

Accessor function: int marpa_g_is_precomputed (Marpa_Grammar g)

Return value: On success, a boolean which is 1 iff grammar g is precomputed. On hard failure, -2.

Mutator function: int marpa_g_precompute (Marpa_Grammar g)

Precomputation involves running a series of grammar checks and “precomputing” some useful information which is kept internally to save repeated calculations. After precomputation, the grammar is “frozen” in many respects, and many grammar mutators that succeed before precomputation will cause hard failures after precomputation. Precomputation is necessary for a recognizer to be generated from a grammar.

On success, and on fully recoverable hard failure, does the following:

• Precomputes the grammar g.
• Clears any events that were in the event queue at the beginning of this method call.
• Returns zero or more events.
• Returns a value as described in this method’s return value summary.

The types of event that this method may return are MARPA_EVENT_LOOP_RULES, MARPA_EVENT_COUNTED_NULLABLE, and MARPA_EVENT_NULLING_TERMINAL. All of these events occur only on failure. Events may be queried using the marpa_g_event() method. See marpa_g_event().

The fully recoverable hard failure is MARPA_ERR_GRAMMAR_HAS_CYCLE. While this method precomputes the grammar for fully recoverable hard failures, parsing with a grammar that has a cycle is deprecated. Applications should treat MARPA_ERR_GRAMMAR_HAS_CYCLE as a library-recoverable error. A MARPA_ERR_GRAMMAR_HAS_CYCLE error occurs iff at least one MARPA_EVENT_LOOP_RULES event occurs. For more details on cycles, see Cycles.

The error code MARPA_ERR_COUNTED_NULLABLE is library-recoverable. This failure occurs when a symbol on the RHS of a sequence rule is nullable, which Libmarpa does not allow in a grammar. Error code MARPA_ERR_COUNTED_NULLABLE occurs iff one or more MARPA_EVENT_COUNTED_NULLABLE events occur. There is one MARPA_EVENT_COUNTED_NULLABLE event for every symbol that is a nullable on the right hand side of a sequence rule. An application may use these events to inform the user of the problematic symbols, and this detail may help the user fix the grammar.

The error code MARPA_ERR_NULLING_TERMINAL occurs only if LHS terminals are enabled. The LHS terminals feature is deprecated. See LHS terminals. Error code MARPA_ERR_NULLING_TERMINAL is library-recoverable. One or more MARPA_EVENT_NULLING_TERMINAL events will occur iff this method fails with error code MARPA_ERR_NULLING_TERMINAL. See Nulling terminals.

Among the other error codes that may case this method to fail are the following:

• MARPA_ERR_NO_RULES: The grammar has no rules.
• MARPA_ERR_NO_START_SYMBOL: No start symbol was specified.
• MARPA_ERR_INVALID_START_SYMBOL: A start symbol ID was specified, but it is not the ID of a valid symbol.
• MARPA_ERR_START_NOT_LHS: The start symbol is not on the LHS of any rule.
• MARPA_ERR_UNPRODUCTIVE_START: The start symbol is not productive.

More details of these can be found under the description of the appropriate code. See External error codes.

Return value: On success, a non-negative integer, whose value is otherwise unspecified. On hard failure, -2. For the error code MARPA_ERR_GRAMMAR_HAS_CYCLE, the hard failure is fully recoverable. For the error codes MARPA_ERR_COUNTED_NULLABLE and MARPA_ERR_NULLING_TERMINAL, the hard failure is library-recoverable.