# Racc - ri - phpman

= **Racc**

(from gem rdoc-7.2.0)
------------------------------------------------------------------------


## Racc is an [LALR(1)](https://www.chedong.com/phpMan.php/man/LALR/1/markdown) parser generator. It is written in Ruby itself, and
generates Ruby programs.

== **Command-line Reference**

  racc [-o<var>filename</var>] [--output-file=<var>filename</var>]
       [-e<var>rubypath</var>] [--executable=<var>rubypath</var>]
       [-v] [--verbose]
       [-O<var>filename</var>] [--log-file=<var>filename</var>]
       [-g] [--debug]
       [-E] [--embedded]
       [-l] [--no-line-convert]
       [-c] [--line-convert-all]
       [-a] [--no-omit-actions]
       [-C] [--check-only]
       [-S] [--output-status]
       [--version] [--copyright] [--help] <var>grammarfile</var>

grammarfile:
### Racc grammar file. Any extension is permitted.

-o+outfile+, --output-file=outfile:
  A filename for output. default is <filename>.tab.rb

-O+filename+, --log-file=filename:
### Place logging output in file filename. Default log file name is
  <filename>.output.

-e+rubypath+, --executable=rubypath:
  output executable file(mode 755). where path is the Ruby interpreter.

-v, --verbose:
  verbose mode. create filename.output file, like yacc's y.output file.

-g, --debug:
  add debug code to parser class. To display debugging information, use
  this '-g' option and set @yydebug true in parser class.

-E, --embedded:
  Output parser which doesn't need runtime files (racc/parser.rb).

-F, --frozen:
### Output parser which declares frozenstringliterals: true

-C, --check-only:
### Check syntax of racc grammar file and quit.

-S, --output-status:
### Print messages time to time while compiling.

-l, --no-line-convert:
  turns off line number converting.

-c, --line-convert-all:
### Convert line number of actions, inner, header and footer.

-a, --no-omit-actions:
### Call all actions, even if an action is empty.

--version:
  print Racc version and quit.

--copyright:
### Print copyright and quit.

--help:
### Print usage and quit.


== **Generating Parser Using Racc**

To compile Racc grammar file, simply type:

  $ racc parse.y

This creates Ruby script file "parse.tab.y". The -o option can change
the output filename.

== **Writing A Racc Grammar File**

## If you want your own parser, you have to write a grammar file. A grammar
file contains the name of your parser class, grammar for the parser,
user code, and anything else. When writing a grammar file, yacc's
knowledge is helpful. If you have not used yacc before, Racc is not too
difficult.

Here's an example Racc grammar file.

  class Calcparser
  rule
    target: exp { print val[0] }

    exp: exp '+' exp
       | exp '*' exp
       | '(' exp ')'
       | NUMBER
  end

## Racc grammar files resemble yacc files. But (of course), this is Ruby
code. yacc's $$ is the 'result', $0, $1... is an array called 'val', and
$-1, $-2... is an array called '_values'.

## See the Grammar File Reference( rdoc-ref:lib/racc/rdoc/grammar.en.rdoc )
for more information on grammar files.

== **Parser**

