Lrama v0.5.12

4 files changed, 187 insertions, 3 deletions

diff --git a/tool/lrama/LEGAL.md b/tool/lrama/LEGAL.md
index f708ae7a1c..a3ef848514 100644
--- a/tool/lrama/LEGAL.md
+++ b/tool/lrama/LEGAL.md
@@ -7,5 +7,6 @@ mentioned below.
 
 These files are licensed under the GNU General Public License version 3 or later. See these files for more information.
 
+* template/bison/_yacc.h
 * template/bison/yacc.c
 * template/bison/yacc.h
diff --git a/tool/lrama/NEWS.md b/tool/lrama/NEWS.md
new file mode 100644
index 0000000000..de4c3bbf12
--- /dev/null
+++ b/tool/lrama/NEWS.md
@@ -0,0 +1,167 @@
+# NEWS for Lrama
+
+## Lrama 0.5.11 (2023-12-02)
+
+### Type specification of parameterizing rules
+
+Allow to specify type of rules by specifying tag, `<i>` in below example.
+Tag is post-modification style.
+
+```
+%union {
+    int i;
+}
+
+%%
+
+program         : option(number) <i>
+                | number_alias? <i>
+                ;
+```
+
+https://github.com/ruby/lrama/pull/272
+
+
+## Lrama 0.5.10 (2023-11-18)
+
+### Parameterizing rules (option, nonempty_list, list)
+
+Support function call style parameterizing rules for `option`, `nonempty_list` and `list`.
+
+https://github.com/ruby/lrama/pull/197
+
+### Parameterizing rules (separated_list)
+
+Support `separated_list` and `separated_nonempty_list` parameterizing rules.
+
+```
+program: separated_list(',', number)
+
+// Expanded to
+
+program: separated_list_number
+separated_list_number: ε
+separated_list_number: separated_nonempty_list_number
+separated_nonempty_list_number: number
+separated_nonempty_list_number: separated_nonempty_list_number ',' number
+```
+
+```
+program: separated_nonempty_list(',', number)
+
+// Expanded to
+
+program: separated_nonempty_list_number
+separated_nonempty_list_number: number
+separated_nonempty_list_number: separated_nonempty_list_number ',' number
+```
+
+https://github.com/ruby/lrama/pull/204
+
+## Lrama 0.5.9 (2023-11-05)
+
+### Parameterizing rules (suffix)
+
+Parameterizing rules are template of rules.
+It's very common pattern to write "list" grammar rule like:
+
+```
+opt_args: /* none */
+        | args
+        ;
+
+args: arg
+    | args arg
+```
+
+Lrama supports these suffixes:
+
+* `?`: option
+* `+`: nonempty list
+* `*`: list
+
+Idea of Parameterizing rules comes from Menhir LR(1) parser generator (https://gallium.inria.fr/~fpottier/menhir/manual.html#sec32).
+
+https://github.com/ruby/lrama/pull/181
+
+## Lrama 0.5.7 (2023-10-23)
+
+### Racc parser
+
+Replace Lrama's parser from hand written parser to LR parser generated by Racc.
+Lrama uses `--embedded` option to generate LR parser because Racc is changed from default gem to bundled gem by Ruby 3.3 (https://github.com/ruby/lrama/pull/132).
+
+https://github.com/ruby/lrama/pull/62
+
+## Lrama 0.5.4 (2023-08-17)
+
+### Runtime configuration for error recovery
+
+Meke error recovery function configurable on runtime by two new macros.
+
+* `YYMAXREPAIR`: Expected to return max length of repair operations. `%parse-param` is passed to this function.
+* `YYERROR_RECOVERY_ENABLED`: Expected to return bool value to determine error recovery is enabled or not. `%parse-param` is passed to this function.
+
+https://github.com/ruby/lrama/pull/74
+
+## Lrama 0.5.3 (2023-08-05)
+
+### Error Recovery
+
+Support token insert base Error Recovery.
+`-e` option is needed to generate parser with error recovery functions.
+
+https://github.com/ruby/lrama/pull/44
+
+## Lrama 0.5.2 (2023-06-14)
+
+### Named References
+
+Instead of positional references like `$1` or `$$`,
+named references allow to access to symbol by name.
+
+```
+primary: k_class cpath superclass bodystmt k_end
+           {
+             $primary = new_class($cpath, $bodystmt, $superclass);
+           }
+```
+
+Alias name can be declared.
+
+```
+expr[result]: expr[ex-left] '+' expr[ex.right]
+                {
+                  $result = $[ex-left] + $[ex.right];
+                }
+```
+
+Bison supports this feature from 2.5.
+
+### Add parse params to some macros and functions
+
+`%parse-param` are added to these macros and functions to remove ytab.sed hack from Ruby.
+
+* `YY_LOCATION_PRINT`
+* `YY_SYMBOL_PRINT`
+* `yy_stack_print`
+* `YY_STACK_PRINT`
+* `YY_REDUCE_PRINT`
+* `yysyntax_error`
+
+https://github.com/ruby/lrama/pull/40
+
+See also: https://github.com/ruby/ruby/pull/7807
+
+## Lrama 0.5.0 (2023-05-17)
+
+### stdin mode
+
+When `-` is given as grammar file name, reads the grammar source from STDIN, and takes the next argument as the input file name. This mode helps pre-process a grammar source.
+
+https://github.com/ruby/lrama/pull/8
+
+## Lrama 0.4.0 (2023-05-13)
+
+This is the first version migrated to Ruby.
+This version generates "parse.c" compatible with Bison 3.8.2.
diff --git a/tool/lrama/lib/lrama/grammar/code/rule_action.rb b/tool/lrama/lib/lrama/grammar/code/rule_action.rb
index 2c274c67ec..984c350b25 100644
--- a/tool/lrama/lib/lrama/grammar/code/rule_action.rb
+++ b/tool/lrama/lib/lrama/grammar/code/rule_action.rb
@@ -14,9 +14,23 @@ module Lrama
         # * ($1) yyvsp[i]
         # * (@1) yylsp[i]
         #
+        #
+        # Consider a rule like
+        #
+        #   class: keyword_class { $1 } tSTRING { $2 + $3 } keyword_end { $class = $1 + $keyword_end }
+        #
+        # For the semantic action of original rule:
+        #
+        # "Rule"                class: keyword_class { $1 } tSTRING { $2 + $3 } keyword_end { $class = $1 + $keyword_end }
+        # "Position in grammar"                   $1     $2      $3          $4          $5                             $6
+        # "Index for yyvsp"                       -4     -3      -2          -1           0
+        #
+        #
+        # For the first midrule action:
+        #
         # "Rule"                class: keyword_class { $1 } tSTRING { $2 + $3 } keyword_end { $class = $1 + $keyword_end }
-        # "Position in grammar"                   $1    $2      $3          $4          $5                             $6
-        # "Index for yyvsp"                       -4    -3      -2          -1           0
+        # "Position in grammar"                   $1
+        # "Index for yyvsp"                        0
         def reference_to_c(ref)
           case
           when ref.type == :dollar && ref.name == "$" # $$
@@ -45,10 +59,12 @@ module Lrama
           @rule.position_in_original_rule_rhs || @rule.rhs.count
         end
 
+        # If this is midrule action, RHS is a RHS of the original rule.
         def rhs
           (@rule.original_rule || @rule).rhs
         end
 
+        # Unlike `rhs`, LHS is always a LHS of the rule.
         def lhs
           @rule.lhs
         end
diff --git a/tool/lrama/lib/lrama/version.rb b/tool/lrama/lib/lrama/version.rb
index 42fb926aca..3e68736482 100644
--- a/tool/lrama/lib/lrama/version.rb
+++ b/tool/lrama/lib/lrama/version.rb
@@ -1,3 +1,3 @@
 module Lrama
-  VERSION = "0.5.11".freeze
+  VERSION = "0.5.12".freeze
 end