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]