This file is indexed.

/usr/share/perl5/Parse/Yapp.pm is in libparse-yapp-perl 1.21-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
#
# Module Parse::Yapp.pm.
#
# Copyright © 1998, 1999, 2000, 2001, Francois Desarmenien.
# Copyright © 2017 William N. Braswell, Jr.
# All Rights Reserved.
#
# See the Copyright section at the end of the Parse/Yapp.pm pod section
# for usage and distribution rights.
#
#
package Parse::Yapp;

use strict;
use vars qw($VERSION @ISA);
@ISA = qw(Parse::Yapp::Output);

use Parse::Yapp::Output;

# CORRELATION #py001: $VERSION must be changed in both Parse::Yapp & Parse::Yapp::Driver
our $VERSION = '1.21';

1;

__END__

=encoding UTF-8

=head1 NAME

Parse::Yapp - Perl extension for generating and using LALR parsers. 

=head1 SYNOPSIS

  yapp -m MyParser grammar_file.yp

  ...

  use MyParser;

  $parser=new MyParser();
  $value=$parser->YYParse(yylex => \&lexer_sub, yyerror => \&error_sub);

  $nberr=$parser->YYNberr();

  $parser->YYData->{DATA}= [ 'Anything', 'You Want' ];

  $data=$parser->YYData->{DATA}[0];

=head1 DESCRIPTION

Parse::Yapp (Yet Another Perl Parser compiler) is a collection of modules
that let you generate and use yacc like thread safe (reentrant) parsers with
perl object oriented interface.

The script yapp is a front-end to the Parse::Yapp module and let you
easily create a Perl OO parser from an input grammar file.

=head2 The Grammar file

=over 4

=item C<Comments>

Through all your files, comments are either Perl style, introduced by I<#>
up to the end of line, or C style, enclosed between  I</*> and I<*/>.


=item C<Tokens and string literals>


Through all the grammar files, two kind of symbols may appear:
I<Non-terminal> symbols, called also I<left-hand-side> symbols,
which are the names of your rules, and I<Terminal> symbols, called
also I<Tokens>.

Tokens are the symbols your lexer function will feed your parser with
(see below). They are of two flavours: symbolic tokens and string
literals.

Non-terminals and symbolic tokens share the same identifier syntax:

		[A-Za-z][A-Za-z0-9_]*

String literals are enclosed in single quotes and can contain almost
anything. They will be output to your parser file double-quoted, making
any special character as such. '"', '$' and '@' will be automatically
quoted with '\', making their writing more natural. On the other hand,
if you need a single quote inside your literal, just quote it with '\'.

You cannot have a literal I<'error'> in your grammar as it would
confuse the driver with the I<error> token. Use a symbolic token instead.
In case you inadvertently use it, this will produce a warning telling you
you should have written it I<error> and will treat it as if it were the
I<error> token, which is certainly NOT what you meant.


=item C<Grammar file syntax>

It is very close to yacc syntax (in fact, I<Parse::Yapp> should compile
a clean I<yacc> grammar without any modification, whereas the opposite
is not true).

This file is divided in three sections, separated by C<%%>:

	header section
	%%
	rules section
	%%
	footer section

=over 4

=item B<The Header Section> section may optionally contain:

=over

=item *

One or more code blocks enclosed inside C<%{> and C<%}> just like in
yacc. They may contain any valid Perl code and will be copied verbatim
at the very beginning of the parser module. They are not as useful as
they are in yacc, but you can use them, for example, for global variable
declarations, though you will notice later that such global variables can
be avoided to make a reentrant parser module.

=item *

Precedence declarations, introduced by C<%left>, C<%right> and C<%nonassoc>
specifying associativity, followed by the list of tokens or litterals
having the same precedence and associativity.
The precedence being the latter declared will be having the highest level.
(see the yacc or bison manuals for a full explanation of how they work,
as they are implemented exactly the same way in Parse::Yapp)

