.\" 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::ASF 3pm"
.TH Marpa::R2::ASF 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::ASF \- Marpa's abstract syntax forests (\s-1ASF\s0's)
.SH "Synopsis"
.IX Header "Synopsis"
We want to \*(L"diagram\*(R" the following sentence.
.PP
.Vb 1
\&  my $sentence = \*(Aqa panda eats shoots and leaves.\*(Aq;
.Ve
.PP
Here's the result we are looking for.  It is in Penntag form:
.PP
.Vb 9
\&  (S (NP (DT a) (NN panda))
\&     (VP (VBZ eats) (NP (NNS shoots) (CC and) (NNS leaves)))
\&     (. .))
\&  (S (NP (DT a) (NN panda))
\&     (VP (VP (VBZ eats) (NP (NNS shoots))) (CC and) (VP (VBZ leaves)))
\&     (. .))
\&  (S (NP (DT a) (NN panda))
\&     (VP (VP (VBZ eats)) (VP (VBZ shoots)) (CC and) (VP (VBZ leaves)))
\&     (. .))
.Ve
.PP
Here is the grammar.
.PP
.Vb 2
\&  :default ::= action => [ values ] bless => ::lhs
\&  lexeme default = action => [ value ] bless => ::name
\&
\&  S   ::= NP  VP  period  bless => S
\&
\&  NP  ::= NN              bless => NP
\&      |   NNS          bless => NP
\&      |   DT  NN          bless => NP
\&      |   NN  NNS         bless => NP
\&      |   NNS CC NNS  bless => NP
\&
\&  VP  ::= VBZ NP          bless => VP
\&      | VP VBZ NNS        bless => VP
\&      | VP CC VP bless => VP
\&      | VP VP CC VP bless => VP
\&      | VBZ bless => VP
\&
\&  period ~ \*(Aq.\*(Aq
\&
\&  :discard ~ whitespace
\&  whitespace ~ [\es]+
\&
\&  CC ~ \*(Aqand\*(Aq
\&  DT  ~ \*(Aqa\*(Aq | \*(Aqan\*(Aq
\&  NN  ~ \*(Aqpanda\*(Aq
\&  NNS  ~ \*(Aqshoots\*(Aq | \*(Aqleaves\*(Aq
\&  VBZ ~ \*(Aqeats\*(Aq | \*(Aqshoots\*(Aq | \*(Aqleaves\*(Aq
.Ve
.PP
Here's the code. It actually does two traversals, one that produces the full result as
shown above, and another which \*(L"prunes\*(R" the forest down to a single tree.
.PP
.Vb 7
\&  my $panda_grammar = Marpa::R2::Scanless::G\->new(
\&      { source => \e$dsl, bless_package => \*(AqPennTags\*(Aq, } );
\&  my $panda_recce = Marpa::R2::Scanless::R\->new( { grammar => $panda_grammar } );
\&  $panda_recce\->read( \e$sentence );
\&  my $asf = Marpa::R2::ASF\->new( { slr=>$panda_recce } );
\&  my $full_result = $asf\->traverse( {}, \e&full_traverser );
\&  my $pruned_result = $asf\->traverse( {}, \e&pruning_traverser );
.Ve
.PP
The code for the full traverser is in an appendix.
The pruning code is simpler.  Here it is:
.PP
.Vb 5
\&  sub penn_tag {
\&     my ($symbol_name) = @_;
\&     return q{.} if $symbol_name eq \*(Aqperiod\*(Aq;
\&     return $symbol_name;
\&  }
\&
\&  sub pruning_traverser {
\&
\&      # This routine converts the glade into a list of Penn\-tagged elements.  It is called recursively.
\&      my ($glade, $scratch)     = @_;
\&      my $rule_id     = $glade\->rule_id();
\&      my $symbol_id   = $glade\->symbol_id();
\&      my $symbol_name = $panda_grammar\->symbol_name($symbol_id);
\&
\&      # A token is a single choice, and we know enough to fully Penn\-tag it
\&      if ( not defined $rule_id ) {
\&      my $literal = $glade\->literal();
\&      my $penn_tag = penn_tag($symbol_name);
\&      return "($penn_tag $literal)";
\&      }
\&
\&      my $length = $glade\->rh_length();
\&      my @return_value = map { $glade\->rh_value($_) } 0 .. $length \- 1;
\&
\&      # Special case for the start rule
\&      return (join q{ }, @return_value) . "\en" if  $symbol_name eq \*(Aq[:start]\*(Aq ;
\&
\&      my $join_ws = q{ };
\&      $join_ws = qq{\en   } if $symbol_name eq \*(AqS\*(Aq;
\&      my $penn_tag = penn_tag($symbol_name);
\&      return "($penn_tag " . ( join $join_ws, @return_value ) . \*(Aq)\*(Aq;
\&
\&  }
.Ve
.PP
Here is the \*(L"pruned\*(R" output:
.PP
.Vb 3
\&  (S (NP (DT a) (NN panda))
\&     (VP (VBZ eats) (NP (NNS shoots) (CC and) (NNS leaves)))
\&     (. .))
.Ve
.SH "THIS INTERFACE is ALPHA and EXPERIMENTAL"
.IX Header "THIS INTERFACE is ALPHA and EXPERIMENTAL"
The interface described in this document is very much a work in progress.
It is alpha and experimental \*(--
subject to radical change without notice.
.SH "About this document"
.IX Header "About this document"
This document describes the abstract syntax forests (\s-1ASF\s0's) of
Marpa's \s-1SLIF\s0 interface.
An \s-1ASF\s0 is an efficient and practical way to represent multiple abstract syntax trees (\s-1AST\s0's).
.SH "Constructor"
.IX Header "Constructor"
.SS "\fInew()\fP"
.IX Subsection "new()"
.Vb 2
\&  my $asf = Marpa::R2::ASF\->new( { slr => $slr } );
\&  die \*(AqNo ASF\*(Aq if not defined $asf;
.Ve
.PP
Creates a new \s-1ASF\s0 object.
Must be called with a list of one or more hashes of named arguments.
Currently only one named argument is allowed, the \f(CW\*(C`slr\*(C'\fR argument, and
that argument is required.
The value of the \f(CW\*(C`slr\*(C'\fR argument must be a \s-1SLIF\s0 recognizer object.
.PP
Returns the new \s-1ASF\s0 object, or \f(CW\*(C`undef\*(C'\fR if there was a problem.
.SH "Accessor"
.IX Header "Accessor"
.SS "\fIgrammar()\fP"
.IX Subsection "grammar()"
.Vb 1
\&    my $grammar     = $asf\->grammar();
.Ve
.PP
Returns the \s-1SLIF\s0 grammar associated with the \s-1ASF.\s0
This can be convenient when using \s-1SLIF\s0 grammar methods
while examining an \s-1ASF.\s0
All failures are thrown as exceptions.
.SH "The traverser method"
.IX Header "The traverser method"
.SS "\fItraverse()\fP"
.IX Subsection "traverse()"
.Vb 1
\&  my $full_result = $asf\->traverse( {}, \e&full_traverser );
.Ve
.PP
Performs a traversal of the \s-1ASF.\s0
Returns the value of the traversal,
which is computed as described below.
It requires two arguments.
The first is a per-traversal object, which must be a Perl reference.
The second argument must be a reference to a traverser function,
Discussion of how to write a traverser follows.
The \f(CW\*(C`traverse()\*(C'\fR method may be called repeatedly for an \s-1ASF,\s0
with the same traverser, or with different ones.
.SH "How to write a traverser"
.IX Header "How to write a traverser"
The process of
writing a traverser will be familiar if you have experience with
traversing trees.
The traverser may be called at every node of the forest.
(These nodes are called \fBglades\fR.)
The traverser must return a value,
which may not be an \f(CW\*(C`undef\*(C'\fR.
The value returned by the traverser becomes the value of the glade.
The value of the topmost glade (called the \fBpeak\fR) becomes the value
of the traversal, and will be the value returned by
the \f(CW\*(C`traverse()\*(C'\fR method.
.PP
The traverser is called at most once for each glade \*(-- subsequent
attempts to determine the value of a glade will return a memoized
value.
The traverser is always invoked for the peak, and for any glade whose
value is required.
It may or may not be invoked for other glades.
.PP
The traverser is always invoked with two arguments.
The first argument will be a \fBglade object\fR.
Methods of the glade object are used to find information about
the glade, and to move around in it.
.PP
The second of the two arguments to a traverser is 
the per-traversal object, which will be shared by all calls
in the traversal.
It may be used as a \*(L"scratch pad\*(R" for information
which it is not convenient to pass via return values,
as a means of avoiding the use of globals.
.PP
\&\*(L"Moving around\*(R" in a glade means visiting its \fBparse alternatives\fR.
(Parse alternatives are usually called \fBalternatives\fR,
when the meaning is clear.)
If a glade has exactly one alternative, it is called a \fBtrivial glade\fR.
When invoked, the traverser points at the first alternative.
Alternatives after the first may be visited using the
the \f(CW\*(C`next()\*(C'\fR glade method.
.PP
Parse alternatives may be either token
alternatives or rule alternatives.
Whether or not the current alternative of the glade is a rule
can be determined using the
the \f(CW\*(C`rule_id()\*(C'\fR glade method,
which returns \f(CW\*(C`undef\*(C'\fR if and only if the glade is positioned at a token
alternative.
.PP
As a special case,
a glade representing a nulled symbol is always a trivial glade,
containing only one token alternative.
This means that a nulled symbol is always treated as a token
in this context,
even when it actually is the \s-1LHS\s0 symbol of a nulled rule.
.PP
At all alternatives,
the \f(CW\*(C`span()\*(C'\fR and
the \f(CW\*(C`literal()\*(C'\fR glade methods
are of use.
The \f(CW\*(C`symbol_id()\*(C'\fR glade method is
also always of use although its meaning varies.
At token alteratives, the \f(CW\*(C`symbol_id()\*(C'\fR method returns the 
token symbol.
At rule alteratives, the \f(CW\*(C`symbol_id()\*(C'\fR method returns the 
\&\s-1ID\s0 of the \s-1LHS\s0 of the rule.
.PP
At rule alternatives,
the \f(CW\*(C`rh_length()\*(C'\fR and
the \f(CW\*(C`rh_value()\*(C'\fR glade methods
are of use.
The \f(CW\*(C`rh_length()\*(C'\fR method returns the length of the \s-1RHS,\s0
and the \f(CW\*(C`rh_value()\*(C'\fR method returns the value of one of the
\&\s-1RHS\s0 children, as determined using its traverser.
.PP
At the peak of the \s-1ASF,\s0 the symbol will be named '\f(CW\*(C`[:start]\*(C'\fR'.
This case often requires special treatment.
Note that it is entirely possible for the peak glade to be non-trivial.
.SH "Glade methods"
.IX Header "Glade methods"
These are methods of the glade object.
Glade objects are passed as arguments to the traversal routine,
and are only valid within its scope.
.SS "\fIliteral()\fP"
.IX Subsection "literal()"
.Vb 1
\&  my $literal = $glade\->literal();
.Ve
.PP
Returns the \fBglade literal\fR, a string in the input which corresponds to this glade.
The glade literal remains constant inside a glade.
The \f(CW\*(C`literal()\*(C'\fR method accepts no arguments.
.SS "\fIspan()\fP"
.IX Subsection "span()"
.Vb 2
\&  my ( $start, $length ) = $glade\->span();
\&  my $end = $start + $length \- 1;
.Ve
.PP
Returns the \fBglade span\fR, two numbers which describe
the location which corresponds to this glade.
The first number will be the start of the span, as
an offset in the input stream.
The second number will be its length.
The glade span remains constant within a glade.
The \f(CW\*(C`span()\*(C'\fR method accepts no arguments.
.PP
Then \*(L"end\*(R" character of the span, when defined, may be calculated as
its start plus its length, minus one.
Applications should note that glades representing nulled symbols
are special cases.
They will have a length of zero and,
properly speaking,
their literals are zero length and
do not have defined first (start) and last (end) characters.
.SS "\fIsymbol_id()\fP"
.IX Subsection "symbol_id()"
.Vb 1
\&    my $symbol_id   = $glade\->symbol_id();
.Ve
.PP
Returns the \fBglade symbol\fR, which remains constant
inside a glade.
For a token alternative, the glade symbol is the token
symbol.
For a rule alternative, the glade symbol is the \s-1LHS\s0 symbol of
the rule.
The symbol \s-1ID\s0 remains constant within a glade.
The \f(CW\*(C`symbol_id()\*(C'\fR method accepts no arguments.
.SS "\fIrule_id()\fP"
.IX Subsection "rule_id()"
.Vb 1
\&  my $rule_id     = $glade\->rule_id();
.Ve
.PP
Returns the \s-1ID\s0 of the rule for the current
alternative.
The \s-1ID\s0 will be non-negative, but it may be zero.
Returns \f(CW\*(C`undef\*(C'\fR if and only if the current
alternative is a token alternative.
The \f(CW\*(C`rule_id()\*(C'\fR method accepts no arguments.
.SS "\fIrh_length()\fP"
.IX Subsection "rh_length()"
.Vb 1
\&  my $length = $glade\->rh_length();
.Ve
.PP
Returns the number of \s-1RHS\s0 children of the current rule.
On success, this will always be an integer greater than zero.
The \f(CW\*(C`rh_length()\*(C'\fR method accepts no arguments.
It is a fatal error to call \f(CW\*(C`rh_length()\*(C'\fR for a glade
that currently points to a token alternative.
.SS "\fIrh_value()\fP"
.IX Subsection "rh_value()"
.Vb 1
\&  my $child_value = $glade\->rh_value($rh_ix);
.Ve
.PP
Requires exactly one argument, \f(CW$rh_ix\fR, which must be the zero-based
index of a \s-1RHS\s0 child of the current rule instance.
Returns the value of the \f(CW$rh_ix\fR'th child of the current rule instance.
For convenient iteration,
returns \f(CW\*(C`undef\*(C'\fR if the value of the \f(CW$rh_ix\fR is greater than or equal to the \s-1RHS\s0 length.
It is a fatal error to call \f(CW\*(C`rh_value()\*(C'\fR for a glade
that currently points to a token alternative.
.SS "\fInext()\fP"
.IX Subsection "next()"
.Vb 1
\&  last CHOICE if not defined $glade\->next();
.Ve
.PP
Points the glade at the next alternative.
If there is no next alternative, returns \f(CW\*(C`undef\*(C'\fR.
On success, returns a defined value.
One of the values returned on success may be
the integer zero, so applications checking for failure
should be careful to check for a Perl defined value,
and not for a Perl true value.
.PP
In addition, because 
the \f(CW\*(C`rule_id()\*(C'\fR method 
remains constant only within a symch, and 
the \f(CW\*(C`next()\*(C'\fR method may 
change the current symch, 
\&\f(CW\*(C`rule_id()\*(C'\fR method
must always be called to obtain the current rule \s-1ID \s0
in a \f(CW\*(C`while\*(C'\fR loop where 
\&\f(CW\*(C`next()\*(C'\fR method 
is used as the exit condition.
.SH "Details"
.IX Header "Details"
This section contains additional explanations, not essential to understanding
the topic of this document.
Often they are formal or mathematical.
Some people find these helpful, but others do not, which is why
they are segregated here.
.SS "Symches and factorings"
.IX Subsection "Symches and factorings"
\&\fBSymch\fR and \fBfactoring\fR are terms which are
useful for some advanced applications.
For the purposes of this document,
the reader can consider the term \*(L"factoring\*(R" as a synonym
for \*(L"parse alternative\*(R".
A symch is either a rule symch or a token alternative.
A rule symch is a series of rule alternatives (factorings) which share the same rule \s-1ID\s0 and the same glade.
A glade's token alternative is a symch all by itself.
The term \fBsymch\fR is shorthand for \*(L"symbolic choice\*(R".
.PP
For each glade accessor, its value can be classified as
.IP "\(bu" 4
remaining constant inside a glade;
.IP "\(bu" 4
remaining constant within a symch; or
.IP "\(bu" 4
potentially varying with each factoring.
.PP
The values of the
\&\f(CW\*(C`literal()\*(C'\fR,
\&\f(CW\*(C`span()\*(C'\fR, and
\&\f(CW\*(C`symbol_id()\*(C'\fR methods
remain constant inside each glade.
The \f(CW\*(C`rule_id()\*(C'\fR method remains constant within a symch \*(--
in fact, the rule \s-1ID\s0 and the glade define a symch.
(Recall that for this purpose, the token alternative's
\&\f(CW\*(C`undef\*(C'\fR is considered a rule \s-1ID.\s0)
The values of the
\&\f(CW\*(C`rh_length()\*(C'\fR method
and the values of the
\&\f(CW\*(C`rh_value()\*(C'\fR method method
may vary with each alternative (factoring).
.PP
When moving through a glade using
the \f(CW\*(C`next()\*(C'\fR method,
alternatives within the same symch are visited
as a group.
More precisely, let
the \*(L"current rule \s-1ID\*(R"\s0 be defined as
the rule \s-1ID\s0 of the alternative at which the glade is
currently pointing.
The
\&\f(CW\*(C`next()\*(C'\fR glade method guarantees that,
before
any alternative with a rule \s-1ID\s0 different from the current rule \s-1ID\s0
is visited,
all of the so-far-unvisited alternatives that share the current rule \s-1ID\s0 will be
visited.
.SH "Appendix: full traverser code"
.IX Header "Appendix: full traverser code"
.Vb 1
\&  sub full_traverser {
\&
\&      # This routine converts the glade into a list of Penn\-tagged elements.  It is called recursively.
\&      my ($glade, $scratch)     = @_;
\&      my $rule_id     = $glade\->rule_id();
\&      my $symbol_id   = $glade\->symbol_id();
\&      my $symbol_name = $panda_grammar\->symbol_name($symbol_id);
\&
\&      # A token is a single choice, and we know enough to fully Penn\-tag it
\&      if ( not defined $rule_id ) {
\&      my $literal = $glade\->literal();
\&      my $penn_tag = penn_tag($symbol_name);
\&      return ["($penn_tag $literal)"];
\&      } ## end if ( not defined $rule_id )
\&
\&      # Our result will be a list of choices
\&      my @return_value = ();
\&
\&      CHOICE: while (1) {
\&
\&      # The results at each position are a list of choices, so
\&      # to produce a new result list, we need to take a Cartesian
\&      # product of all the choices
\&      my $length = $glade\->rh_length();
\&      my @results = ( [] );
\&      for my $rh_ix ( 0 .. $length \- 1 ) {
\&          my @new_results = ();
\&          for my $old_result (@results) {
\&          my $child_value = $glade\->rh_value($rh_ix);
\&          for my $new_value ( @{ $child_value } ) {
\&              push @new_results, [ @{$old_result}, $new_value ];
\&          }
\&          }
\&          @results = @new_results;
\&      } ## end for my $rh_ix ( 0 .. $length \- 1 )
\&
\&      # Special case for the start rule
\&      if ( $symbol_name eq \*(Aq[:start]\*(Aq ) {
\&          return [ map { join q{}, @{$_} } @results ];
\&      }
\&
\&      # Now we have a list of choices, as a list of lists.  Each sub list
\&      # is a list of Penn\-tagged elements, which we need to join into
\&      # a single Penn\-tagged element.  The result will be to collapse
\&      # one level of lists, and leave us with a list of Penn\-tagged
\&      # elements
\&      my $join_ws = q{ };
\&      $join_ws = qq{\en   } if $symbol_name eq \*(AqS\*(Aq;
\&      push @return_value,
\&          map { \*(Aq(\*(Aq . penn_tag($symbol_name) . q{ } . ( join $join_ws, @{$_} ) . \*(Aq)\*(Aq }
\&          @results;
\&
\&      # Look at the next alternative in this glade, or end the
\&      # loop if there is none
\&      last CHOICE if not defined $glade\->next();
\&
\&      } ## end CHOICE: while (1)
\&
\&      # Return the list of Penn\-tagged elements for this glade
\&      return \e@return_value;
\&  } ## end sub full_traverser
.Ve
.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