File: grammar.en.rdoc [Ruby 2.3.4]

    Class Index [+]


    Racc Grammar File Reference

    Global Structure

    Class Block and User Code Block

    There are two blocks on toplevel. One is ‘class’ block, another is ‘user code’ block. ‘user code’ block MUST be placed after ‘class’ block.


    You can insert comments about all places. Two style comments can be used, Ruby style ‘#.….’ and C style ‘/*.…..*/’.

    Class Block

    The class block is formed like this:

    class CLASS_NAME
      [precedance table]
      [token declarations]
      [expected number of S/R conflicts]
      [semantic value conversion]
      [start rule]

    CLASS_NAME is a name of parser class. This is the name of generating parser class.

    If CLASS_NAME includes ‘::’, Racc outputs module clause. For example, writing “class M::C” causes creating the code below:

    module M
      class C

    Grammar Block

    The grammar block describes grammar which is able to be understood by parser. Syntax is:

    (token): (token) (token) (token).... (action)
    (token): (token) (token) (token).... (action)
           | (token) (token) (token).... (action)
           | (token) (token) (token).... (action)

    (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]
      puts val[1] }

    Note that you cannot use ‘%’ string, here document, ‘%r’ regexp in action.

    Actions can be omitted. When it is omitted, ” (empty string) is used.

    A return value of action is a value of left side value ($$). It is value of result, or returned value by `return` statement.

    Here is an example of whole grammar block.

      goal: definition rules source { result = val }
      definition:    none      { result = [] }
        | definition startdesig  { result[0] = val[1] }
        | definition
                 precrule   # this line continues from upper line
            result[1] = val[1]
      startdesig: START TOKEN

    You can use the following special local variables in action:

    result ($$)

    The value of left-hand side (lhs). A default value is val.

    val ($1,$2,$3...)

    An array of value of right-hand side (rhs).

    _values (...$-2,$-1,$0)

    A stack of values. DO NOT MODIFY this stack unless you know what you are doing.

    Operator Precedence

    This function is equal to ‘%prec’ in yacc. To designate this block:

      nonassoc '++'
      left     '*' '/'
      left     '+' '-'
      right    '='

    `right` is yacc’s %right, `left` is yacc’s %left.

    `=` + (symbol) means yacc’s %prec:

      nonassoc UMINUS
      left '*' '/'
      left '+' '-'
      exp: exp '*' exp
         | exp '-' exp
         | '-' exp       =UMINUS   # equals to "%prec UMINUS"


    Racc has bison’s “expect” directive.

    # Example
    class MyParser
      expect 3

    This directive declares “expected” number of shift/reduce conflicts. If “expected” number is equal to real number of conflicts, Racc does not print conflict warning message.

    Declaring Tokens

    By declaring tokens, you can avoid many meaningless bugs. If declared token does not exist or existing token does not decleared, Racc output warnings. Declaration syntax is:



    You can write options for Racc command in your Racc file.

    options OPTION OPTION ...

    Options are:


    omits empty action call or not.


    uses local variable “result” or not.

    You can use ‘no_’ prefix to invert their meanings.

    Converting Token Symbol

    Token symbols are, as default,

    naked token string in Racc file (TOK, XFILE, this_is_token, ...)
    --> symbol (:TOK, :XFILE, :this_is_token, ...)
    quoted string (':', '.', '(', ...)
    --> same string (':', '.', '(', ...)

    You can change this default by “convert” block. Here is an example:

      PLUS 'PlusClass'      # We use PlusClass for symbol of `PLUS'
      MIN  'MinusClass'     # We use MinusClass for symbol of `MIN'

    We can use almost all ruby value can be used by token symbol, except ‘false’ and ‘nil’. These cause unexpected parse error.

    If you want to use String as token symbol, special care is required. For example:

      class '"cls"'            # in code, "cls"
      PLUS '"plus\n"'          # in code, "plus\n"
      MIN  "\"minus#{val}\""   # in code, \"minus#{val}\"

    Start Rule

    ‘%start’ in yacc. This changes start rule.

    start real_target

    User Code Block

    “User Code Block” is a Ruby source code which is copied to output. There are three user code blocks, “header” “inner” and “footer”.

    Format of user code is like this:

    ---- header
      ruby statement
      ruby statement
      ruby statement
    ---- inner
      ruby statement

    If four ‘-’ exist on the line head, Racc treats it as the beginning of the user code block. The name of the user code block must be one word.