=item *

C<%start> followed by a rule's left hand side, declaring this rule to
be the starting rule of your grammar. The default, when C<%start> is not
used, is the first rule in your grammar section.

=item *

C<%token> followed by a list of symbols, forcing them to be recognized
as tokens, generating a syntax error if used in the left hand side of
a rule declaration.
Note that in Parse::Yapp, you I<don't> need to declare tokens as in yacc: any
symbol not appearing as a left hand side of a rule is considered to be
a token.
Other yacc declarations or constructs such as C<%type> and C<%union> are
parsed but (almost) ignored.

=item *

C<%expect> followed by a number, suppress warnings about number of Shift/Reduce
conflicts when both numbers match, a la bison.

=back

=back

=item B<The Rule Section> contains your grammar rules:

A rule is made of a left-hand-side symbol, followed by a C<':'> and one
or more right-hand-sides separated by C<'|'> and terminated by a C<';'>:

    exp:    exp '+' exp
        |   exp '-' exp
        ;

A right hand side may be empty:

    input:  #empty
        |   input line
        ;

(if you have more than one empty rhs, Parse::Yapp will issue a warning,
as this is usually a mistake, and you will certainly have a reduce/reduce
conflict)


A rhs may be followed by an optional C<%prec> directive, followed
by a token, giving the rule an explicit precedence (see yacc manuals
for its precise meaning) and optional semantic action code block (see
below).

    exp:   '-' exp %prec NEG { -$_[1] }
        |  exp '+' exp       { $_[1] + $_[3] }
        |  NUM
        ;

Note that in Parse::Yapp, a lhs I<cannot> appear more than once as
a rule name (This differs from yacc).


=item C<The footer section>

may contain any valid Perl code and will be appended at the very end
of your parser module. Here you can write your lexer, error report
subs and anything relevant to you parser.

=item C<Semantic actions>

Semantic actions are run every time a I<reduction> occurs in the
parsing flow and they must return a semantic value.

They are (usually, but see below C<In rule actions>) written at
the very end of the rhs, enclosed with C<{ }>, and are copied verbatim
to your parser file, inside of the rules table.

Be aware that matching braces in Perl is much more difficult than
in C: inside strings they don't need to match. While in C it is
very easy to detect the beginning of a string construct, or a
single character, it is much more difficult in Perl, as there
are so many ways of writing such literals. So there is no check
for that today. If you need a brace in a double-quoted string, just
quote it (C<\{> or C<\}>). For single-quoted strings, you will need
to make a comment matching it I<in th right order>.
Sorry for the inconvenience.

    {
        "{ My string block }".
        "\{ My other string block \}".
        qq/ My unmatched brace \} /.
        # Force the match: {
        q/ for my closing brace } /
        q/ My opening brace { /
        # must be closed: }
    }

All of these constructs should work.


In Parse::Yapp, semantic actions are called like normal Perl sub calls,
with their arguments passed in C<@_>, and their semantic value are
their return values.

$_[1] to $_[n] are the parameters just as $1 to $n in yacc, while
$_[0] is the parser object itself.

Having $_[0] being the parser object itself allows you to call
parser methods. That's how the yacc macros are implemented:

	yyerrok is done by calling $_[0]->YYErrok
	YYERROR is done by calling $_[0]->YYError
	YYACCEPT is done by calling $_[0]->YYAccept
	YYABORT is done by calling $_[0]->YYAbort

All those methods explicitly return I<undef>, for convenience.

    YYRECOVERING is done by calling $_[0]->YYRecovering

Four useful methods in error recovery sub

    $_[0]->YYCurtok
    $_[0]->YYCurval
    $_[0]->YYExpect
    $_[0]->YYLexer

return respectivly the current input token that made the parse fail,
its semantic value (both can be used to modify their values too, but
I<know what you are doing> ! See I<Error reporting routine> section for
an example), a list which contains the tokens the parser expected when
the failure occurred and a reference to the lexer routine.