## Then you must prepare the parse entry method. There are two types of
parse methods in Racc, [Racc::Parser](https://www.chedong.com/phpMan.php/perldoc/Racc%3A%3AParser/markdown)#do_parse and [Racc::Parser](https://www.chedong.com/phpMan.php/perldoc/Racc%3A%3AParser/markdown)#yyparse

[Racc::Parser](https://www.chedong.com/phpMan.php/perldoc/Racc%3A%3AParser/markdown)#do_parse is simple.

It's yyparse() of yacc, and [Racc::Parser](https://www.chedong.com/phpMan.php/perldoc/Racc%3A%3AParser/markdown)#next_token is yylex(). This
method must returns an array like [TOKENSYMBOL, ITS_VALUE]. EOF is
[false, false]. (TOKENSYMBOL is a Ruby symbol (taken from String#intern)
by default. If you want to change this, see the grammar reference.

[Racc::Parser](https://www.chedong.com/phpMan.php/perldoc/Racc%3A%3AParser/markdown)#yyparse is little complicated, but useful. It does not use
[Racc::Parser](https://www.chedong.com/phpMan.php/perldoc/Racc%3A%3AParser/markdown)#next_token, instead it gets tokens from any iterator.

For example, yyparse(obj, :scan) causes calling +obj#scan+, and you can
return tokens by yielding them from +obj#scan+.

== **Debugging**

When debugging, "-v" or/and the "-g" option is helpful.

"-v" creates verbose log file (.output). "-g" creates a "Verbose
Parser". Verbose Parser prints the internal status when parsing. But
it's _not_ automatic. You must use -g option and set +@yydebug+ to
true in order to get output. -g option only creates the verbose parser.

=== **Racc reported syntax error.**

Isn't there too many "end"? grammar of racc file is changed in v0.10.

Racc does not use '%' mark, while yacc uses huge number of '%' marks..

=== **Racc reported "XXXX conflicts".**

Try "racc -v xxxx.y". It causes producing racc's internal log file,
xxxx.output.

=== **Generated parsers does not work correctly**

Try "racc -g xxxx.y". This command let racc generate "debugging parser".
Then set @yydebug=true in your parser. It produces a working log of your
parser.

== **Re-distributing Racc runtime**

A parser, which is created by Racc, requires the Racc runtime module;
racc/parser.rb.

## Ruby 1.8.x comes with Racc runtime module, you need NOT distribute Racc
runtime files.

## If you want to include the Racc runtime module with your parser. This
can be done by using '-E' option:

  $ racc -E -omyparser.rb myparser.y

This command creates myparser.rb which `includes' Racc runtime. Only you
must do is to distribute your parser file (myparser.rb).

## Note: parser.rb is ruby license, but your parser is not. Your own parser
is completely yours.



## Racc is an [LALR(1)](https://www.chedong.com/phpMan.php/man/LALR/1/markdown) parser generator. It is written in Ruby itself, and
generates Ruby programs.

== **Command-line Reference**

  racc [-o<var>filename</var>] [--output-file=<var>filename</var>]
       [-e<var>rubypath</var>] [--executable=<var>rubypath</var>]
       [-v] [--verbose]
       [-O<var>filename</var>] [--log-file=<var>filename</var>]
       [-g] [--debug]
       [-E] [--embedded]
       [-l] [--no-line-convert]
       [-c] [--line-convert-all]
       [-a] [--no-omit-actions]
       [-C] [--check-only]
       [-S] [--output-status]
       [--version] [--copyright] [--help] <var>grammarfile</var>

grammarfile:
### Racc grammar file. Any extension is permitted.

-o+outfile+, --output-file=outfile:
  A filename for output. default is <filename>.tab.rb

-O+filename+, --log-file=filename:
### Place logging output in file filename. Default log file name is
  <filename>.output.

-e+rubypath+, --executable=rubypath:
  output executable file(mode 755). where path is the Ruby interpreter.

-v, --verbose:
  verbose mode. create filename.output file, like yacc's y.output file.

-g, --debug:
  add debug code to parser class. To display debugging information, use
  this '-g' option and set @yydebug true in parser class.

-E, --embedded:
  Output parser which doesn't need runtime files (racc/parser.rb).

-F, --frozen:
### Output parser which declares frozenstringliterals: true

-C, --check-only:
### Check syntax of racc grammar file and quit.

-S, --output-status:
### Print messages time to time while compiling.

-l, --no-line-convert:
  turns off line number converting.

-c, --line-convert-all:
### Convert line number of actions, inner, header and footer.

-a, --no-omit-actions:
### Call all actions, even if an action is empty.

--version:
  print Racc version and quit.

--copyright:
### Print copyright and quit.

--help:
### Print usage and quit.


== **Generating Parser Using Racc**

To compile Racc grammar file, simply type:

  $ racc parse.y

This creates Ruby script file "parse.tab.y". The -o option can change
the output filename.

== **Writing A Racc Grammar File**

## If you want your own parser, you have to write a grammar file. A grammar
file contains the name of your parser class, grammar for the parser,
user code, and anything else. When writing a grammar file, yacc's
knowledge is helpful. If you have not used yacc before, Racc is not too
difficult.

Here's an example Racc grammar file.

  class Calcparser
  rule
    target: exp { print val[0] }

    exp: exp '+' exp
       | exp '*' exp
       | '(' exp ')'
       | NUMBER
  end

## Racc grammar files resemble yacc files. But (of course), this is Ruby
code. yacc's $$ is the 'result', $0, $1... is an array called 'val', and
$-1, $-2... is an array called '_values'.

## See the Grammar File Reference( rdoc-ref:lib/racc/rdoc/grammar.en.rdoc )
for more information on grammar files.

== **Parser**

## Then you must prepare the parse entry method. There are two types of
parse methods in Racc, [Racc::Parser](https://www.chedong.com/phpMan.php/perldoc/Racc%3A%3AParser/markdown)#do_parse and [Racc::Parser](https://www.chedong.com/phpMan.php/perldoc/Racc%3A%3AParser/markdown)#yyparse

[Racc::Parser](https://www.chedong.com/phpMan.php/perldoc/Racc%3A%3AParser/markdown)#do_parse is simple.

It's yyparse() of yacc, and [Racc::Parser](https://www.chedong.com/phpMan.php/perldoc/Racc%3A%3AParser/markdown)#next_token is yylex(). This
method must returns an array like [TOKENSYMBOL, ITS_VALUE]. EOF is
[false, false]. (TOKENSYMBOL is a Ruby symbol (taken from String#intern)
by default. If you want to change this, see the grammar reference.

[Racc::Parser](https://www.chedong.com/phpMan.php/perldoc/Racc%3A%3AParser/markdown)#yyparse is little complicated, but useful. It does not use
[Racc::Parser](https://www.chedong.com/phpMan.php/perldoc/Racc%3A%3AParser/markdown)#next_token, instead it gets tokens from any iterator.

For example, yyparse(obj, :scan) causes calling +obj#scan+, and you can
return tokens by yielding them from +obj#scan+.

== **Debugging**

When debugging, "-v" or/and the "-g" option is helpful.

"-v" creates verbose log file (.output). "-g" creates a "Verbose
Parser". Verbose Parser prints the internal status when parsing. But
it's _not_ automatic. You must use -g option and set +@yydebug+ to
true in order to get output. -g option only creates the verbose parser.

=== **Racc reported syntax error.**

Isn't there too many "end"? grammar of racc file is changed in v0.10.

Racc does not use '%' mark, while yacc uses huge number of '%' marks..

=== **Racc reported "XXXX conflicts".**

Try "racc -v xxxx.y". It causes producing racc's internal log file,
xxxx.output.

=== **Generated parsers does not work correctly**

Try "racc -g xxxx.y". This command let racc generate "debugging parser".
Then set @yydebug=true in your parser. It produces a working log of your
parser.

== **Re-distributing Racc runtime**

A parser, which is created by Racc, requires the Racc runtime module;
racc/parser.rb.

## Ruby 1.8.x comes with Racc runtime module, you need NOT distribute Racc
runtime files.

## If you want to include the Racc runtime module with your parser. This
can be done by using '-E' option:

  $ racc -E -omyparser.rb myparser.y

This command creates myparser.rb which `includes' Racc runtime. Only you
must do is to distribute your parser file (myparser.rb).

## Note: parser.rb is ruby license, but your parser is not. Your own parser
is completely yours.
------------------------------------------------------------------------
= **Constants:**

Copyright:
  [not documented]

VERSION:
  [not documented]

Version:
  [not documented]