.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Marpa::R2::Scanless::R 3pm"
.TH Marpa::R2::Scanless::R 3pm "2015-03-06" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "Name"
.IX Header "Name"
Marpa::R2::Scanless::R \- Scanless interface recognizers
.SH "Synopsis"
.IX Header "Synopsis"
.Vb 3
\&    my $recce = Marpa::R2::Scanless::R\->new( { grammar => $grammar } );
\&    my $self = bless { grammar => $grammar }, \*(AqMy_Actions\*(Aq;
\&    $self\->{recce} = $recce;
\&
\&    if ( not defined eval { $recce\->read($p_input_string); 1 }
\&        )
\&    {
\&        ## Add last expression found, and rethrow
\&        my $eval_error = $EVAL_ERROR;
\&        chomp $eval_error;
\&        die $self\->show_last_expression(), "\en", $eval_error, "\en";
\&    } ## end if ( not defined eval { $event_count = $recce\->read...})
\&
\&    my $value_ref = $recce\->value( $self );
\&    if ( not defined $value_ref ) {
\&        die $self\->show_last_expression(), "\en",
\&            "No parse was found, after reading the entire input\en";
\&    }
.Ve
.PP
.Vb 9
\&    package My_Actions;
\&    sub do_parens    { shift; return $_[1] }
\&    sub do_add       { shift; return $_[0] + $_[2] }
\&    sub do_subtract  { shift; return $_[0] \- $_[2] }
\&    sub do_multiply  { shift; return $_[0] * $_[2] }
\&    sub do_divide    { shift; return $_[0] / $_[2] }
\&    sub do_pow       { shift; return $_[0]**$_[2] }
\&    sub do_first_arg { shift; return shift; }
\&    sub do_script    { shift; return join q{ }, @_ }
.Ve
.SH "About this document"
.IX Header "About this document"
This page is the reference document for the recognizer objects
of Marpa's \s-1SLIF \s0(Scanless interface).
.SH "Internal and external scanning"
.IX Header "Internal and external scanning"
The Scanless interface is so-called because
it does not require the application to supply a scanner (lexer).
The \s-1SLIF\s0 contains its own lexer,
one whose use is integrated into
its syntax.
In this document, use of the \s-1SLIF\s0's
internal scanner is called
\&\fBinternal scanning\fR.
.PP
The \s-1SLIF\s0 allows applications that find it useful to
do their own scanning.
When an application
bypasses the \s-1SLIF\s0's internal scanner
and does its own scanning,
this document calls it
\&\fBexternal scanning\fR.
An application can use
external scanning to supplement internal 
scanning,
or to replace the \s-1SLIF\s0's internal scanner entirely.
.SH "Locations"
.IX Header "Locations"
.SS "Input stream locations"
.IX Subsection "Input stream locations"
An input stream location is the offset of a codepoint in the
input stream.
When the input stream is being treated as a string,
input stream location corresponds to Perl's \f(CW\*(C`pos()\*(C'\fR location.
In this document, the word \*(L"location\*(R" refers
to location in the input stream
unless otherwise specified.
.SS "Negative locations"
.IX Subsection "Negative locations"
Several methods allow locations and lengths to be specified
as negative numbers.
A negative location is a location counted
from the end, so that \-1 means location before the
last character of the string,
\&\-2 the location before the second to last character of a string, etc.
A negative length indicates a distance to a location
counted from the end.
A length of \-1 indicates the distance to the end of the string,
\&\-2 indicates the distance to the location just before
the last character
of the string,
etc.
.PP
For example, suppose that we are dealing with input stream locations.
The span (\f(CW\*(C`0, \-1\*(C'\fR) is the entire input stream.
The span (\f(CW\*(C`\-1, \-1\*(C'\fR) is the
last character of input stream.
The span (\f(CW\*(C`\-2, \-1\*(C'\fR) is the
last two characters of the input stream.
The span (\f(CW\*(C`\-2, 1\*(C'\fR) is the 
second to last character of the input stream.
.SS "G1 locations"
.IX Subsection "G1 locations"
In addition to input stream location,
the \s-1SLIF\s0 also tracks G1 location.
G1 location starts at zero,
and increases by exactly one as each lexeme is read.
G1 location is usually not the same
as input stream location.
There is also a concept of G1 length,
which is simply
length calculated in terms of G1 locations.
.PP
G1 location can be ignored most of the time,
but it does become relevant to a small degree
when dealing
with ambiguous terminals,
and to a greater degree when tracing the G1 grammar.
(For those more familiar with Marpa's internals,
the G1 location is the G1 Earley set index.)
.SS "Current location"
.IX Subsection "Current location"
The \s-1SLIF\s0 tracks
the \fBcurrent location in the input stream\fR, more usually simply
called the \fBcurrent location\fR.
Locations are zero-based, so that location 0 is the start
of the input stream.
A location is said to \fBpoint\fR to the character after it,
if there is such a character.
For example,
location 0 points to the first character of the input stream,
unless the stream is of zero length,
in which case there is no first character.
.PP
A current location equal to the length of the input stream
indicates \s-1EOS \s0(end of stream).
In a zero length stream, location 0 is \s-1EOS.\s0
The \s-1EOS\s0 location never points to a character.
.PP
In the \s-1SLIF,\s0 when the current input stream location
moves, it does not necessarily advance \*(-- it
can skip forward,
or can be positioned to an earlier location.
The application can skip sections of the input stream.
The application is also free to
revisit spans of the input stream as often as it wants.
.PP
Here are the guarantees:
.IP "\(bu" 4
Initially, the current location is 0.
.IP "\(bu" 4
The current location will never be negative.
.IP "\(bu" 4
The current location will never be greater than \s-1EOS.\s0
.SS "Literals and G1 spans"
.IX Subsection "Literals and G1 spans"
Often it is useful to find the literal substring of the input which corresponds to a span
of G1 locations.
If an application reads the input monotonically within the G1 span
this presents no complications.
.PP
\&\*(L"Monotonically\*(R" here means that,
for the G1 span \f(CW\*(C`$g1_start, $g1_length\*(C'\fR,
the application reads the G1 locations
in sequence and one-by-one, starting at
\&\f(CW$g1_start\fR and ending at \f(CW\*(C`$g1_start+$g1_length\*(C'\fR.
This is the usual case.
.PP
Reading the input monotonically is the default,
and by far the most common
case.
But Marpa applications
are free to skip forward in the stream,
to jump backward,
to reread the same input multiple times, etc., etc.
It is entirely possible the final input stream location of a G1 span 
will be before the start of the G1 span.
.PP
In precise terms,
the substring returned
for a G1 span \f(CW\*(C`$g1_start, $g1_length\*(C'\fR
is determined as follows:
The string
will start at the first input stream location in the span for
G1 location \f(CW\*(C`$g1_start+1\*(C'\fR.
The end of the string will be at
the last input stream location in the span for
G1 location \f(CW\*(C`$g1_start+$g1_length\*(C'\fR.
When an application moves backward in the input,
the end of the string,
as calculated above,
may be before the start of the string.
When the end of a string is before its start,
the substring returned will be the zero-length string.
.PP
Applications which do not read monotonically,
but which also
want to associate spans of G1 locations with the input stream,
may need to reassemble the input based on their own ideas.
The \*(L"\fIliteral()\fR\*(R" method can assist in this process.
.SH "How internal scanning works"
.IX Header "How internal scanning works"
The \s-1SLIF\s0 always starts scanning using the \f(CW\*(C`read()\*(C'\fR
method.
Pedantically, this means scanning always begins with a phase
of internal scanning.
But that first phase may be of zero length,
and after that,
internal scanning does not have to be resumed.
.PP
Internal scanning can be resumed with the \f(CW\*(C`resume()\*(C'\fR method.
Both the \f(CW\*(C`read()\*(C'\fR and \f(CW\*(C`resume()\*(C'\fR methods require the application
to specify a span in the input stream.
The \f(CW\*(C`read()\*(C'\fR method sets the input stream,
and that input stream is the one used by all \f(CW\*(C`resume()\*(C'\fR method calls
for that recognizer.
.PP
In what follows, the term \*(L"internal scanning method\*(R"
refers to either the \f(CW\*(C`read()\*(C'\fR or the \f(CW\*(C`resume()\*(C'\fR method.
After an internal scanning method,
the current location will indicate how far
in the input stream the internal scanning method actually read.
If the internal scanning method paused before \s-1EOS,\s0
the current
location will be the one at which it paused.
If the internal scanning method pauses at \s-1EOS,\s0
the current location will be \s-1EOS.\s0
The return value of the \f(CW\*(C`read()\*(C'\fR and the \f(CW\*(C`resume()\*(C'\fR method is
the current location.
.SS "\s-1EOS\s0"
.IX Subsection "EOS"
The location of \s-1EOS\s0 depends on the
\&\f(CW$start\fR and \f(CW$length\fR arguments
to the last
internal scanning method,
and on the length of the input string.
.IP "\(bu" 4
If the \f(CW$length\fR argument of the last internal scanning method was
non-negative,
\&\s-1EOS\s0 will be at \f(CW\*(C`$start+$length\*(C'\fR.
.IP "\(bu" 4
If the \f(CW$length\fR argument was negative,
\&\s-1EOS\s0 will be at
\&\f(CW\*(C`$length + 1 + length $input_string\*(C'\fR.
.IP "\(bu" 4
The default length for the internal scanning methods is always \-1,
so that the default \s-1EOS\s0 is always at
\&\f(CW\*(C`length $input_string\*(C'\fR,
the end of the input string.
.SS "Pauses in internal scanning"
.IX Subsection "Pauses in internal scanning"
When a \f(CW\*(C`read()\*(C'\fR and the \f(CW\*(C`resume()\*(C'\fR method pauses,
one of more of the following occurred.
.IP "\(bu" 4
A named event
.Sp
One or more named events may have triggered.
Named events are
created by
named event statements.
They can also be created by
lexeme pseudo-rules.
Named events may be queried using
the \fIevents()\fR \fImethod()\fR.
.IP "\(bu" 4
A unnamed lexeme pause event
.Sp
A lexeme pause that is not a named event may have triggered.
Lexeme pauses are created by
lexeme pseudo-rules.
Applications can always name lexeme pause events, using the
event adverb,
and are strongly encouraged to do so.
If all lexeme pauses are named,
the check for unnamed events can be omitted.
The presence or absence of an unnamed lexeme pause event
may be checked for using
the \fIlexeme_pause()\fR method.
.IP "\(bu" 4
\&\s-1EOS\s0
.Sp
\&\s-1EOS\s0 may have been reached.
This may be checked for by comparing the current location
with the expected \s-1EOS.\s0
.SH "The input stream"
.IX Header "The input stream"
For error message and other purposes,
even external lexemes are required to correspond to a span of the input stream.
An external scanner
must set up a relationship to the input stream,
even if that relationship is completely artificial.
.PP
One way to do this is to put an artificial preamble in front of
the input stream.
For example, the first 7 characters of the input stream could be
a preamble containing the characters "\f(CW\*(C`NO TEXT\*(C'\fR".
This preamble could be immediately followed by what is seen as the text
from a more natural point of view.
In this case, the initial call to the \f(CW\*(C`read()\*(C'\fR method
could take the form
\&\f(CW\*(C`$slr\->read($input_string, 7)\*(C'\fR.
Lexemes corresponding to the artificial preamble would be read
using a method call similar to
\&\f(CW\*(C`$slr\->lexeme_read($symbol_name, 0, 7, $value)\*(C'\fR.
.SH "Constructor"
.IX Header "Constructor"
.Vb 1
\&    my $recce = Marpa::R2::Scanless::R\->new( { grammar => $grammar } );
.Ve
.PP
The \f(CW\*(C`new()\*(C'\fR method is the constructor for \s-1SLIF\s0 recognizers.
The \f(CW\*(C`new()\*(C'\fR constructor accepts a hash of named arguments.
The \f(CW\*(C`grammar\*(C'\fR named argument is required.
All other named arguments are optional.
.PP
The following named arguments are allowed:
.SS "end"
.IX Subsection "end"
Most users will want to ignore this argument.
It is an advanced argument, mainly for use in testing.
The \f(CW\*(C`end\*(C'\fR named argument
specifies the parse end, as a G1 location.
The default is for the parse to end where the input did,
so that the parse returned is of the entire input.
The \f(CW\*(C`end\*(C'\fR named argument is not allowed
once a parse series has begun.
.SS "grammar"
.IX Subsection "grammar"
The \f(CW\*(C`new\*(C'\fR method is required to have
a \f(CW\*(C`grammar\*(C'\fR named argument.  Its
value must be
an \s-1SLIF\s0 grammar object.
.SS "max_parses"
.IX Subsection "max_parses"
If non-zero, causes a fatal error when that number
of parse results is exceeded.
\&\f(CW\*(C`max_parses\*(C'\fR is useful to
limit \s-1CPU\s0 usage and output length when testing
and debugging.
Stable and production applications may
prefer to count the number of parses,
and take a less Draconian response when the
count is exceeded.
.PP
The value must be an integer.
If it is zero, there will be no
limit on the number of parse results returned.
The default is for
there to be no limit.
.SS "ranking_method"
.IX Subsection "ranking_method"
The value must be a string:
one of "\f(CW\*(C`none\*(C'\fR\*(L",
\&\*(R"\f(CW\*(C`rule\*(C'\fR\*(L",
or \*(R"\f(CW\*(C`high_rule_only\*(C'\fR\*(L".
When the value is \*(R"\f(CW\*(C`none\*(C'\fR", Marpa returns the parse results
in arbitrary order.
This is the default.
The \f(CW\*(C`ranking_method\*(C'\fR named argument is not allowed
once evaluation has begun.
.PP
The "\f(CW\*(C`rule\*(C'\fR\*(L"
and \*(R"\f(CW\*(C`high_rule_only\*(C'\fR" ranking methods
allows the user
to control the order
in which parse results are returned by
the \f(CW\*(C`value\*(C'\fR method,
and to exclude some parse results from the parse series.
For details, see the document
on parse order.
.SS "semantics_package"
.IX Subsection "semantics_package"
Sets the semantic package for the recognizer.
The setting of this argument takes precedence
over any package implied by the blessing of the per-parse arguments to
the \s-1SLIF\s0 recognizer's \f(CW\*(C`value()\*(C'\fR method.
The semantics package is used when resolving action names to
fully qualified Perl names.
For more details on the \s-1SLIF\s0 semantics,
see the document on \s-1SLIF\s0
semantics.
.SS "too_many_earley_items"
.IX Subsection "too_many_earley_items"
The \f(CW\*(C`too_many_earley_items\*(C'\fR argument is optional,
and very few applications will need it.
If specified, it sets the \fBEarley item warning threshold\fR to
a value other than its default.
If an Earley set becomes larger than the
Earley item warning threshold,
a recognizer event is generated,
and
a warning is printed to the trace file handle.
.PP
Marpa parses from any \s-1BNF,\s0
and can handle grammars and inputs which produce very large
Earley sets.
But parsing that involves very large Earley sets can be slow.
Large Earley sets
are something most applications can,
and will wish to, avoid.
.PP
By default, Marpa calculates
an Earley item warning threshold
for the G1 recognizer
based on the size of the
G1 grammar,
and for each L0 recognizer based on the size
of the L0 grammar.
The default thresholds will never be less than 100.
The default is the result of considerable experience
and almost all users will be happy with it.
.PP
If the
Earley item warning threshold is changed from its default,
the change applies to both L0 and G1 \*(-- currently
there is no way to set them separately.
If the Earley item warning threshold is set to 0,
no recognizer event is generated,
and
warnings about large Earley sets are turned off.
An Earley item threshold warning almost always
indicates a serious issue,
and turning these warnings off will
rarely be what an application wants.
.SS "trace_terminals"
.IX Subsection "trace_terminals"
If non-zero, traces the lexemes \*(--
those tokens passed from the L0 parser to
the G1 parser.
This named argument is the best way to follow
what the L0 parser is doing,
and it is also very helpful for tracing the G1 parser.
.SS "trace_values"
.IX Subsection "trace_values"
The trace_values named argument is a numeric trace level.  If the
numeric trace level is 1, Marpa prints tracing information as values
are computed in the evaluation stack.  A trace level of 0 turns
value tracing off, which is the default. Traces are written to the
trace file handle.
.SS "trace_file_handle"
.IX Subsection "trace_file_handle"
The value is a file handle.
Trace output and warning messages
go to the trace file handle.
By default, the trace file handle is inherited from the
grammar.
.SH "Basic mutators"
.IX Header "Basic mutators"
.SS "\fIread()\fP"
.IX Subsection "read()"
.Vb 1
\&    $recce\->read($p_input_string);
.Ve
.PP
.Vb 1
\&    $recce\->read( \e$string, 0, 0 );
.Ve
.PP
Given a pointer to an input stream,
\&\f(CW\*(C`read()\*(C'\fR parses it according to the grammar.
Only a single call to \f(CW\*(C`read()\*(C'\fR
is allowed for a scanless
recognizer.
.PP
\&\f(CW\*(C`read()\*(C'\fR recognizes
optional second and third arguments.
The second argument is a location in the input stream
at which internal scanning will start.
The third argument is the length of the section
of the input stream to be scanned before pausing.
The default start location is zero.
The default length is \-1.
Negative locations and lengths have the standard
interpretation, as described above.
.PP
Start location and length can both be zero.
This pauses internal scanning immediately and can be
used to hand complete control of scanning
over to an external scanner.
.PP
Completion named events
can occur during the \f(CW\*(C`read()\*(C'\fR method.
When a named event occurs, 
the \f(CW\*(C`read()\*(C'\fR method pauses.
Named events can be queried using
the Scanless recognizer's \fIevents()\fR
method.
The \f(CW\*(C`read()\*(C'\fR method also
pauses as specified with the
Scanless \s-1DSL\s0's pause adverb.
.PP
On failure, throws an exception.
The call is considered successful
if it ended because a parse was found,
or because internal scanning was paused.
On success, \f(CW\*(C`read()\*(C'\fR returns the location in the input
stream at which internal scanning ended.
This value may be zero.
.SS "\fIseries_restart()\fP"
.IX Subsection "series_restart()"
.Vb 1
\&    $slr\->series_restart( { end => $i } );
.Ve
.PP
The \f(CW\*(C`series_restart()\*(C'\fR method ends the current parse series,
and starts another.
It allows, as optional arguments, hashes of named arguments
for the \s-1SLIF\s0 recognizer.
These named arguments can be any of those allowed by
the \f(CW\*(C`set()\*(C'\fR method.
.PP
\&\f(CW\*(C`series_restart()\*(C'\fR resets all the named arguments to their defaults.
An application that wants a non-default named argument to have effect
in each of its parse
series must respecify it at the beginning of each parse series.
\&\f(CW\*(C`series_restart()\*(C'\fR is particularly useful for
the 
\&\f(CW\*(C`end\*(C'\fR and \f(CW\*(C`semantics_package\*(C'\fR named arguments,
which cannot be changed once a parse series is underway.
To change their values,
an application must start a new parse series.
.SS "\fIset()\fP"
.IX Subsection "set()"
.Vb 1
\&    $slr\->set( { max_parses => 42 } );
.Ve
.PP
This method allows the named arguments to be changed after an \s-1SLIF\s0
grammar is created.
Currently, the arguments that may be changed are \f(CW\*(C`end\*(C'\fR,
\&\f(CW\*(C`max_parses\*(C'\fR,
\&\f(CW\*(C`semantics_package\*(C'\fR and
\&\f(CW\*(C`trace_file_handle\*(C'\fR.
.SS "\fIvalue()\fP"
.IX Subsection "value()"
.Vb 1
\&    my $value_ref = $recce\->value( $self );
.Ve
.PP
The \f(CW\*(C`value\*(C'\fR method call evaluates the next parse tree
in the parse series,
and returns a reference to the parse result for that parse tree.
If there are no more parse trees,
the \f(CW\*(C`value\*(C'\fR method returns \f(CW\*(C`undef\*(C'\fR.
.PP
Because Marpa parses ambiguous grammars, every parse
is a series of zero or more parse trees.
This series of zero or more parse trees is called a \fBparse series\fR.
There are zero parse trees if there was no valid parse
of the input according to the grammar.
.PP
The \f(CW\*(C`value()\*(C'\fR method allows one, optional argument.
This argument can be a Perl scalar of any kind, but the most useful
possibilities are references (blessed or unblessed) to hashes or array.
If provided, the argument of the \f(CW\*(C`value()\*(C'\fR method
explicitly specifies the per-parse argument for the
parse tree.
The per-parse argument will be the first argument of all 
Perl semantics closures, and can be used to share data within
the tree,
when that data does not conveniently fit into the bottom-up
flow of parse tree evaluation.
Symbol tables are one example of the kind of data which parses often
require, but which it is not convenient to accumulate bottom-up.
.PP
If the \f(CW\*(C`semantics_package\*(C'\fR named argument of the \s-1SLIF\s0
recognizer was not specified,
Marpa will use the package into which the per-parse argument was blessed
as the semantics package \*(--
the package in which to look for the parse's Perl semantic closures.
In this case, Marpa will regard the per-parse arguments of all
calls in the same parse series as the source of the semantics package,
and it will require that the calls be consistent \*(--
each call must have a per-parse argument,
and that per-parse argument  must be blessed into the semantics package.
.SH "Mutators for external scanning"
.IX Header "Mutators for external scanning"
.SS "\fIactivate()\fP"
.IX Subsection "activate()"
.Vb 1
\&        $slr\->activate($_, 0) for @events;
.Ve
.PP
The \f(CW\*(C`activate()\*(C'\fR method allows the recognizer to deactivate and reactivate named
events.
Named events allow the recognizer to stop for external scanning at conveniently
defined locations.
Named events can be defined for the prediction and completion of non-zero-length symbols,
and nulled events can be defined to trigger when zero-length symbols are
recognized.
.PP
The \f(CW\*(C`activate()\*(C'\fR method takes two arguments.
The first is the name of an event, and the second (optional) argument is
0 or 1.
If the argument is 0, the event is deactivated.
If the argument is 1, the event is reactivated.
An argument of 1 is the default.
but,
since an \s-1SLIF\s0 recognizer always starts with all defined events
activated,
0 will probably be more common as the second argument to
\&\f(CW\*(C`activate()\*(C'\fR
.PP
Location 0 events are triggered in the \s-1SLIF\s0 recognizer's 
constructor,
before the \f(CW\*(C`activate()\*(C'\fR method can be called.
This means that currently there is no way to deactivate
location zero events.
.PP
The overhead imposed by events
can be reduced by using the \f(CW\*(C`activate()\*(C'\fR method.
But making many calls to the
the \f(CW\*(C`activate()\*(C'\fR method purely for efficiency
purposes will be counter-productive.
Also, deactivated events still impose
some overhead, so if an event is never used
it should be commented out in the \s-1SLIF DSL.\s0
.SS "\fIlexeme_alternative()\fP"
.IX Subsection "lexeme_alternative()"
.Vb 5
\&            if ( not defined $recce\->lexeme_alternative($token_name) ) {
\&                die
\&                    qq{Parser rejected token "$long_name" at position $start_of_lexeme, before "},
\&                    substr( $string, $start_of_lexeme, 40 ), q{"};
\&            }
.Ve
.PP
The \f(CW\*(C`lexeme_alternative()\*(C'\fR method
allows an external scanner to read
ambiguous tokens.
Most applications 
will prefer the simpler \f(CW\*(C`lexeme_read()\*(C'\fR.
.PP
\&\f(CW\*(C`lexeme_alternative()\*(C'\fR takes one or two arguments.
The first argument,
which is required,
is the name of a symbol to be read
at the current location.
The second argument,
which is optional,
is the value of the symbol.
The value argument is interpreted as described for \f(CW\*(C`lexeme_read()\*(C'\fR.
.PP
Any number of tokens may be read using \f(CW\*(C`lexeme_alternative()\*(C'\fR
without advancing the current location.
This allows an application to use ambiguous tokens.
To complete reading at a G1 location,
and advance the current G1 location to the next G1 location,
use the \f(CW\*(C`lexeme_complete()\*(C'\fR method.
.PP
On success, returns a non-negative number.
Returns \f(CW\*(C`undef\*(C'\fR if the token was rejected.
Failures are thrown as exceptions.
.SS "\fIlexeme_complete()\fP"
.IX Subsection "lexeme_complete()"
.Vb 3
\&            next TOKEN
\&                if $recce\->lexeme_complete( $start_of_lexeme,
\&                        ( length $lexeme ) );
.Ve
.PP
The \f(CW\*(C`lexeme_complete()\*(C'\fR method allows an external scanner to read
ambiguous tokens.
Most applications will prefer the simpler \f(CW\*(C`lexeme_read()\*(C'\fR.
.PP
The \f(CW\*(C`lexeme_complete()\*(C'\fR method
requires two arguments,
a input stream start location and a length.
These are interpreted as described for the
corresponding second and third
arguments to \f(CW\*(C`lexeme_read()\*(C'\fR.
The \f(CW\*(C`lexeme_complete()\*(C'\fR
method completes the reading of
alternative tokens at the current G1 location,
and advances the current G1 location by one.
Current location in the input stream is moved
to the location after the new lexeme,
as indicated by the arguments.
.PP
Completion named events
can occur during the \f(CW\*(C`lexeme_complete()\*(C'\fR method.
Named events can be queried using
the Scanless recognizer's \fIevents()\fR
method.
.PP
\&\fBReturn value:\fR
On success, \f(CW\*(C`lexeme_complete()\*(C'\fR
returns the new current location.
This will never be location zero, because a succesful
call of \f(CW\*(C`lexeme_complete()\*(C'\fR always advances the location.
On unthrown failure, \f(CW\*(C`lexeme_complete()\*(C'\fR returns 0.
.SS "\fIlexeme_read()\fP"
.IX Subsection "lexeme_read()"
.Vb 1
\&    $re\->lexeme_read( \*(Aqlstring\*(Aq, $start, $length, $value ) // die;
.Ve
.PP
The \f(CW\*(C`lexeme_read()\*(C'\fR method reads a single, unambiguous, lexeme.
It takes four arguments, only the first of which is required.
The first argument is the lexeme's symbol name.
The second and third arguments specify the span in the input
stream to be associated with the lexeme.
The last argument indicates its value.
.PP
The second and third arguments are, respectively,
the start and length of a span in the input stream.
The start defaults to the current location.
If the pause span is defined,
and the start of the pause lexeme is
the same as the current location,
length defaults to the length of the pause span.
Otherwise length defaults to \-1.
.PP
Negative values are allowed and are interpreted
as described above.
This span will be treated as the section of the input stream
that corresponds to the tokens read at the current location.
This correspondence may be artificial, but a span must
always be specified.
.PP
The fourth argument specifies the value of the lexeme.
If the value argument is omitted,
the token's value will be a string
containing the corresponding substring
of the input stream.
Omitting the value argument does not have the same
effect as passing an explicit Perl \f(CW\*(C`undef\*(C'\fR.
If the value argument is an explicit Perl \f(CW\*(C`undef\*(C'\fR,
the value of the lexeme will be a Perl \f(CW\*(C`undef\*(C'\fR.
.PP
.Vb 1
\&    $slr\->lexeme_read($symbol, $start, $length, $value)
.Ve
.PP
is the equivalent of
.PP
.Vb 2
\&    $slr\->lexeme_alternative($symbol, $value)
\&    $slr\->lexeme_complete($start, $length)
.Ve
.PP
Current location in the input stream is moved
to the place where \f(CW\*(C`read()\*(C'\fR paused or,
if it never pauses,
to \f(CW\*(C`$start+$length\*(C'\fR.
Current G1 location is advanced by one.
.PP
Completion named events
can occur during the \f(CW\*(C`lexeme_read()\*(C'\fR method.
Named events can be queried using
the Scanless recognizer's \fIevents()\fR
method.
.PP
\&\fBReturn value\fR:
On success, \f(CW\*(C`lexeme_read()\*(C'\fR returns the new current location.
This will never be location zero, because lexemes cannot be zero length.
If the token was rejected, returns a Perl \f(CW\*(C`undef\*(C'\fR.
On other unthrown failure, returns 0.
.SS "\fIresume()\fP"
.IX Subsection "resume()"
.Vb 10
\&    my $re = Marpa::R2::Scanless::R\->new(
\&        {   grammar           => $parser\->{grammar},
\&            semantics_package => \*(AqMarpaX::JSON::Actions\*(Aq
\&        }
\&    );
\&    my $length = length $string;
\&    for (
\&        my $pos = $re\->read( \e$string );
\&        $pos < $length;
\&        $pos = $re\->resume()
\&        )
\&    {
\&        my ( $start, $length ) = $re\->pause_span();
\&        my $value = substr $string, $start + 1, $length \- 2;
\&        $value = decode_string($value) if \-1 != index $value, \*(Aq\e\e\*(Aq;
\&        $re\->lexeme_read( \*(Aqlstring\*(Aq, $start, $length, $value ) // die;
\&    } ## end for ( my $pos = $re\->read( \e$string ); $pos < $length...)
\&    my $per_parse_arg = bless {}, \*(AqMarpaX::JSON::Actions\*(Aq;
\&    my $value_ref = $re\->value($per_parse_arg);
\&    return ${$value_ref};
.Ve
.PP
The \f(CW\*(C`resume()\*(C'\fR method takes two arguments,
a start location and a length.
The default start location is the current location.
The default length is \-1.
Negative arguments are interpreted
as described above.
.PP
The \f(CW\*(C`resume()\*(C'\fR method resumes
the \s-1SLIF\s0's internal scanning,
as described
above.
.PP
Completion named events
can occur during the \f(CW\*(C`resume()\*(C'\fR method.
When a named event occurs, 
the \f(CW\*(C`resume()\*(C'\fR method pauses.
Named events can be queried using
the Scanless recognizer's \fIevents()\fR
method.
The \f(CW\*(C`resume()\*(C'\fR method also
pauses as specified with the
Scanless \s-1DSL\s0's pause adverb.
.PP
On success, \f(CW\*(C`resume()\*(C'\fR moves
the current location to where it paused,
or to the \s-1EOS.\s0
The return value is the new current location.
On unthrown failure,
\&\f(CW\*(C`resume()\*(C'\fR return a Perl \f(CW\*(C`undef\*(C'\fR.
.SH "Accessors"
.IX Header "Accessors"
.SS "\fIambiguity_metric()\fP"
.IX Subsection "ambiguity_metric()"
.Vb 1
\&    my $ambiguity_metric = $slr\->ambiguity_metric();
.Ve
.PP
Returns 1 if there is an unambiguous parse,
and 2 or greater if there is a ambiguous parse.
Returns 0 if called before parsing.
Returns 0 or less than zero on other unthrown failure.
.SS "\fIcurrent_g1_location()\fP"
.IX Subsection "current_g1_location()"
.Vb 1
\&    my $current_g1_location = $slr\->current_g1_location();
.Ve
.PP
Returns the current G1 location.
.SS "\fIevents()\fP"
.IX Subsection "events()"
.Vb 5
\&        EVENT:
\&        for my $event ( @{ $slr\->events() } ) {
\&            my ($name) = @{$event};
\&            push @actual_events, $name;
\&        }
.Ve
.PP
The \f(CW\*(C`events()\*(C'\fR method takes no arguments,
and returns an array of event descriptors.
It returns the empty array
if there were no event.
.PP
Each named event descriptor is a reference to an array of one,
and potentially more, elements.
The first element of every named event descriptor is a string
containing the name of the event,
and this is typically the only element.
In certain cases, there could be
other elements of a named event descriptor,
which will be
as described for the type of named event.
Named events are
described in the \s-1SLIF
DSL\s0.
.PP
Events occur during the
the Scanless recognizer's \fIread()\fR,
\&\fIresume()\fR,
\&\fIlexeme_complete()\fR,
and \fIlexeme_read()\fR
methods.
Any subsequent call
to an \s-1SLIF\s0 recognizer mutator may clear the list
of triggered events,
The assumption is that
an application interested in events
will call
the \f(CW\*(C`events()\*(C'\fR method almost as soon as
control is returned to it.
.PP
Named events are returned in order by type.
Completion events are first.
They are followed by the nulled events.
These are in turn followed by prediction events.
Within each type,
the order of events is arbitrary.
.PP
Applications may find it convenient to
turn specific events off,
temporarily or permanently.
Events may be activated or deactivated
with the \s-1SLIF\s0 recognizer's
\&\fIactivate()\fR method.
.SS "\fIexhausted()\fP"
.IX Subsection "exhausted()"
.Vb 1
\&    my $exhausted_status = $slr\->exhausted();
.Ve
.PP
The exhausted method returns a Perl true if parsing in a \s-1SLIF\s0
recognizer is
exhausted, and a Perl false otherwise. Parsing is exhausted when the
recognizer will not accept any further input.
.PP
An attempt to read input into an
exhausted parser causes an exception to be thrown.
The exception is all that most applications require,
but this method
allows the recognizer's exhaustion status to be discovered directly.
.SS "\fIg1_location_to_span()\fP"
.IX Subsection "g1_location_to_span()"
.Vb 2
\&        my ( $span_start, $span_length ) =
\&            $slr\->g1_location_to_span($g1_location);
.Ve
.PP
G1 locations do not correspond to a single input stream
location, but to a span of them.
The \f(CW\*(C`g1_location_to_span()\*(C'\fR method
returns an \fBarray\fR of two elements, representing a span in the input stream.
The first element of the array is the input stream location
where the span starts.
The second element of the array is the length of the span.
As a special case,
the input stream span for G1 location 0 is always (0,0).
.PP
Sometimes it is convenient to think of
G1 location as corresponding to a single input stream location.
When this is the case,
what is usually intended is the last input stream location
of the span.
The last input stream location
of the span
will always be \f(CW\*(C`$span_start+$span_length\*(C'\fR.
.SS "\fIinput_length()\fP"
.IX Subsection "input_length()"
.Vb 1
\&    my $input_length = $slr\->input_length();
.Ve
.PP
The \f(CW\*(C`input_length()\*(C'\fR method accepts no arguments,
and returns the length of the input stream.
.SS "\fIlast_completed()\fP"
.IX Subsection "last_completed()"
.Vb 8
\&    sub show_last_expression {
\&        my ($self) = @_;
\&        my $recce = $self\->{recce};
\&        my ( $g1_start, $g1_length ) = $recce\->last_completed(\*(AqExpression\*(Aq);
\&        return \*(AqNo expression was successfully parsed\*(Aq if not defined $g1_start;
\&        my $last_expression = $recce\->substring( $g1_start, $g1_length );
\&        return "Last expression successfully parsed was: $last_expression";
\&    } ## end sub show_last_expression
.Ve
.PP
.Vb 1
\&    my ( $g1_start, $g1_length ) = $recce\->last_completed(\*(AqExpression\*(Aq);
.Ve
.PP
Given the name of a symbol,
returns the start G1 location and
the length in G1 locations of the most recent match.
If there was more than one most recent match, it returns
the longest.
If there was no match, returns the empty array in array context
and a Perl false in scalar context.
.SS "\fIline_column()\fP"
.IX Subsection "line_column()"
.Vb 2
\&    my ( $start, $span_length ) = $re\->pause_span();
\&    my ( $line,  $column )      = $re\->line_column($start);
.Ve
.PP
The \f(CW\*(C`line_column()\*(C'\fR method accepts one, optional, argument:
a location in the input stream.
The location defaults to the current location.
\&\f(CW\*(C`line_column()\*(C'\fR returns the corresponding line and column position,
as a 2\-element array.
The first element of the array is the line position,
and the second element is the column position.
.PP
Numbering of lines and columns is 1\-based,
following \s-1UNIX\s0 editor tradition.
Except at \s-1EOF,\s0 the line and column will be that of an
actual character.
At \s-1EOF\s0 the line number
will be that of the last line,
and the column number will be that of the last column
plus one.
Applications which want to treat \s-1EOF\s0 as a special case
can test it for using the \f(CW\*(C`pos()\*(C'\fR method
and the \f(CW\*(C`input_length()\*(C'\fR method.
.PP
A line is considered to end with any newline sequence
as defined in the
Unicode Specification 4.0.0, Section 5.8.
Specifically, a line ends with one of the following:
.IP "\(bu" 4
a \s-1LF \s0(line feed U+000A);
.IP "\(bu" 4
a \s-1CR \s0(carriage return, U+000D), when it is not followed by a \s-1LF\s0;
.IP "\(bu" 4
a \s-1CRLF\s0 sequence (U+000D,U+000A);
.IP "\(bu" 4
a \s-1NEL \s0(next line, U+0085);
.IP "\(bu" 4
a \s-1VT \s0(vertical tab, U+000B);
.IP "\(bu" 4
a \s-1FF \s0(form feed, U+000C);
.IP "\(bu" 4
a \s-1LS \s0(line separator, U+2028) or
.IP "\(bu" 4
a \s-1PS \s0(paragraph separator, U+2029).
.SS "\fIliteral()\fP"
.IX Subsection "literal()"
.Vb 1
\&    my $literal_string = $re\->literal( $start, $span_length );
.Ve
.PP
The \f(CW\*(C`literal()\*(C'\fR method accepts two arguments,
the start location and length of a span in the
input stream.
It returns the substring of the input stream
corresponding to that span.
.SS "\fIpause_lexeme()\fP"
.IX Subsection "pause_lexeme()"
.Vb 1
\&   my $lexeme = $re\->pause_lexeme();
.Ve
.PP
The \f(CW\*(C`pause_lexeme()\*(C'\fR method accepts no arguments,
and returns the name of the lexeme which caused the most
recent pause.
The pause lexeme is initially undefined
and it is reset to undefined at the beginning of
each call to the \f(CW\*(C`read()\*(C'\fR or \f(CW\*(C`resume()\*(C'\fR methods.
.PP
More than one lexeme may cause a pause.
When this is the case,
all the causal lexemes will be
acceptable to the G1 grammar,
and all the causal lexemes will have
the same lexeme priority.
When more than one lexeme causes a pause,
the choice of pause
lexeme is arbitrary.
Applications may not rely on a particular choice,
or on that choice being repeated,
even when the choice is made
in similar or identical circumstances.
.PP
Not every pause is caused by a lexeme.
A pause often occurs because
of the length argument of an internal scanning method.
When the most recent pause was not caused by a lexeme,
the pause lexeme is undefined.
\&\f(CW\*(C`pause_lexeme()\*(C'\fR returns a Perl \f(CW\*(C`undef\*(C'\fR when
the pause lexeme is undefined.
.SS "\fIpause_span()\fP"
.IX Subsection "pause_span()"
.Vb 1
\&    my ( $start, $length ) = $re\->pause_span();
.Ve
.PP
The \f(CW\*(C`pause_span()\*(C'\fR method accepts no arguments,
and returns the \*(L"pause span\*(R" as a 2\-element array.
The \*(L"pause span\*(R" is
the start location and length of the lexeme which caused
the most recent pause.
The pause span is initially undefined
and it is reset to undefined at the beginning of
each call to the \f(CW\*(C`read()\*(C'\fR or \f(CW\*(C`resume()\*(C'\fR methods.
.PP
A pause is not always caused by a lexeme \*(-- internal
scanning may be paused
because of the length argument of an internal scanning method.
When the most recent pause was not caused by a lexeme,
no span can be associated with it,
and the pause span is undefined.
\&\f(CW\*(C`pause_span()\*(C'\fR returns a Perl \f(CW\*(C`undef\*(C'\fR if
the pause span is undefined.
.SS "\fIpos()\fP"
.IX Subsection "pos()"
.Vb 1
\&    my $pos = $slr\->pos();
.Ve
.PP
The \f(CW\*(C`pos()\*(C'\fR method accepts no arguments,
and returns the current input stream location.
.SS "\fIprogress()\fP"
.IX Subsection "progress()"
.Vb 1
\&    my $progress_output = $slr\->progress();
.Ve
.PP
Returns an array that describes the progress
of a parse
at a location.
With no argument, \f(CW\*(C`progress()\*(C'\fR reports progress at
the current location.
If a G1 location is
given as its argument,
\&\f(CW\*(C`progress()\*(C'\fR reports progress at that G1 location.
The G1 location may be negative.
An argument of \fI\-X\fR
will be interpreted as location \fIN+X+1\fR, where \fIN\fR is
the current G1 location.
In other words, an argument of \-1 indicates the current G1 location,
an argument of \-2 indicates the G1 location just before
the current one, etc.
.PP
The progress reports returned by
the \f(CW\*(C`progress()\*(C'\fR method
identify rules by their G1 rule \s-1ID.
G1\s0 rules IDs can be converted to a list of the rule's
symbols using the \f(CW\*(C`rule()\*(C'\fR method
of the \s-1SLIF\s0 grammar.
Details on progress reports can be found in
their own document.
.SS "\fIshow_progress()\fP"
.IX Subsection "show_progress()"
.Vb 1
\&    my $show_progress_output = $slr\->show_progress();
.Ve
.PP
Shows the progress of the G1 parse.
For a description of its output,
see Marpa::R2::Progress.
.PP
With no arguments,
the string contains reports for
the current location.
If locations are specified as arguments to
\&\f(CW\*(C`show_progress()\*(C'\fR, they need to be 
G1 locations.
.PP
With a single integer argument \fIN\fR,
the string contains reports for G1 location \fIN\fR.
With two numeric arguments, \fIN\fR and \fIM\fR, the arguments are interpreted
as the start and end points of a range of G1 locations
and the returned string contains
reports for all locations in the range.
.PP
If an argument is negative,
\&\fI\-N\fR,
it indicates
the \fIN\fRth location counting backward
from the furthest location of the parse.
For example, if 42 was the furthest G1 location,
\&\-1 would be G1 location 42 and \-2 would be location 41.
For example, the method call
\&\f(CW\*(C`$recce\->show_progress(\-3, \-1)\*(C'\fR
returns reports for the last three G1 locations of the parse.
The method call \f(CW\*(C`$recce\->show_progress(0, \-1)\*(C'\fR
will print progress reports for the entire parse.
.PP
Locations are G1 locations instead of string offsets,
for two reasons.
First, G1 parse state is only defined at the start of parsing,
and at the end of a non-discarded lexeme.
Therefore many strings offsets will not have a G1 parse state.
Second, \s-1SLIF\s0 recognizers using external scanning are allowed
to rescan the same string repeatedly.
Therefore, a single string offset may have many
G1 parse states.
.SS "\fIsubstring()\fP"
.IX Subsection "substring()"
.Vb 1
\&    my $last_expression = $recce\->substring( $g1_start, $g1_length );
.Ve
.PP
Given a G1 span \*(-- that is, a G1 start location and a length in G1 locations \*(--
the \f(CW\*(C`substring()\*(C'\fR method
returns a substring of the input
stream.
A G1 length of zero will produce the zero-length string.
.PP
The substring of the input stream is determined on the assumption
that the application reads the input monotonically.
When this is not the case, the substring is determined as
described above.
.SS "\fIterminals_expected()\fP"
.IX Subsection "terminals_expected()"
.Vb 1
\&    my @terminals_expected = @{$slr\->terminals_expected()};
.Ve
.PP
Returns a reference to a list of strings, where the strings are the
names of the lexemes acceptable at the current location.
The presence of a lexeme in this list means
that lexeme will be acceptable in the next call of the \f(CW\*(C`resume()\*(C'\fR method.
.PP
This is highly useful for Ruby Slippers parsing.
A more fine-tuned approach is to identify the lexemes of interest
and create \*(L"predicted symbol\*(R" events for them.
.SH "Discouraged methods"
.IX Header "Discouraged methods"
Methods in this section continue to be supported, but their use is
discouraged in favor of other, better solutions.
New applications should avoid using discouraged methods.
.SS "\fIevent()\fP"
.IX Subsection "event()"
.Vb 1
\&            my $event    = $slr\->event($event_ix);
.Ve
.PP
Use of this method is discouraged in favor of the more efficient
\&\fIevents()\fR method.
The \f(CW\*(C`event()\*(C'\fR method requires one argument,
an event index.
It returns a descriptor of
the named event with that index, or a Perl \f(CW\*(C`undef\*(C'\fR
if there is no such event.
For more details on events, see the 
description of the \fIevents()\fR method.
.SS "\fIlast_completed_range()\fP"
.IX Subsection "last_completed_range()"
Use of this method is discouraged in favor of 
\&\*(L"\fIlast_completed()\fR\*(R".
Given the name of a symbol,
\&\f(CW\*(C`last_completed_range()\*(C'\fR
returns the G1 start and G1 end locations of the most recent match.
If there was more than one most recent match,
\&\f(CW\*(C`last_completed_range()\*(C'\fR
returns the longest.
If there was no match,
\&\f(CW\*(C`last_completed_range()\*(C'\fR
returns the empty array in array context
and a Perl false in scalar context.
.SS "\fIrange_to_string()\fP"
.IX Subsection "range_to_string()"
Use of this method is discouraged in favor of 
\&\*(L"\fIsubstring()\fR\*(R".
Given a G1 start and a G1 end location,
\&\f(CW\*(C`range_to_string()\*(C'\fR
returns the substring of the input
stream that is between the two.
The \f(CW\*(C`range_to_string()\*(C'\fR method 
assumes that
the application read forward smoothly in the input stream,
while reading
the sequence of G1 locations.
When that is not the case,
\&\f(CW\*(C`range_to_string()\*(C'\fR behaves in
much the same way as described above
for \*(L"\fIsubstring()\fR\*(R".
.SH "Copyright and License"
.IX Header "Copyright and License"
.Vb 5
\&  Copyright 2014 Jeffrey Kegler
\&  This file is part of Marpa::R2.  Marpa::R2 is free software: you can
\&  redistribute it and/or modify it under the terms of the GNU Lesser
\&  General Public License as published by the Free Software Foundation,
\&  either version 3 of the License, or (at your option) any later version.
\&
\&  Marpa::R2 is distributed in the hope that it will be useful,
\&  but WITHOUT ANY WARRANTY; without even the implied warranty of
\&  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
\&  Lesser General Public License for more details.
\&
\&  You should have received a copy of the GNU Lesser
\&  General Public License along with Marpa::R2.  If not, see
\&  http://www.gnu.org/licenses/.
.Ve