Note that if C<$_[0]-E<gt>YYCurtok> is declared as a C<%nonassoc> token,
it can be included in C<$_[0]-E<gt>YYExpect> list whenever the input
try to use it in an associative way. This is not a bug: the token
IS expected to report an error if encountered.

To detect such a thing in your error reporting sub, the following
example should do the trick:

        grep { $_[0]->YYCurtok eq $_ } $_[0]->YYExpect
    and do {
        #Non-associative token used in an associative expression
    };

Accessing semantics values on the left of your reducing rule is done
through the method

    $_[0]->YYSemval( index )

where index is an integer. Its value being I<1 .. n> returns the same values
than I<$_[1] .. $_[n]>, but I<-n .. 0> returns values on the left of the rule
being reduced (It is related to I<$-n .. $0 .. $n> in yacc, but you
cannot use I<$_[0]> or I<$_[-n]> constructs in Parse::Yapp for obvious reasons)


There is also a provision for a user data area in the parser object,
accessed by the method:

    $_[0]->YYData

which returns a reference to an anonymous hash, which let you have
all of your parsing data held inside the object (see the Calc.yp
or ParseYapp.yp files in the distribution for some examples).
That's how you can make you parser module reentrant: all of your
module states and variables are held inside the parser object.

Note: unfortunately, method calls in Perl have a lot of overhead,
      and when YYData is used, it may be called a huge number
      of times. If your are not a *real* purist and efficiency
      is your concern, you may access directly the user-space
      in the object: $parser->{USER} wich is a reference to an
      anonymous hash array, and then benchmark.

If no action is specified for a rule, the equivalant of a default
action is run, which returns the first parameter:

   { $_[1] }

=item C<In rule actions>

It is also possible to embed semantic actions inside of a rule:

    typedef:    TYPE { $type = $_[1] } identlist { ... } ;

When the Parse::Yapp's parser encounter such an embedded action, it modifies
the grammar as if you wrote (although @x-1 is not a legal lhs value):

    @x-1:   /* empty */ { $type = $_[1] };
    typedef:    TYPE @x-1 identlist { ... } ;

where I<x> is a sequential number incremented for each "in rule" action,
and I<-1> represents the "dot position" in the rule where the action arises.

In such actions, you can use I<$_[1]..$_[n]> variables, which are the
semantic values on the left of your action.

Be aware that the way Parse::Yapp modifies your grammar because of
I<in rule actions> can produce, in some cases, spurious conflicts
that wouldn't happen otherwise.  

=item C<Generating the Parser Module>

Now that you grammar file is written, you can use yapp on it
to generate your parser module:

    yapp -v Calc.yp

will create two files F<Calc.pm>, your parser module, and F<Calc.output>
a verbose output of your parser rules, conflicts, warnings, states
and summary.

What your are missing now is a lexer routine.

=item C<The Lexer sub>

is called each time the parser need to read the next token.

It is called with only one argument that is the parser object itself,
so you can access its methods, specially the

    $_[0]->YYData

data area.

It is its duty to return the next token and value to the parser.
They C<must> be returned as a list of two variables, the first one
is the token known by the parser (symbolic or literal), the second
one being anything you want (usually the content of the token, or the
literal value) from a simple scalar value to any complex reference,
as the parsing driver never use it but to call semantic actions:

    ( 'NUMBER', $num )
or
    ( '>=', '>=' )
or
    ( 'ARRAY', [ @values ] )

When the lexer reach the end of input, it must return the C<''>
empty token with an undef value:

     ( '', undef )

Note that your lexer should I<never> return C<'error'> as token
value: for the driver, this is the error token used for error
recovery and would lead to odd reactions.

Now that you have your lexer written, maybe you will need to output
meaningful error messages, instead of the default which is to print
'Parse error.' on STDERR.

