RubyGems - parser - Versions diffs - 2.7.1.1 → 2.7.2.0 - Mend

parser 2.7.1.1 → 2.7.2.0

Files changed (98) hide show

checksums.yaml +4 -4
data/lib/parser.rb +1 -0
data/lib/parser/all.rb +1 -0
data/lib/parser/ast/processor.rb +2 -0
data/lib/parser/base.rb +6 -5
data/lib/parser/builders/default.rb +146 -19
data/lib/parser/context.rb +1 -0
data/lib/parser/current.rb +10 -1
data/lib/parser/diagnostic.rb +1 -1
data/lib/parser/diagnostic/engine.rb +1 -2
data/lib/parser/lexer.rb +23770 -0
data/lib/parser/macruby.rb +6149 -0
data/lib/parser/max_numparam_stack.rb +1 -1
data/lib/parser/messages.rb +17 -0
data/lib/parser/meta.rb +5 -5
data/lib/parser/ruby18.rb +5663 -0
data/lib/parser/ruby19.rb +6092 -0
data/lib/parser/ruby20.rb +6527 -0
data/lib/parser/ruby21.rb +6578 -0
data/lib/parser/ruby22.rb +6613 -0
data/lib/parser/ruby23.rb +6624 -0
data/lib/parser/ruby24.rb +6694 -0
data/lib/parser/ruby25.rb +6662 -0
data/lib/parser/ruby26.rb +6676 -0
data/lib/parser/ruby27.rb +7803 -0
data/lib/parser/ruby28.rb +8047 -0
data/lib/parser/ruby30.rb +8052 -0
data/lib/parser/rubymotion.rb +6086 -0
data/lib/parser/runner.rb +26 -2
data/lib/parser/runner/ruby_rewrite.rb +2 -2
data/lib/parser/source/buffer.rb +3 -1
data/lib/parser/source/comment.rb +1 -1
data/lib/parser/source/comment/associator.rb +14 -4
data/lib/parser/source/map/method_definition.rb +25 -0
data/lib/parser/source/range.rb +10 -3
data/lib/parser/source/tree_rewriter.rb +73 -10
data/lib/parser/source/tree_rewriter/action.rb +114 -21
data/lib/parser/tree_rewriter.rb +1 -2
data/lib/parser/version.rb +1 -1
data/parser.gemspec +3 -18
metadata +16 -99
data/.gitignore +0 -33
data/.travis.yml +0 -42
data/.yardopts +0 -21
data/CHANGELOG.md +0 -1075
data/CONTRIBUTING.md +0 -17
data/Gemfile +0 -10
data/LICENSE.txt +0 -25
data/README.md +0 -309
data/Rakefile +0 -166
data/ci/run_rubocop_specs +0 -14
data/doc/AST_FORMAT.md +0 -2180
data/doc/CUSTOMIZATION.md +0 -37
data/doc/INTERNALS.md +0 -21
data/doc/css/.gitkeep +0 -0
data/doc/css/common.css +0 -68
data/lib/parser/lexer.rl +0 -2536
data/lib/parser/macruby.y +0 -2198
data/lib/parser/ruby18.y +0 -1934
data/lib/parser/ruby19.y +0 -2175
data/lib/parser/ruby20.y +0 -2353
data/lib/parser/ruby21.y +0 -2357
data/lib/parser/ruby22.y +0 -2364
data/lib/parser/ruby23.y +0 -2370
data/lib/parser/ruby24.y +0 -2408
data/lib/parser/ruby25.y +0 -2405
data/lib/parser/ruby26.y +0 -2413
data/lib/parser/ruby27.y +0 -2941
data/lib/parser/rubymotion.y +0 -2182
data/test/bug_163/fixtures/input.rb +0 -5
data/test/bug_163/fixtures/output.rb +0 -5
data/test/bug_163/rewriter.rb +0 -20
data/test/helper.rb +0 -60
data/test/parse_helper.rb +0 -319
data/test/racc_coverage_helper.rb +0 -133
data/test/test_base.rb +0 -31
data/test/test_current.rb +0 -29
data/test/test_diagnostic.rb +0 -96
data/test/test_diagnostic_engine.rb +0 -62
data/test/test_encoding.rb +0 -99
data/test/test_lexer.rb +0 -3608
data/test/test_lexer_stack_state.rb +0 -78
data/test/test_parse_helper.rb +0 -80
data/test/test_parser.rb +0 -9430
data/test/test_runner_parse.rb +0 -35
data/test/test_runner_rewrite.rb +0 -47
data/test/test_source_buffer.rb +0 -162
data/test/test_source_comment.rb +0 -36
data/test/test_source_comment_associator.rb +0 -367
data/test/test_source_map.rb +0 -15
data/test/test_source_range.rb +0 -187
data/test/test_source_rewriter.rb +0 -541
data/test/test_source_rewriter_action.rb +0 -46
data/test/test_source_tree_rewriter.rb +0 -253
data/test/test_static_environment.rb +0 -45
data/test/using_tree_rewriter/fixtures/input.rb +0 -3
data/test/using_tree_rewriter/fixtures/output.rb +0 -3
data/test/using_tree_rewriter/using_tree_rewriter.rb +0 -9

@@ -1,14 +0,0 @@
-#!/usr/bin/env bash
-set -eux
-bundle install
-rake generate
-git clone https://github.com/rubocop-hq/rubocop.git --depth=1
-cd rubocop
-export BUNDLE_GEMFILE=Gemfile
-echo "gem 'parser', path: '../'" > Gemfile.local
-bundle install
-bundle exec rake spec

data/doc/AST_FORMAT.md DELETED

