20.2 Progress report methods

Mutator function: int marpa_r_progress_report_reset ( Marpa_Recognizer r)

On success, sets the current node of the report traverser to the start sentinel. See Progress report traverser.

This method is not usually needed. Its effect is to leave the traverser in the same state as it is immediately after the marpa_r_progress_report_start() method. Loosely speaking, it allows the traversal to “start over”.

Hard fails if the recognizer is not started, or if no progress report traverser is active.

Return value: On success, a non-negative value. On failure, -2.

Mutator function: int marpa_r_progress_report_start ( Marpa_Recognizer r, Marpa_Earley_Set_ID set_id)

Creates a progress report traverser in recognizer r for the Earley set with ID set_id.

On success, does the following:

• If a progress report traverser was active in recognizer r before this method call, destroys it and frees its memory.
• Creates a new progress report traverser from the Earley items for the Earley set with ID set_id.
• Sets the current node of the traverser to the start sentinel. Intuitively, for a non-empty Earley set, this can be thought of as positioning the traverser before the first Earley item.
• Returns n, the number of Earley items. n may be zero.

Hard fails if no Earley set with ID set_id exists. The error code is MARPA_ERR_INVALID_LOCATION if set_id is negative. The error code is MARPA_ERR_NO_EARLEY_SET_AT_LOCATION if set_id is greater than the ID of the latest Earley set.

Return value: On success, the number of Earley items, which will always be non-negative. On hard failure, -2.

Mutator function: int marpa_r_progress_report_finish ( Marpa_Recognizer r )

On success, destroys the progress report traverser for recognizer r, freeing its memory. For details about the report traverser, see marpa_r_progress_report_start().

It is often not necessary to call this method. marpa_r_progress_report_start() destroys any previously existing progress report. And, when a recognizer is destroyed, its progress report is destroyed as a side effect.

Hard fails if no progress report is active.

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

Mutator function: Marpa_Rule_ID marpa_r_progress_item ( Marpa_Recognizer r, int* position, Marpa_Earley_Set_ID* origin )

This method allows access to the data for the next progress report item of a progress report. See Progress report traverser.

Let oldCurrent be the current node of the progress report traverser in r when this method was called. Let oldNext be the next link of oldCurrent. If oldCurrent is the end sentinel, oldNext is not defined, and this method soft fails.

In the event of success:

• Sets the current node of the traverser to oldNext. We will call this new value of the current node, newCurrent.
• Writes the “cooked dot position” of the Earley item corresponding to newCurrent to the location pointed to by the position argument.
• Writes the origin of the Earley item corresponding to newCurrent to the location pointed to by the origin argument.
• Returns the rule ID of the Earley item corresponding to newCurrent.

The “cooked dot position” is

• the standard 0-based start-relative dot position, if the dotted rule is not a completion; and
• -1, if the dotted rule is a completion. This has the advantage of making it easy for the application to determine if the dotted rule is a completion. An application that prefers the “raw” 0-based start-relative dot position may convert a -1 to the rule length. See marpa_g_rule_length().

In the event of soft failure:

• Sets the current node to the end sentinel.
• Sets the error code to MARPA_ERR_PROGRESS_REPORT_EXHAUSTED.
• Leaves unchanged the locations pointed to by the position and origin arguments.
• Returns -1.

In addition to watching for soft failure, the application can use the item count returned by marpa_r_progress_report_start() to determine when the last item has been seen.

Return value: On success, the rule ID of the progress report item, which is always non-negative. On soft failure, -1. If either the position or the origin argument is NULL, or on other hard failure, -2.