So you will need an Error reporting sub.

=item C<Error reporting routine>

If you want one, write it knowing that it is passed as parameter
the parser object. So you can share information with the lexer
routine quite easily.

You can also use the C<$_[0]-E<gt>YYErrok> method in it, which will
resume parsing as if no error occurred. Of course, since the invalid
token is still invalid, you're supposed to fix the problem by
yourself.

The method C<$_[0]-E<gt>YYLexer> may help you, as it returns a reference
to the lexer routine, and can be called as

    ($tok,$val)=&{$_[0]->Lexer}

to get the next token and semantic value from the input stream. To
make them current for the parser, use:

    ($_[0]->YYCurtok, $_[0]->YYCurval) = ($tok, $val)

and know what you're doing...

=item C<Parsing>

Now you've got everything to do the parsing.

First, use the parser module:

    use Calc;

Then create the parser object:

    $parser=new Calc;

Now, call the YYParse method, telling it where to find the lexer
and error report subs:

    $result=$parser->YYParse(yylex => \&Lexer,
                           yyerror => \&ErrorReport);

(assuming Lexer and ErrorReport subs have been written in your current
package)

The order in which parameters appear is unimportant.

Et voila.

The YYParse method will do the parse, then return the last semantic
value returned, or undef if error recovery cannot recover.

If you need to be sure the parse has been successful (in case your
last returned semantic value I<is> undef) make a call to:

    $parser->YYNberr()

which returns the total number of time the error reporting sub has been called.

=item C<Error Recovery>

in Parse::Yapp is implemented the same way it is in yacc.

=item C<Debugging Parser>

To debug your parser, you can call the YYParse method with a debug parameter:

    $parser->YYParse( ... , yydebug => value, ... )

where value is a bitfield, each bit representing a specific debug output:

    Bit Value    Outputs
    0x01         Token reading (useful for Lexer debugging)
    0x02         States information
    0x04         Driver actions (shifts, reduces, accept...)
    0x08         Parse Stack dump
    0x10         Error Recovery tracing

To have a full debugging output, use

    debug => 0x1F

Debugging output is sent to STDERR, and be aware that it can produce
C<huge> outputs.

=item C<Standalone Parsers>

By default, the parser modules generated will need the Parse::Yapp
module installed on the system to run. They use the Parse::Yapp::Driver
which can be safely shared between parsers in the same script.

In the case you'd prefer to have a standalone module generated, use
the C<-s> switch with yapp: this will automagically copy the driver
code into your module so you can use/distribute it without the need
of the Parse::Yapp module, making it really a C<Standalone Parser>.

If you do so, please remember to include Parse::Yapp's copyright notice
in your main module copyright, so others can know about Parse::Yapp module.

=item C<Source file line numbers>

by default will be included in the generated parser module, which will help
to find the guilty line in your source file in case of a syntax error.
You can disable this feature by compiling your grammar with yapp using
the C<-n> switch.

=back

=head1 BUGS AND SUGGESTIONS

If you find bugs, think of anything that could improve Parse::Yapp
or have any questions related to it, feel free to contact the author.

=head1 AUTHOR

William N. Braswell, Jr. <wbraswell_cpan@NOSPAM.nym.hush.com>
(Remove "NOSPAM".)

=head1 SEE ALSO

yapp(1) perl(1) yacc(1) bison(1).

=head1 COPYRIGHT

The Parse::Yapp module and its related modules and shell scripts are copyright:
Copyright © 1998, 1999, 2000, 2001, Francois Desarmenien.
Copyright © 2017 William N. Braswell, Jr.

You may use and distribute them under the terms of either
the GNU General Public License or the Artistic License,
as specified in the Perl README file.

If you use the "standalone parser" option so people don't need to install
Parse::Yapp on their systems in order to run you software, this copyright
noticed should be included in your software copyright too, and the copyright
notice in the embedded driver should be left untouched.

=cut