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


13 Progress reports

An important advantage of the Marpa algorithm is the ability to easily get full information about the state of the parse.

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

To get the information in a progress report, it is necessary to step through the progress report items. To get the data for the current progress report item, and advance to the next one, use the marpa_r_progress_item() method.

To destroy a progress report, freeing the memory it uses, call the marpa_r_progress_report_finish() method.

Function: int marpa_r_progress_report_reset ( Marpa_Recognizer r)

Resets the progress report. Assumes a report of the progress has already been initialized at some Earley set for recognizer r, with marpa_r_progress_report_start(). The reset progress report will be positioned before its first item.

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

Function: int marpa_r_progress_report_start ( Marpa_Recognizer r, Marpa_Earley_Set_ID set_id)

Initializes a report of the progress at Earley set set_id for recognizer r. If a progress report already exists, it is destroyed and its memory is freed. Initially, the progress report is positioned before its first item.

If no Earley set with ID set_id exists, marpa_r_progress_report_start() fails. 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 available. If the recognizer has not been started; if set_id does not exist; or on other failure, -2.

Function: int marpa_r_progress_report_finish ( Marpa_Recognizer r )

Destroys the report of the progress at Earley set set_id for recognizer r, freeing the memory and other resources. It is often not necessary to call this method. Any previously existing progress report is destroyed automatically whenever a new progress report is started, and when the recognizer is destroyed.

Return value: -2 if no progress report has been started, or on other failure. On success, a non-negative value.

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 item of a progress report. If there are no more progress report items, it returns -1 as a termination indicator and sets the error code to MARPA_ERR_PROGRESS_REPORT_EXHAUSTED. Either the termination indicator, or the item count returned by marpa_r_progress_report_start(), can be used to determine when the last item has been seen.

On success, the dot position is returned in the location pointed to by the position argument, and the origin is returned in the location pointed to by the origin argument. On failure, the locations pointed to by the position and origin arguments are unchanged.

Return value: On success, the rule ID of the next progress report item. If there are no more progress report items, -1. If either the position or the origin argument is NULL, or on other failure, -2.


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