Next: , Previous: , Up: Top   [Contents][Index]


18 Progress reports

It is an important property of the Marpa algorithm that the Earley sets are added one at a time, so that before we have started the construction of the Earley set at n+1, we know the full state of the parse at and before location n. Libmarpa’s progress reports allow access to the Earley items in an Earley set.

To start a progress report, use the marpa_r_progress_report_start() command. For each recognizer, only one progress report can be in use at any one time.

To step through the Earley items, use the marpa_r_progress_item() method.

Mutator function: int marpa_r_progress_report_reset ( Marpa_Recognizer r)

On success, sets the current vertex of the report traverser to the null vertex. For more about the report traverser, including details about the current and null vertices, see marpa_r_progress_report_start().

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. A progress report traverser is a non-empty directed cycle graph whose vertices consist of the following:

There may be no Earley items in an Earley set, and therefore a progress report traverser may contain no report items. A progress report traverser with no report items is called a “trivial traverser”. A trivial traverser has exactly one edge: (null, null).

The edges of a non-trivial traverser are

This implies that every vertex has exactly one direct successor. The report items are a subgraph, and this graph can be seen as inducing the sequence ritem[0] ... ritem[n-1].

When a progress report traverser is active, one vertex is distinguished as the current vertex, which we will write as current. We call the direct successor of the current vertex, the next vertex.

On success, does the following:

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 report 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. For details about progress reports, see marpa_r_progress_report_start().

In the event of success:

The “cooked dot position” is

Use of the cooked dot position allows an application to quickly determine if the dotted rule is a completion. The cooked dot position is -1 iff the dotted rule is a completion.

In the event of soft failure:

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.


Next: , Previous: , Up: Top   [Contents][Index]