Next: Bocage methods, Previous: Recognizer methods, Up: Top [Contents][Index]
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.
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.
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:
n,
and we will write ritem[i]
for the i’th report item.
null for
the null vertex.
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
(null, ritem[0]),
(ritem[n-1], null), and
0 <= i < v-1, (ritem[i-1], ritem[i]).
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:
n, the number of report 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 report items, which will always be non-negative. On hard failure, -2.
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.
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:
c_before be the vertex
that is the current vertex immediately
before the call to this method.
The report item traverser has exactly one edge such that c_before
is its first element.
Let this edge be (c_before,c_after).
This method sets the current vertex to c_after.
In this method description, we will write current as an alias for c_after.
current will be a report item vertex and therefore there will
be an Earley item corresponding to current.
current
to the location pointed to by the position argument.
current
to the location pointed to by the origin argument.
current.
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:
current is the null vertex.
MARPA_ERR_PROGRESS_REPORT_EXHAUSTED.
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: Bocage methods, Previous: Recognizer methods, Up: Top [Contents][Index]