FWD » Core Development » Conversion Tools

The core rules have these forms:

/**
 * <standard_gcd_javadoc>
 */
rule_name <returns_clause> <parameters>
   :
      {
         <init_action>
      }
      <matching>
      {
         <exit_action>
      }
   ;

• <standard_gcd_javadoc> MUST include all parameters, return value and throws clauses (check javadoc on the oracle JDK, there are missing throws clauses in our current grammar)
• <returns_clause>, <parameters> are optional
• the <init_action> and <exit_action> are optional and if not present the curly braces will not be there
• notice the indentation of <matching>, <matching> can be single line or multi-line
  • if all content fits on a single line (less than 110 chars), then doing so is preferred, see SINGLE LINE below
  • if the content is more than 110 chars, then follow the pattern of MULTI-LINE below

SINGLE LINE example:

/**
 * <javadoc_here>
 */
rule_name
   :
      ROOT_TOKEN^ some_rule ( alternative1 | alternative2 ) ANOTHER_TOKEN YET_ONE_MORE_TOKEN
   ;

The matches are indented from the :, the ; is aligned with the : and the entire matching is done on a single line. The root token doesn't have to be first (if the tree generation needs something different, that is fine).

MULTI-LINE example:

/**
 * <javadoc_here>
 */
rule_name
   :
      ROOT_TOKEN^
      some_rule
      (
         <options>
         :
           <semantic_predicate_alt1>
           alternative1         
         | <semantic_predicate_alt2>
           alternative2
         | alternative3
         | ...
         | alternativeN
      )
      ANOTHER_TOKEN
      YET_ONE_MORE_TOKEN
   ;

Notice how the subrule indents. The predicates (<semantic_predicate_altX>) are optional. Notice how they precede their associated alternative and are split onto their own line if they exist.

The <options> block is optional.

Please reflect these ideas into the wiki page.

Some additional rules:

1. Do not use the shorthand syntax that drops () for subrule processing when there is only one element matched.

ANTLR4 allows rule_name? instead of (rule_name)?. This same shortcut is also available for + and *. Do not use it. Put the parenthesis into the code so that it is an explicit subrule.

This limitation also applies to the lexer, since ANTLR4 allows tokens and literals to use 'sometext'? instead of ('sometext')?. Do not use it.

2. Do not use the shorthand syntax where unambiguous token names can be referenced inside actions.

For a token, KW_SOMETHING, ANTLR4 allows the action to reference the token as $KW_SOMETHING instead of explicitly labeling the token. Please use the explicitly labeled form s=KW_SOMETHING which then would be a $s reference in the action.

3. Do not use dynamically scoped attributes. Instead, pass local data down the call stack where needed so that the linkage is explicit.

ANTLR4 allows any rule to use a $rule_name::local_member reference in an action. This is fragile (because it depends on that rule being in the call stack. It is also confusing since it is defined somewhere else and is not a data member.