File: //usr/share/doc/racc/en/grammar.en.html
<?xml version="1.0" ?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>rdoc/en/grammar.en</title>
</head>
<body>
<h1><a name="label-0" id="label-0">Racc Grammar File Reference</a></h1><!-- RDLabel: "Racc Grammar File Reference" -->
<h2><a name="label-1" id="label-1">Global Structure</a></h2><!-- RDLabel: "Global Structure" -->
<h2><a name="label-2" id="label-2">Class Block and User Code Block</a></h2><!-- RDLabel: "Class Block and User Code Block" -->
<p>There's two block on toplevel.
one is 'class' block, another is 'user code' block. 'user code' block MUST
places after 'class' block.</p>
<h2><a name="label-3" id="label-3">Comment</a></h2><!-- RDLabel: "Comment" -->
<p>You can insert comment about all places. Two style comment can be used,
Ruby style (#.....) and C style (/*......*/) .</p>
<h2><a name="label-4" id="label-4">Class Block</a></h2><!-- RDLabel: "Class Block" -->
<p>The class block is formed like this:
--
class CLASS_NAME</p>
<pre>[precedance table]
[token declearations]
[expected number of S/R conflict]
[options]
[semantic value convertion]
[start rule]</pre>
<p>rule</p>
<pre>GRAMMARS</pre>
<p>--
CLASS_NAME is a name of parser class.
This is the name of generating parser class.</p>
<p>If CLASS_NAME includes '::', Racc outputs module clause.
For example, writing "class M::C" causes creating the code bellow:
--
module M</p>
<pre>class C
:
:
end</pre>
<p>end
--</p>
<h2><a name="label-5" id="label-5">Grammar Block</a></h2><!-- RDLabel: "Grammar Block" -->
<p>The grammar block discripts grammar which is able
to be understood by parser. Syntax is:
--
(token): (token) (token) (token).... (action)</p>
<p>(token): (token) (token) (token).... (action)</p>
<pre>| (token) (token) (token).... (action)
| (token) (token) (token).... (action)</pre>
<p>--
(action) is an action which is executed when its (token)s are found.
(action) is a ruby code block, which is surrounded by braces:
--
{ print val[0]</p>
<pre>puts val[1] }</pre>
<p>--
Note that you cannot use '%' string, here document, '%r' regexp in action.</p>
<p>Actions can be omitted.
When it is omitted, '' (empty string) is used.</p>
<p>A return value of action is a value of left side value ($$).
It is value of result, or returned value by "return" statement.</p>
<p>Here is an example of whole grammar block.
--
rule</p>
<pre>goal: definition ruls source { result = val }
definition: /* none */ { result = [] }
| definition startdesig { result[0] = val[1] }
| definition
precrule # this line continue from upper line
{
result[1] = val[1]
}
startdesig: START TOKEN</pre>
<p>--
You can use following special local variables in action.</p>
<ul>
<li>result ($$)</li>
</ul>
<p>The value of left-hand side (lhs). A default value is val[0].</p>
<ul>
<li>val ($1,$2,$3...)</li>
</ul>
<p>An array of value of right-hand side (rhs).</p>
<ul>
<li>_values (...$-2,$-1,$0)</li>
</ul>
<p>A stack of values.
DO NOT MODIFY this stack unless you know what you are doing.</p>
<h2><a name="label-6" id="label-6">Operator Precedance</a></h2><!-- RDLabel: "Operator Precedance" -->
<p>This function is equal to '%prec' in yacc.
To designate this block:
--
prechigh</p>
<pre>nonassoc '++'
left '*' '/'
left '+' '-'
right '='</pre>
<p>preclow
--
`right' is yacc's %right, `left' is yacc's %left.</p>
<p>`=' + (symbol) means yacc's %prec:
--
prechigh</p>
<pre>nonassoc UMINUS
left '*' '/'
left '+' '-'</pre>
<p>preclow</p>
<p>rule</p>
<pre>exp: exp '*' exp
| exp '-' exp
| '-' exp =UMINUS # equals to "%prec UMINUS"
:
:</pre>
<p>--</p>
<h2><a name="label-7" id="label-7">expect</a></h2><!-- RDLabel: "expect" -->
<p>Racc has bison's "expect" directive.
--</p>
<p>class MyParser
rule</p>
<pre>expect 3
:
:</pre>
<p>--
This directive declears "expected" number of shift/reduce conflict.
If "expected" number is equal to real number of conflicts,
racc does not print confliction warning message.</p>
<h2><a name="label-8" id="label-8">Declaring Tokens</a></h2><!-- RDLabel: "Declaring Tokens" -->
<p>By declaring tokens, you can avoid many meanless bugs.
If decleared token does not exist/existing token does not decleared,
Racc output warnings. Declearation syntax is:
--
token TOKEN_NAME AND_IS_THIS</p>
<pre>ALSO_THIS_IS AGAIN_AND_AGAIN THIS_IS_LAST</pre>
<p>--</p>
<h2><a name="label-9" id="label-9">Options</a></h2><!-- RDLabel: "Options" -->
<p>You can write options for racc command in your racc file.
--
options OPTION OPTION ...
--
Options are:</p>
<ul>
<li>omit_action_call</li>
</ul>
<p>omit empty action call or not.</p>
<ul>
<li>result_var</li>
</ul>
<p>use/does not use local variable "result"</p>
<p>You can use 'no_' prefix to invert its meanings.</p>
<h2><a name="label-10" id="label-10">Converting Token Symbol</a></h2><!-- RDLabel: "Converting Token Symbol" -->
<p>Token symbols are, as default,</p>
<ul>
<li>naked token string in racc file (TOK, XFILE, this_is_token, ...)
--&gt; symbol (:TOK, :XFILE, :this_is_token, ...)</li>
<li>quoted string (':', '.', '(', ...)
--&gt; same string (':', '.', '(', ...)</li>
</ul>
<p>You can change this default by "convert" block.
Here is an example:
--
convert</p>
<pre>PLUS 'PlusClass' # We use PlusClass for symbol of `PLUS'
MIN 'MinusClass' # We use MinusClass for symbol of `MIN'</pre>
<p>end
--
We can use almost all ruby value can be used by token symbol,
except 'false' and 'nil'. These are causes unexpected parse error.</p>
<p>If you want to use String as token symbol, special care is required.
For example:
--
convert</p>
<pre>class '"cls"' # in code, "cls"
PLUS '"plus\n"' # in code, "plus\n"
MIN "\"minus#{val}\"" # in code, \"minus#{val}\"</pre>
<p>end
--</p>
<h2><a name="label-11" id="label-11">Start Rule</a></h2><!-- RDLabel: "Start Rule" -->
<p>'%start' in yacc. This changes start rule.
--
start real_target
--
This statement will not be used forever, I think.</p>
<h2><a name="label-12" id="label-12">User Code Block</a></h2><!-- RDLabel: "User Code Block" -->
<p>"User Code Block" is a Ruby source code which is copied to output.
There are three user code block, "header" "inner" and "footer".</p>
<p>Format of user code is like this:
--
---- header</p>
<pre>ruby statement
ruby statement
ruby statement</pre>
<p>---- inner</p>
<pre>ruby statement
:
:</pre>
<p>--
If four '-' exist on line head,
racc treat it as beginning of user code block.
A name of user code must be one word.</p>
</body>
</html>