@@ -1,2180 +0,0 @@
-AST and Source Location
-=======================
-## Literals
-### Singletons
-Format:
-~~~
-(true)
-"true"
- ~~~~ expression
-(false)
-"false"
- ~~~~~ expression
-(nil)
-"nil"
- ~~~ expression
-~~~
-### Integer
-Format:
-~~~
-(int 123)
-"123"
- ~~~ expression
-(int -123)
-"-123"
- ^ operator
- ~~~ expression
-(int 1)
-"__LINE__"
- ~~~~~~~~ expression
-~~~
-### Float
-Format:
-~~~
-(float 1.0)
-"1.0"
- ~~~ expression
-(float -1.0)
-"-1.0"
- ^ operator
- ~~~~ expression
-~~~
-### Complex
-Format:
-~~~
-(complex (0+1i))
-"1i"
- ~~ expression
-(complex (0+(1/1)*i))
-"1ri"
- ~~~ expression
-~~~
-### Rational
-Format:
-~~~
-(rational (2/1))
-"2.0r"
- ~~~~ expression
-~~~
-### String
-#### Plain
-Format:
-~~~
-(str "foo")
-"'foo'"
- ^ begin
-     ^ end
- ~~~~~ expresion
-(string "foo.rb")
-"__FILE__"
- ~~~~~~~~ expression
-~~~
-#### With interpolation
-Format:
-~~~
-(dstr (str "foo") (begin (lvar bar)) (str "baz"))
-'"foo#{bar}baz"'
- ^ begin      ^ end
- ~~~~~~~~~~~~~~ expression
-     ^^ begin (begin)
-          ^ end (begin)
-     ^^^^^^ expression (begin)
-~~~
-#### Here document
-Format:
-~~~
-(str "foo\nbar\n")
-'<<HERE␊foo␊bar␊HERE'
- ~~~~~~ expression
-        ~~~~~~~~ heredoc_body
-                ~~~~ heredoc_end
-~~~
-### Symbol
-#### Plain
-Format:
-~~~
-(sym :foo)
-":foo"
- ~~~~ expresion
-":'foo'"
-  ^ begin
-      ^ end
- ~~~~~~ expression
-~~~
-#### With interpolation
-Format:
-~~~
-(dsym (str "foo") (lvar bar) (str "baz"))
-':"foo#{bar}baz"'
-  ^ begin      ^ end
- ~~~~~~~~~~~~~~~ expression
-~~~
-### Execute-string
-#### Plain
-Format:
-~~~
-(xstr (str "foo") (lvar bar))
-"`foo#{bar}`"
- ^ begin   ^ end
- ~~~~~~~~~~~ expression
-~~~
-#### Here document
-Format:
-~~~
-(xstr (str "foo\nbar\n"))
-"<<`HERE`␊foo␊bar␊HERE"
- ~~~~~~~~ expression
-          ~~~~~~~~ heredoc_body
-                  ~~~~ heredoc_end
-~~~
-### Regexp
-#### Options
-Format:
-~~~
-(regopt :i :m)
-"im"
- ~~ expression
-~~~
-#### Regexp
-Format:
-~~~
-(regexp (str "foo") (lvar :bar) (regopt :i))
-"/foo#{bar}/i"
- ^ begin   ^ end
- ~~~~~~~~~~~ expression
-~~~
-### Array
-#### Plain
-Format:
-~~~
-(array (int 1) (int 2))
-"[1, 2]"
- ^ begin
-      ^ end
- ~~~~~~ expression
-~~~
-#### Splat
-Can also be used in argument lists: `foo(bar, *baz)`
-Format:
-~~~
-(splat (lvar :foo))
-"*foo"
- ^ operator
- ~~~~ expression
-~~~
-#### With interpolation
-Format:
-~~~
-(array (int 1) (splat (lvar :foo)) (int 2))
-"[1, *foo, 2]"
- ^ begin    ^ end
- ~~~~~~~~~~~~ expression
-~~~
-### Hash
-#### Pair
-##### With hashrocket
-Format:
-~~~
-(pair (int 1) (int 2))
-"1 => 2"
-   ~~ operator
- ~~~~~~ expression
-~~~
-##### With label (1.9)
-Format:
-~~~
-(pair (sym :answer) (int 42))
-"answer: 42"
-       ^ operator (pair)
- ~~~~~~ expression (sym)
- ~~~~~~~~~~ expression (pair)
-~~~
-#### Plain
-Format:
-~~~
-(hash (pair (int 1) (int 2)) (pair (int 3) (int 4)))
-"{1 => 2, 3 => 4}"
- ^ begin        ^ end
- ~~~~~~~~~~~~~~~~ expression
-~~~
-#### Keyword splat (2.0)
-Can also be used in argument lists: `foo(bar, **baz)`
-Format:
-~~~
-(kwsplat (lvar :foo))
-"**foo"
- ~~ operator
- ~~~~~ expression
-~~~
-#### With interpolation (2.0)
-Format:
-~~~
-(hash (pair (sym :foo) (int 2)) (kwsplat (lvar :bar)))
-"{ foo: 2, **bar }"
- ^ begin         ^ end
- ~~~~~~~~~~~~~~~~~ expression
-~~~
-### Range
-#### Inclusive
-Format:
-~~~
-(irange (int 1) (int 2))
-"1..2"
-  ~~ operator
- ~~~~ expression
-~~~
-#### Exclusive
-Format:
-~~~
-(erange (int 1) (int 2))
-"1...2"
-  ~~~ operator
- ~~~~~ expression
-~~~
-### Endless (2.6)
-Format:
-~~~
-(irange (int 1) nil)
-"1.."
-  ~~ operator
- ~~~ expression
-(erange (int 1) nil)
-"1..."
-  ~~~ operator
- ~~~~ expression
-~~~
-### Beginless (2.7)
-Format:
-~~~
-(irange nil (int 1))
-"..1"
- ~~ operator
- ~~~ expression
-(erange nil (int 1))
-"...1"
- ~~~ operator
- ~~~~ expression
-~~~
-## Access
-### Self
-Format:
-~~~
-(self)
-"self"
- ~~~~ expression
-~~~
-### Local variable
-Format:
-~~~
-(lvar :foo)
-"foo"
- ~~~ expression
-~~~
-### Instance variable
-Format:
-~~~
-(ivar :@foo)
-"@foo"
- ~~~~ expression
-~~~
-### Class variable
-Format:
-~~~
-(cvar :@@foo)
-"@@foo"
- ~~~~~ expression
-~~~
-### Global variable
-#### Regular global variable
-Format:
-~~~
-(gvar :$foo)
-"$foo"
- ~~~~ expression
-~~~
-#### Regular expression capture groups
-Format:
-~~~
-(nth-ref 1)
-"$1"
- ~~ expression
-~~~
-#### Regular expression back-references
-Format:
-~~~
-(back-ref :$&)
-"$&"
- ~~ expression
-(back-ref :$`)
-"$`"
-(back-ref :$')
-"$'"
-(back-ref :$+)
-"$+"
-~~~
-### Constant
-#### Top-level constant
-Format:
-~~~
-(const (cbase) :Foo)
-"::Foo"
-   ~~~ name
- ~~ double_colon
- ~~~~~ expression
-~~~
-#### Scoped constant
-Format:
-~~~
-(const (lvar :a) :Foo)
-"a::Foo"
-    ~~~ name
-  ~~ double_colon
- ~~~~~~ expression
-~~~
-#### Unscoped constant
-Format:
-~~~
-(const nil :Foo)
-"Foo"
- ~~~ name
- ~~~ expression
-~~~
-### defined?
-Format:
-~~~
-(defined? (lvar :a))
-"defined? a"
- ~~~~~~~~ keyword
- ~~~~~~~~~~ expression
-"defined?(a)"
- ~~~~~~~~ keyword
-         ^ begin
-           ^ end
- ~~~~~~~~~~~ expression
-~~~
-## Assignment
-### To local variable
-Format:
-~~~
-(lvasgn :foo (lvar :bar))
-"foo = bar"
-     ^ operator
- ~~~~~~~~~ expression
-~~~
-### To instance variable
-Format:
-~~~
-(ivasgn :@foo (lvar :bar))
-"@foo = bar"
-      ^ operator
- ~~~~~~~~~~ expression
-~~~
-### To class variable
-Format:
-~~~
-(cvasgn :@@foo (lvar :bar))
-"@@foo = bar"
-       ^ operator
- ~~~~~~~~~~~ expression
-~~~
-### To global variable
-Format:
-~~~
-(gvasgn :$foo (lvar :bar))
-"$foo = bar"
-      ^ operator
- ~~~~~~~~~~ expression
-~~~
-### To constant
-#### Top-level constant
-Format:
-~~~
-(casgn (cbase) :Foo (int 1))
-"::Foo = 1"
-   ~~~ name
-       ~ operator
- ~~~~~~~ expression
-~~~
-#### Scoped constant
-Format:
-~~~
-(casgn (lvar :a) :Foo (int 1))
-"a::Foo = 1"
-    ~~~ name
-        ~ operator
- ~~~~~~~~ expression
-~~~
-#### Unscoped constant
-Format:
-~~~
-(casgn nil :Foo (int 1))
-"Foo = 1"
- ~~~ name
-     ~ operator
- ~~~~~~~ expression
-~~~
-### To attribute
-Format:
-~~~
-(send (self) :foo= (int 1))
-"self.foo = 1"
-     ^ dot
-      ~~~ selector
-          ^ operator
- ~~~~~~~~~~~~ expression
-~~~
-### To attribute, using "safe navigation operator"
-Format:
-~~~
-(csend (self) :foo= (int 1))
-"self&.foo = 1"
-     ^^ dot
-       ~~~ selector
-           ^ operator
- ~~~~~~~~~~~~~ expression
-~~~
-### Multiple assignment
-#### Multiple left hand side
-Format:
-~~~
-(mlhs (lvasgn :a) (lvasgn :b))
-"a, b"
- ~~~~ expression
-"(a, b)"
- ^ begin
-      ^ end
- ~~~~~~ expression
-~~~
-#### Assignment
-Rule of thumb: every node inside `(mlhs)` is "incomplete"; to make
-it "complete", one could imagine that a corresponding node from the
-mrhs is "appended" to the node in question. This applies both to
-side-effect free assignments (`lvasgn`, etc) and side-effectful
-assignments (`send`).
-Format:
-~~~
-(masgn (mlhs (lvasgn :foo) (lvasgn :bar)) (array (int 1) (int 2)))
-"foo, bar = 1, 2"
-          ^ operator
- ~~~~~~~~~~~~~~~ expression
-(masgn (mlhs (ivasgn :@a) (cvasgn :@@b)) (array (splat (lvar :c))))
-"@a, @@b = *c"
-(masgn (mlhs (mlhs (lvasgn :a) (lvasgn :b)) (lvasgn :c)) (lvar :d))
-"a, (b, c) = d"
-(masgn (mlhs (send (self) :a=) (send (self) :[]= (int 1))) (lvar :a))
-"self.a, self[1] = a"
-~~~
-### Binary operator-assignment
-Binary operator-assignment features the same "incomplete assignments" and "incomplete calls" as [multiple assignment](#assignment-1).
-#### Variable binary operator-assignment
-Format:
-~~~
-(op-asgn (lvasgn :a) :+ (int 1))
-"a += 1"
-   ~~ operator
- ~~~~~~ expression
-(op-asgn (ivasgn :a) :+ (int 1))
-"@a += 1"
-~~~
-#### Method binary operator-assignment
-Format:
-~~~
-(op-asgn (send (ivar :@a) :b) :+ (int 1))
-"@a.b += 1"
-    ~ selector (send)
- ~~~~ expression (send)
-      ~~ operator (op-asgn)
- ~~~~~~~~~ expression (op-asgn)
-(op-asgn (send (ivar :@a) :[] (int 0) (int 1))) :+ (int 1))
-"@a[0, 1] += 1"
-   ~~~~~~ selector (send)
- ~~~~~~~~ expression (send)
-          ~~ operator (op-asgn)
- ~~~~~~~~~~~~~ expression (op-asgn)
-~~~
-### Logical operator-assignment
-Logical operator-assignment features the same "incomplete assignments" and "incomplete calls" as [multiple assignment](#assignment-1).
-#### Variable logical operator-assignment
-Format:
-~~~
-(or-asgn (ivasgn :@a) (int 1))
-"@a ||= 1"
-    ~~~ operator
- ~~~~~~~~ expression
-(and-asgn (lvasgn :a) (int 1))
-"a &&= 1"
-   ~~~ operator
- ~~~~~~~ expression
-~~~
-#### Method logical operator-assignment
-Format:
-~~~
-(or-asgn (send (ivar :@foo) :bar) (int 1))
-"@foo.bar ||= 1"
-      ~~~ selector (send)
- ~~~~~~~~ expr (send)
-          ~~~ operator (or-asgn)
- ~~~~~~~~~~~~~~ expression (or-asgn)
-(and-asgn (send (lvar :@foo) :bar) (int 1))
-"foo.bar &&= 1"
-     ~~~ selector (send)
- ~~~~~~~ expr (send)
-         ~~~ operator (and-asgn)
- ~~~~~~~~~~~~~ expression (and-asgn)
-(or-asgn (send (ivar :@foo) :[] (int 1) (int 2)) (int 1))
-"@foo[1, 2] ||= 1"
-     ~~~~~~ selector (send)
- ~~~~~~~~~~ expr (send)
-            ~~~ operator (or-asgn)
- ~~~~~~~~~~~~~~~~ expression (or-asgn)
-~~~
-## Class and module definition
-### Module
-Format:
-~~~
-(module (const nil :Foo) (nil))
-"module Foo; end"
- ~~~~~~ keyword
-             ~~~ end
-~~~
-### Class
-Format:
-~~~
-(class (const nil :Foo) (const nil :Bar) (nil))
-"class Foo < Bar; end"
- ~~~~~ keyword    ~~~ end
-           ~ operator
- ~~~~~~~~~~~~~~~~~~~~ expression
-(class (const nil :Foo) nil (nil))
-"class Foo; end"
- ~~~~~ keyword
-            ~~~ end
- ~~~~~~~~~~~~~~ expression
-~~~
-### Singleton class
-Format:
-~~~
-(sclass (lvar :a) (nil))
-"class << a; end"
- ~~~~~ keyword
-       ~~ operator
-             ~~~ end
- ~~~~~~~~~~~~~~~ expression
-~~~
-## Method (un)definition
-### Instance methods
-Format:
-~~~
-(def :foo (args) nil)
-"def foo; end"
- ~~~ keyword
-     ~~~ name
-          ~~~ end
- ~~~~~~~~~~~~ expression
-~~~
-### Singleton methods
-Format:
-~~~
-(defs (self) :foo (args) nil)
-"def self.foo; end"
- ~~~ keyword
-          ~~~ name
-               ~~~ end
- ~~~~~~~~~~~~~~~~~ expression
-~~~
-### Undefinition
-Format:
-~~~
-(undef (sym :foo) (sym :bar) (dsym (str "foo") (int 1)))
-"undef foo :bar :"foo#{1}""
- ~~~~~ keyword
- ~~~~~~~~~~~~~~~~~~~~~~~~~ expression
-~~~
-## Aliasing
-### Method aliasing
-Format:
-~~~
-(alias (sym :foo) (dsym (str "foo") (int 1)))
-"alias foo :"foo#{1}""
- ~~~~~ keyword
- ~~~~~~~~~~~~~~~~~~~~ expression
-~~~
-### Global variable aliasing
-Format:
-~~~
-(alias (gvar :$foo) (gvar :$bar))
-"alias $foo $bar"
- ~~~~~ keyword
- ~~~~~~~~~~~~~~~ expression
-(alias (gvar :$foo) (back-ref :$&))
-"alias $foo $&"
- ~~~~~ keyword
- ~~~~~~~~~~~~~~~ expression
-~~~
-## Formal arguments
-Format:
-~~~
-(args (arg :foo))
-"(foo)"
- ~~~~~ expression
-~~~
-### Required argument
-Format:
-~~~
-(arg :foo)
-"foo"
- ~~~ expression
- ~~~ name
-~~~
-### Optional argument
-Format:
-~~~
-(optarg :foo (int 1))
-"foo = 1"
- ~~~~~~~ expression
-     ^ operator
- ~~~ name
-~~~
-### Named splat argument
-Format:
-~~~
-(restarg :foo)
-"*foo"
- ~~~~ expression
-  ~~~ name
-~~~
-Begin of the `expression` points to `*`.
-### Unnamed splat argument
-Format:
-~~~
-(restarg)
-"*"
- ^ expression
-~~~
-### Block argument
-Format:
-~~~
-(blockarg :foo)
-"&foo"
-  ~~~ name
- ~~~~ expression
-~~~
-Begin of the `expression` points to `&`.
-### Auto-expanding proc argument (1.9)
-In Ruby 1.9 and later, when a proc-like closure (i.e. a closure
-created by capturing a block or with the `proc` method, but not
-with the `->{}` syntax or the `lambda` method) has exactly one
-argument, and it is called with more than one argument, the behavior
-is as if the array of all arguments was instead passed as the sole
-argument. This behavior can be prevented by adding a comma after
-the sole argument (e.g. `|foo,|`).
-Format:
-~~~
-(procarg0 (arg :foo))
-"|foo|"
-  ~~~ expression
-(procarg0 (arg :foo) (arg :bar))
-"|(foo, bar)|"
-  ~ begin
-           ~ end
-  ~~~~~~~~~~ expression
-~~~
-### Expression arguments
-Ruby 1.8 allows to use arbitrary expressions as block arguments,
-such as `@var` or `foo.bar`. Such expressions should be treated as
-if they were on the lhs of a multiple assignment.
-Format:
-~~~
-(args (arg_expr (ivasgn :@bar)))
-"|@bar|"
-(args (arg_expr (send (send nil :foo) :a=)))
-"|foo.a|"
-(args (restarg_expr (ivasgn :@bar)))
-"|*@bar|"
-(args (blockarg_expr (ivasgn :@bar)))
-"|&@bar|"
-~~~
-### Block shadow arguments
-Format:
-~~~
-(args (shadowarg :foo) (shadowarg :bar))
-"|; foo, bar|"
-~~~
-### Decomposition
-Format:
-~~~
-(def :f (args (arg :a) (mlhs (arg :foo) (restarg :bar))))
-"def f(a, (foo, *bar)); end"
-          ^ begin   ^ end
-          ~~~~~~~~~~~ expression
-~~~
-### Required keyword argument
-Format:
-~~~
-(kwarg :foo)
-"foo:"
- ~~~~ expression
- ~~~~ name
-~~~
-### Optional keyword argument
-Format:
-~~~
-(kwoptarg :foo (int 1))
-"foo: 1"
- ~~~~~~ expression
- ~~~~ name
-~~~
-### Named keyword splat argument
-Format:
-~~~
-(kwrestarg :foo)
-"**foo"
- ~~~~~ expression
-   ~~~ name
-~~~
-### Unnamed keyword splat argument
-Format:
-~~~
-(kwrestarg)
-"**"
- ~~ expression
-~~~
-### Keyword nil argument
-Format:
-~~~
-(kwnilarg)
-"**nil"
-   ~~~ name
- ~~~~~ expression
-~~~
-### Objective-C arguments
-MacRuby includes a few more syntactic "arguments" whose name becomes
-the part of the Objective-C method name, despite looking like Ruby 2.0
-keyword arguments, and are thus treated differently.
-#### Objective-C label-like keyword argument
-Format:
-~~~
-(objc-kwarg :a :b)
-"a: b"
- ~ keyword
-  ~ operator
-    ~ argument
- ~~~~ expression
-~~~
-#### Objective-C pair-like keyword argument
-Format:
-~~~
-(objc-kwarg :a :b)
-"a => b"
- ~ keyword
-   ~~ operator
-      ~ argument
- ~~~~~~ expression
-~~~
-#### Objective-C keyword splat argument
-Format:
-~~~
-(objc-restarg (objc-kwarg :foo))
-"(*a: b)"
-   ~ objc-kwarg.keyword
-    ~ objc-kwarg.operator
-      ~ objc-kwarg.argument
-  ~ operator
-  ~~~~~ expression
-~~~
-Note that these splat arguments will only be parsed inside parentheses,
-e.g. in the following code:
-~~~
-def f((*a: b)); end
-~~~
-However, the following code results in a parse error:
-~~~
-def f(*a: b); end
-~~~
-## Numbered parameters
-### Block with numbered parameters
-Ruby 2.7 introduced a feature called "numbered parameters".
-Numbered and ordinal parameters are mutually exclusive, so if the block
-has only numbered parameters it also has a different AST node.
-Note that the second child represents a total number of numbered parameters.
-Format:
-~~~
-s(:numblock,
-  s(:send, nil, :proc), 3,
-  s(:send,
-    s(:lvar, :_1), :+,
-    s(:lvar, :_3)))
-"proc { _1 + _3 }"
-      ~ begin   ~ end
- ~~~~~~~~~~~~~~~~ expression
-~~~
-## Forward arguments
-### Method definition accepting forwarding arguments
-Ruby 2.7 introduced a feature called "arguments forwarding".
-When a method takes any arguments for forwarding them in the future
-the whole `args` node gets replaced with `forward-args` node.
-Format:
-~~~
-(def :foo
-  (forward-args) nil)
-"def foo(...); end"
-            ~ end
-        ~ begin
-        ~~~~~ expression
-~~~
-### Method call taking arguments of the currently forwarding method
-Format:
-~~~
-(send nil :foo
-  (forwarded-args))
-"foo(...)"
-     ~~~ expression
-~~~
-## Send
-### To self
-Format:
-~~~
-(send nil :foo (lvar :bar))
-"foo(bar)"
- ~~~ selector
-    ^ begin
-        ^ end
- ~~~~~~~~ expression
-~~~
-### To receiver
-Format:
-~~~
-(send (lvar :foo) :bar (int 1))
-"foo.bar(1)"
-    ^ dot
-     ~~~ selector
-        ^ begin
-          ^ end
- ~~~~~~~~~~ expression
-(send (lvar :foo) :+ (int 1))
-"foo + 1"
-     ^ selector
- ~~~~~~~ expression
-(send (lvar :foo) :-@)
-"-foo"
- ^ selector
- ~~~~ expression
-(send (lvar :foo) :a= (int 1))
-"foo.a = 1"
-     ~ selector
-       ^ operator
- ~~~~~~~~~ expression
-~~~
-### To superclass
-Format of super with arguments:
-~~~
-(super (lvar :a))
-"super a"
- ~~~~~ keyword
- ~~~~~~~ expression
-(super)
-"super()"
-      ^ begin
-       ^ end
- ~~~~~ keyword
- ~~~~~~~ expression
-~~~
-Format of super without arguments (**z**ero-arity):
-~~~
-(zsuper)
-"super"
- ~~~~~ keyword
- ~~~~~ expression
-~~~
-### To block argument
-Format:
-~~~
-(yield (lvar :foo))
-"yield(foo)"
- ~~~~~ keyword
-      ^ begin
-          ^ end
- ~~~~~~~~~~ expression
-~~~
-### Indexing
-Format:
-~~~
-(index (lvar :foo) (int 1))
-"foo[1]"
-    ^ begin
-      ^ end
- ~~~~~~ expression
-(indexasgn (lvar :bar) (int 1) (int 2) (lvar :baz))
-"bar[1, 2] = baz"
-    ^ begin
-         ^ end
-           ^ operator
- ~~~~~~~~~~~~~~~ expression
-~~~
-### Passing a literal block
-~~~
-(block (send nil :foo) (args (arg :bar)) (begin ...))
-"foo do |bar|; end"
-     ~~ begin
-               ~~~ end
-     ~~~~~~~~~~~~~ expression
-~~~
-### Passing expression as block
-Used when passing expression as block `foo(&bar)`
-~~~
-(send nil :foo (int 1) (block-pass (lvar :foo)))
-"foo(1, &foo)"
-        ^ operator
-        ~~~~ expression
-~~~
-### "Stabby lambda"
-~~~
-(block (lambda) (args) nil)
-"-> {}"
- ~~ lambda.expression
-~~~
-### "Safe navigation operator"
-~~~
-(csend (send nil :foo) :bar)
-"foo&.bar"
-    ~~ dot
-~~~
-### Objective-C variadic send
-MacRuby allows to pass a variadic amount of arguments via the last
-keyword "argument". Semantically, these, together with the pair value
-of the last pair in the hash implicitly passed as the last argument,
-form an array, which replaces the pair value. Despite that, the node
-is called `objc-varargs` to distinguish it from a literal array passed
-as a value.
-~~~
-(send nil :foo (int 1) (hash (pair (sym :bar) (objc-varargs (int 1) (int 2) (nil)))))
-"foo(1, bar: 2, 3, nil)"
-             ~~~~~~~~~ expression (array)
-~~~
-## Control flow
-### Logical operators
-#### Binary (and or && ||)
-Format:
-~~~
-(and (lvar :foo) (lvar :bar))
-"foo and bar"
-     ~~~ operator
- ~~~~~~~~~~~ expression
-~~~
-~~~
-(or (lvar :foo) (lvar :bar))
-"foo or bar"
-     ~~ operator
- ~~~~~~~~~~ expression
-~~~
-#### Unary (! not) (1.8)
-Format:
-~~~
-(not (lvar :foo))
-"!foo"
- ^ operator
-"not foo"
- ~~~ operator
-~~~
-### Branching
-#### Without else
-Format:
-~~~
-(if (lvar :cond) (lvar :iftrue) nil)
-"if cond then iftrue; end"
- ~~ keyword
-         ~~~~ begin
-                      ~~~ end
- ~~~~~~~~~~~~~~~~~~~~~~~~ expression
-"if cond; iftrue; end"
- ~~ keyword
-                  ~~~ end
- ~~~~~~~~~~~~~~~~~~~~ expression
-"iftrue if cond"
-        ~~ keyword
- ~~~~~~~~~~~~~~ expression
-(if (lvar :cond) nil (lvar :iftrue))
-"unless cond then iftrue; end"
- ~~~~~~ keyword
-             ~~~~ begin
-                          ~~~ end
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ expression
-"unless cond; iftrue; end"
- ~~~~~~ keyword
-                      ~~~ end
- ~~~~~~~~~~~~~~~~~~~~~~~~ expression
-"iftrue unless cond"
-        ~~~~~~ keyword
- ~~~~~~~~~~~~~~~~~~ expression
-~~~
-#### With else
-Format:
-~~~
-(if (lvar :cond) (lvar :iftrue) (lvar :iffalse))
-"if cond then iftrue; else; iffalse; end"
- ~~ keyword
-         ~~~~ begin
-                      ~~~~ else
-                                 ~~~ end
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ expression
-"if cond; iftrue; else; iffalse; end"
- ~~ keyword
-                  ~~~~ else
-                                 ~~~ end
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ expression
-(if (lvar :cond) (lvar :iffalse) (lvar :iftrue))
-"unless cond then iftrue; else; iffalse; end"
- ~~~~~~ keyword
-             ~~~~ begin
-                          ~~~~ else
-                                         ~~~ end
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ expression
-"unless cond; iftrue; else; iffalse; end"
- ~~~~~~ keyword
-                      ~~~~ else
-                                     ~~~ end
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ expression
-~~~
-#### With elsif
-Format:
-~~~
-(if (lvar :cond1) (int 1) (if (lvar :cond2 (int 2) (int 3))))
-"if cond1; 1; elsif cond2; 2; else 3; end"
- ~~ keyword (left)
-              ~~~~~ else (left)
-                                      ~~~ end (left)
-              ~~~~~ keyword (right)
-                              ~~~~ else (right)
-                                      ~~~ end (right)
-~~~
-#### Ternary
-Format:
-~~~
-(if (lvar :cond) (lvar :iftrue) (lvar :iffalse))
-"cond ? iftrue : iffalse"
-      ^ question
-               ^ colon
- ~~~~~~~~~~~~~~~~~~~~~~~ expression
-~~~
-### Case matching
-#### When clause
-Format:
-~~~
-(when (regexp "foo" (regopt)) (begin (lvar :bar)))
-"when /foo/ then bar"
- ~~~~ keyword
-            ~~~~ begin
- ~~~~~~~~~~~~~~~~~~~ expression
-(when (int 1) (int 2) (send nil :meth))
-"when 1, 2; meth"
-(when (int 1) (splat (lvar :foo)) (send nil :meth))
-"when 1, *foo; meth"
-(when (splat (lvar :foo)) (send nil :meth))
-"when *foo; meth"
-~~~
-#### Case-expression clause
-##### Without else
-Format:
-~~~
-(case (lvar :foo) (when (str "bar") (lvar :bar)) nil)
-"case foo; when "bar"; bar; end"
- ~~~~ keyword               ~~~ end
-~~~
-##### With else
-Format:
-~~~
-(case (lvar :foo) (when (str "bar") (lvar :bar)) (lvar :baz))
-"case foo; when "bar"; bar; else baz; end"
- ~~~~ keyword               ~~~~ else ~~~ end
-~~~
-#### Case-conditions clause
-##### Without else
-Format:
-~~~
-(case nil (when (lvar :bar) (lvar :bar)) nil)
-"case; when bar; bar; end"
- ~~~~ keyword         ~~~ end
-~~~
-##### With else
-Format:
-~~~
-(case nil (when (lvar :bar) (lvar :bar)) (lvar :baz))
-"case; when bar; bar; else baz; end"
- ~~~~ keyword         ~~~~ else ~~~ end
-(case nil (lvar :baz))
-"case; else baz; end"
- ~~~~ keyword
-       ~~~~ else
-                 ~~~ end
-~~~
-### Looping
-#### With precondition
-Format:
-~~~
-(while (lvar :condition) (send nil :foo))
-"while condition do foo; end"
- ~~~~~ keyword
-                 ~~ begin
-                         ~~~ end
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~ expression
-"while condition; foo; end"
- ~~~~~ keyword
-                       ~~~ end
- ~~~~~~~~~~~~~~~~~~~~~~~~~ expression
-"foo while condition"
-     ~~~~~ keyword
- ~~~~~~~~~~~~~~~~~~~ expression
-(until (lvar :condition) (send nil :foo))
-"until condition do foo; end"
- ~~~~~ keyword
-                 ~~ begin
-                         ~~~ end
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~ expression
-(until (lvar :condition) (send nil :foo))
-"until condition; foo; end"
- ~~~~~ keyword
-                       ~~~ end
-~~~~~~~~~~~~~~~~~~~~~~~~~~ expression
-"foo until condition"
-     ~~~~~ keyword
- ~~~~~~~~~~~~~~~~~~~ expression
-~~~
-#### With postcondition
-Format:
-~~~
-(while-post (lvar :condition) (kwbegin (send nil :foo)))
-"begin; foo; end while condition"
- ~~~~~ begin (begin)
-             ~~~ end (begin)
-                 ~~~~~ keyword (while-post)
-(until-post (lvar :condition) (kwbegin (send nil :foo)))
-"begin; foo; end until condition"
- ~~~~~ begin (begin)
-             ~~~ end (begin)
-                 ~~~~~ keyword (until-post)
-~~~
-#### For-in
-Format:
-~~~
-(for (lvasgn :a) (lvar :array) (send nil :p (lvar :a)))
-"for a in array do p a; end"
- ~~~ keyword
-       ~~ in
-                ~~ begin
-                        ~~~ end
-"for a in array; p a; end"
- ~~~ keyword
-       ~~ in
-                      ~~~ end
-(for
-  (mlhs (lvasgn :a) (lvasgn :b)) (lvar :array)
-  (send nil :p (lvar :a) (lvar :b)))
-"for a, b in array; p a, b; end"
-~~~
-#### Break
-Format:
-~~~
-(break (int 1))
-"break 1"
- ~~~~~ keyword
- ~~~~~~~ expression
-~~~
-#### Next
-Format:
-~~~
-(next (int 1))
-"next 1"
- ~~~~ keyword
- ~~~~~~ expression
-~~~
-#### Redo
-Format:
-~~~
-(redo)
-"redo"
- ~~~~ keyword
- ~~~~ expression
-~~~
-### Return
-Format:
-~~~
-(return (lvar :foo))
-"return(foo)"
- ~~~~~~ keyword
- ~~~~~~~~~~~ expression
-~~~
-### Exception handling
-#### Rescue body
-Format:
-~~~
-(resbody (array (const nil :Exception) (const nil :A)) (lvasgn :bar) (int 1))
-"rescue Exception, A => bar; 1"
- ~~~~~~ keyword      ~~ assoc
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ expression
-"rescue Exception, A => bar then 1"
- ~~~~~~ keyword      ~~ assoc
-                            ~~~~ begin
-(resbody (array (const nil :Exception)) (ivasgn :bar) (int 1))
-"rescue Exception => @bar; 1"
- ~~~~~~ keyword   ~~ assoc
-(resbody nil (lvasgn :bar) (int 1))
-"rescue => bar; 1"
- ~~~~~~ keyword
-        ~~ assoc
-(resbody nil nil (int 1))
-"rescue; 1"
- ~~~~~~ keyword
-~~~
-#### Rescue statement
-##### Without else
-Format:
-~~~
-(begin
-  (rescue (send nil :foo) (resbody ...) (resbody ...) nil))
-"begin; foo; rescue Exception; rescue; end"
- ~~~~~ begin                           ~~~ end
-             ~~~~~~~~~~~~~~~~~ expression (rescue.resbody/1)
-                               ~~~~~~~ expression (rescue.resbody/2)
-        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ expression (rescue)
-~~~
-##### With else
-Format:
-~~~
-(begin
-  (rescue (send nil :foo) (resbody ...) (resbody ...) (true)))
-"begin; foo; rescue Exception; rescue; else true end"
- ~~~~~ begin                           ~~~~ else (rescue)
-                                                 ~~~ end
-~~~
-#### Ensure statement
-Format:
-~~~
-(begin
-  (ensure (send nil :foo) (send nil :bar))
-"begin; foo; ensure; bar; end"
- ~~~~~ begin ~~~~~~ keyword (ensure)
-                          ~~~ end
-~~~
-#### Rescue with ensure
-Format:
-~~~
-(begin
-  (ensure
-    (rescue (send nil :foo) (resbody ...) (int 1))
-    (send nil :bar))
-"begin; foo; rescue; nil; else; 1; ensure; bar; end"
- ~~~~~ begin
-                          ~~~~ else (ensure.rescue)
-             ~~~~~~~~~~~~~~~~~~~~~ expression (rescue)
-                                   ~~~~~~ keyword (ensure)
-             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ expression (ensure)
-                                                ~~~ end
-~~~
-#### Retry
-Format:
-~~~
-(retry)
-"retry"
- ~~~~~ keyword
- ~~~~~ expression
-~~~
-### BEGIN and END
-Format:
-~~~
-(preexe (send nil :puts (str "foo")))
-"BEGIN { puts "foo" }"
- ~~~~~ keyword
-       ^ begin      ^ end
- ~~~~~~~~~~~~~~~~~~~~ expression
-(postexe (send nil :puts (str "bar")))
-"END { puts "bar" }"
- ~~~ keyword
-     ^ begin      ^ end
- ~~~~~~~~~~~~~~~~~~ expression
-~~~
-## Miscellanea
-### Flip-flops
-Format:
-~~~
-(iflipflop (lvar :a) (lvar :b))
-"if a..b; end"
-     ~~ operator
-    ~~~~ expression
-(eflipflop (lvar :a) (lvar :b))
-"if a...b; end"
-     ~~~ operator
-    ~~~~~ expression
-~~~
-### Implicit matches
-Format:
-~~~
-(match-current-line (regexp (str "a") (regopt)))
-"if /a/; end"
-    ~~~ expression
-~~~
-### Local variable injecting matches
-Format:
-~~~
-(match-with-lvasgn (regexp (str "(?<match>bar)") (regopt)) (lvar :baz))
-"/(?<match>bar)/ =~ baz"
-                 ~~ selector
- ~~~~~~~~~~~~~~~~~~~~~~ expression
-~~~
-## Special constants
-### File
-Format:
-~~~
-(__FILE__)
-"__FILE__"
- ~~~~~~~~ expression
-~~~
-### Line
-Format:
-~~~
-(__LINE__)
-"__LINE__"
- ~~~~~~~~ expression
-~~~
-### Encoding
-Format:
-~~~
-(__ENCODING__)
-"__ENCODING__"
- ~~~~~~~~~~~~ expression
-~~~
-## Pattern matching
-### Using `in` modifier
-Format:
-~~~
-(in-match
-  (int 1)
-  (match-var :a))
-"1 in a"
-   ~~ operator
- ~~~~~~ expression
-~~~
-### Case with pattern matching
-#### Without else
-Format:
-~~~
-(case-match
-  (str "str")
-  (in-pattern
-    (match-var :foo)
-    (lvar :bar)) nil)
-"case "str"; in foo; bar; end"
- ~~~~ keyword             ~~~ end
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ expression
-~~~
-#### With else
-Format:
-~~~
-(case-match,
-  (str "str")
-  (in-pattern
-    (match-var :foo)
-    (lvar :bar))
-  (lvar :baz))
-"case "str"; in foo; bar; else; baz; end"
- ~~~~ keyword             ~~~~ else  ~~~ end
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ expression
-~~~
-#### With empty else
-Empty `else` differs from the missing (or _implicit_) `else` for pattern matching, since
-the latter one raises a `NoMatchingPattern` exception. Thus, we need a way to distinguish this
-two cases in the resulting AST.
-Format:
-~~~
-(case-match,
-  (str "str")
-  (in-pattern
-    (match-var :foo)
-    (lvar :bar))
-  (empty-else))
-"case "str"; in foo; bar; else; end"
- ~~~~ keyword             ~~~~ else
-                                ~~~ end
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ expression
-~~~
-### In clause
-Format:
-~~~
-(in-pattern
-  (match-var :foo)
-  (lvar :bar))
-"in foo then bar"
- ~~ keyword
-        ~~~~ begin
- ~~~~~~~~~~~~~~~ expression
-~~~
-### If guard
-This guard runs after matching, so it's not an `if` modifier.
-Format:
-~~~
-(in-pattern
-  (match-var :foo)
-  (if-guard
-    (lvar :bar)) nil)
-"in foo if bar"
-        ~~ keyword
-        ~~~~~~ expression
-~~~
-### Unless guard
-This guard runs after matching, so it's not an `unless` modifier.
-Format:
-~~~
-(in-pattern
-  (match-var :foo)
-  (unless-guard
-    (lvar :bar)) nil)
-"in foo unless bar"
-        ~~~~~~ keyword
-        ~~~~~~~~~~ expression
-~~~
-### Match variable
-Format:
-~~~
-(match-var :foo)
-"in foo"
-    ~~~ name
-    ~~~ expression
-~~~
-### Match rest
-#### With name
-Format:
-~~~
-(match-rest
-  (match-var :foo))
-"in *foo"
-    ~ operator
-    ~~~~ expression
-~~~
-#### Without name
-Format:
-~~~
-(match-rest)
-"in *"
-    ~ operator
-    ~ expression
-~~~
-### Pin operator
-Format:
-~~~
-(pin
-  (lvar :foo))
-"in ^foo"
-    ~ selector
-    ~~~~ expression
-~~~
-### Match alternative
-Format:
-~~~
-(match-alt
-  (pin
-    (lvar :foo))
-  (int 1))
-"in ^foo | 1"
-         ~ operator
-    ~~~~~~~~ expression
-~~~
-### Match with alias
-Format:
-~~~
-(match-as
-  (int 1)
-  (match-var :foo))
-"in 1 => foo"
-      ~~ operator
-    ~~~~~~~~ expression
-~~~
-### Match using array pattern
-#### Explicit
-Format:
-~~~
-(array-pattern
-  (pin
-    (lvar :foo))
-  (match-var :bar))
-"in [^foo, bar]"
-    ~ begin   ~ end
-    ~~~~~~~~~~~ expression
-~~~
-#### Explicit with tail
-Adding a trailing comma in the end works as `, *`
-Format:
-~~~
-(array-pattern-with-tail
-  (pin
-    (lvar :foo))
-  (match-var :bar))
-"in [^foo, bar,]"
-    ~ begin    ~ end
-    ~~~~~~~~~~~~ expression
-~~~
-#### Implicit
-Format:
-~~~
-(array-pattern
-  (pin
-    (lvar :foo))
-  (match-var :bar))
-"in ^foo, bar"
-    ~~~~~~~~~ expression
-~~~
-#### Implicit with tail
-Format:
-Adding a trailing comma in the end works as `, *`,
-so a single item match with comma gets interpreted as an array.
-~~~
-(array-pattern-with-tail
-  (match-var :foo))
-"in foo,"
-    ~~~~ expression
-~~~
-### Matching using hash pattern
-#### Explicit
-Format:
-~~~
-(hash-pattern
-  (pair
-    (sym :a)
-    (int 10)))
-"in { a: 10 }"
-    ~ begin ~ end
-    ~~~~~~~~~ expression
-~~~
-#### Implicit
-Format:
-~~~
-(hash-pattern
-  (pair
-    (sym :a)
-    (int 10)))
-"in a: 10"
-    ~~~~~ expression
-~~~
-#### Assignment using hash pattern
-Format:
-~~~
-(hash-pattern
-  (match-var :a))
-"in a:"
-    ~ name (match-var)
-    ~~ expression (match-var)
-~~~
-#### Nil hash pattern
-Format:
-~~~
-(hash-pattern
-  (match-nil-pattern))
-"in **nil"
-    ~~~~~ expression (match-nil-pattern)
-      ~~~ name (match-nil-pattern)
-~~~
-### Matching using const pattern
-#### With array pattern
-Format:
-~~~
-(const-pattern
-  (const nil :X)
-  (array-pattern
-    (pin
-      (lvar :foo))
-    (match-var :bar)))
-"in X[^foo bar]"
-     ~ begin (const-pattern)
-               ~ end (const-pattern)
-    ~~~~~~~~~~~~ expression (const-pattern)
-    ~ name (const-pattern.const)
-    ~ expression (const-pattern.const)
-~~~
-#### With hash pattern
-Format:
-~~~
-(const-pattern
-  (const nil :X)
-  (hash-pattern
-    (match-var :foo)
-    (match-var :bar)))
-"in X[foo:, bar:]"
-     ~ begin (const-pattern)
-                ~ end (const-pattern)
-    ~~~~~~~~~~~~~ expression (const-pattern)
-    ~ name (const-pattern.const)
-    ~ expression (const-pattern.const)
-~~~
-#### With array pattern without elements
-Format:
-~~~
-(const-pattern
-  (const nil :X)
-  (array-pattern))
-"in X[]"
-     ~ begin (const-pattern)
-      ~ end (const-pattern)
-    ~~~ expression (const-pattern)
-    ~ name (const-pattern.const)
-    ~ expression (const-pattern.const)
-     ~~ expression (const-pattern.array_pattern)
-~~~