prism 0.26.0 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +45 -1
  3. data/Makefile +3 -2
  4. data/config.yml +305 -20
  5. data/docs/configuration.md +1 -0
  6. data/ext/prism/api_node.c +884 -879
  7. data/ext/prism/extconf.rb +23 -4
  8. data/ext/prism/extension.c +16 -9
  9. data/ext/prism/extension.h +1 -1
  10. data/include/prism/ast.h +298 -9
  11. data/include/prism/diagnostic.h +15 -5
  12. data/include/prism/options.h +2 -2
  13. data/include/prism/parser.h +10 -0
  14. data/include/prism/static_literals.h +8 -6
  15. data/include/prism/version.h +2 -2
  16. data/lib/prism/dot_visitor.rb +22 -6
  17. data/lib/prism/dsl.rb +8 -8
  18. data/lib/prism/ffi.rb +4 -4
  19. data/lib/prism/inspect_visitor.rb +2156 -0
  20. data/lib/prism/lex_compat.rb +18 -1
  21. data/lib/prism/mutation_compiler.rb +2 -2
  22. data/lib/prism/node.rb +2345 -1964
  23. data/lib/prism/node_ext.rb +34 -5
  24. data/lib/prism/parse_result/newlines.rb +0 -2
  25. data/lib/prism/parse_result.rb +137 -13
  26. data/lib/prism/pattern.rb +12 -6
  27. data/lib/prism/polyfill/byteindex.rb +13 -0
  28. data/lib/prism/polyfill/unpack1.rb +14 -0
  29. data/lib/prism/reflection.rb +21 -31
  30. data/lib/prism/serialize.rb +27 -17
  31. data/lib/prism/translation/parser/compiler.rb +34 -15
  32. data/lib/prism/translation/parser.rb +6 -6
  33. data/lib/prism/translation/ripper.rb +72 -68
  34. data/lib/prism/translation/ruby_parser.rb +69 -31
  35. data/lib/prism.rb +3 -2
  36. data/prism.gemspec +36 -38
  37. data/rbi/prism/compiler.rbi +3 -5
  38. data/rbi/prism/inspect_visitor.rbi +12 -0
  39. data/rbi/prism/node.rbi +359 -321
  40. data/rbi/prism/parse_result.rbi +85 -34
  41. data/rbi/prism/reflection.rbi +7 -13
  42. data/rbi/prism/translation/ripper.rbi +1 -11
  43. data/rbi/prism.rbi +9 -9
  44. data/sig/prism/dsl.rbs +3 -3
  45. data/sig/prism/inspect_visitor.rbs +22 -0
  46. data/sig/prism/node.rbs +68 -48
  47. data/sig/prism/parse_result.rbs +42 -10
  48. data/sig/prism/reflection.rbs +2 -8
  49. data/sig/prism/serialize.rbs +2 -3
  50. data/sig/prism.rbs +9 -9
  51. data/src/diagnostic.c +44 -24
  52. data/src/node.c +41 -16
  53. data/src/options.c +2 -2
  54. data/src/prettyprint.c +61 -18
  55. data/src/prism.c +623 -188
  56. data/src/serialize.c +5 -2
  57. data/src/static_literals.c +120 -34
  58. data/src/token_type.c +4 -4
  59. data/src/util/pm_integer.c +9 -2
  60. metadata +7 -9
  61. data/lib/prism/node_inspector.rb +0 -68
  62. data/lib/prism/polyfill/string.rb +0 -12
  63. data/rbi/prism/desugar_compiler.rbi +0 -5
  64. data/rbi/prism/mutation_compiler.rbi +0 -5
  65. data/rbi/prism/translation/parser/compiler.rbi +0 -13
  66. data/rbi/prism/translation/ripper/ripper_compiler.rbi +0 -5
  67. data/rbi/prism/translation/ruby_parser.rbi +0 -11
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: abad576ba53ce985475eb5d69638557386eef255c8fe625728780ce8ff66844e
4
- data.tar.gz: a3c5e24f5d1ee0fe04d282a3f40d643cd914a518985a9cadebbb53200e4d3003
3
+ metadata.gz: 7715842445523172c9593bae81ff5c1a889c6735b59f1c5a879fe63bbeacd724
4
+ data.tar.gz: 755dd34f1e20f374aa2910482a8fac4e709e332d5313a1c80bcc2b3fc9ffbad4
5
5
  SHA512:
6
- metadata.gz: d3255b2de64f3154500885ae2bd091389d6ac87c9b88cb8ff83b7d58026066c4e007cb7c486dcc8e8146132aad63a1c58ddd8ad598441d26bec7ad062409f6a9
7
- data.tar.gz: 3d7563663f013a4dcc633b5e19d0a4605cae18bd0a0f99cc02c142198b25126f915185eef4080625c9a5867093a5bc5717db96ef8a8da6cdc69e849f65fbb7fd
6
+ metadata.gz: 37206e932b34156ad6b1679ea379e8665d987bf9673d37a1e5f74c1abb1a442adbdc0d2045d75624e60507794bd8dd56c5b7bbc8864d7ab9cec1f9a6c1c44b05
7
+ data.tar.gz: 15fc69115a30581010fb65d540f8d2a0c0cd1f76d59754d9b3c1d2f4c2f4354f2f9cbb5087a7989df6b85ff5285248875d6ed40b05d2fca89753f1235948bb0d
data/CHANGELOG.md CHANGED
@@ -6,6 +6,48 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.28.0] - 2024-05-03
10
+
11
+ ### Added
12
+
13
+ - Nested hashes will now warn for duplicated keys, as in: `{ foo: 1, **{ foo: 2 } }`.
14
+ - `Prism::ReturnNode` now has a flag on it to indicate if it is redundant.
15
+ - `Prism::Location#slice_lines` and `Prism::Node#slice_lines` are now provided to slice the source code of a node including the content before the node on the same line that it starts on and the content after the node on the same line that it ends on.
16
+ - Symbols with invalid byte sequences now give errors.
17
+ - You can now pass `"3.3.1"` to the `version:` parameter on all `Prism.*` APIs.
18
+ - `Prism::Source#lines`, `Prism::Location#source_lines`, `Prism::Node#source_lines`, and `Prism::Node#script_lines` are now provided, which will all return the source code of the source as an array of strings.
19
+ - `Prism::ASCIISource` is now provided, which is a subclass of `Prism::Source` but specialized to increase performance when the source is entirely ASCII.
20
+ - Prism now provides errors when parsing Ruby 3.4+ syntax for index expressions with keywords or blocks.
21
+ - Prism now provides an error when `**nil` is used after other keyword parameters.
22
+ - Prism now provides errors when safe navigation is used in call target expressions, e.g., `foo&.bar, = 1`.
23
+ - `Prism::Node#tunnel` is now provided, which returns an array of nodes starting at the current node that contain a given line and column.
24
+
25
+ ### Changed
26
+
27
+ - All translation layers now assume an eval context, which means they will not return errors for invalid jumps like `yield`.
28
+ - `Prism::Node#inspect` now uses a queue instead of recursion to avoid stack overflows.
29
+ - Prism now more closely mirrors CRuby interpolation semantics, which means you could potentially have a static literal string that directly interpolates another static literal string.
30
+ - The shipped RBI sorbet types no longer use generics.
31
+ - `Prism::ConstantPathNode#child` and `Prism::ConstantTargetNode#child` are now deprecated, replaced by two new fields on these nodes: `name` and `name_loc`.
32
+
33
+ ## [0.27.0] - 2024-04-23
34
+
35
+ ### Added
36
+
37
+ - Implemented `===` for each of the nodes, which will check if equality but ignore the specific ranges of locations.
38
+
39
+ ### Changed
40
+
41
+ - Fix translation of `ItParametersNode` for parser translation.
42
+ - Fix translation of `dstr` for ruby_parser translation.
43
+ - Do not allow omitted hash values whose keys end with `!` or `?`.
44
+ - Split up `Prism::ParseResult` into `Prism::Result` with subclasses `Prism::ParseResult`, `Prism::LexResult`, `Prism::ParseLexResult`, and `Prism::LexCompat::Result`.
45
+ - Change reflection classes to have only a single `IntegerField` class and rename `DoubleField` to `FloatField`.
46
+ - Fall back to default `AR` and `CC` in `Makefile`.
47
+ - Use GC-able symbols for the syntax tree to avoid adding to the global symbol table.
48
+ - Fix a bug with karatsuba_multiply that would result in a stack overflow.
49
+ - Fix parser translation when looking for tokens with `srange_find`.
50
+
9
51
  ## [0.26.0] - 2024-04-18
10
52
 
11
53
  ### Added
@@ -458,7 +500,9 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
458
500
 
459
501
  - 🎉 Initial release! 🎉
460
502
 
461
- [unreleased]: https://github.com/ruby/prism/compare/v0.26.0...HEAD
503
+ [unreleased]: https://github.com/ruby/prism/compare/v0.28.0...HEAD
504
+ [0.28.0]: https://github.com/ruby/prism/compare/v0.27.0...v0.28.0
505
+ [0.27.0]: https://github.com/ruby/prism/compare/v0.26.0...v0.27.0
462
506
  [0.26.0]: https://github.com/ruby/prism/compare/v0.25.0...v0.26.0
463
507
  [0.25.0]: https://github.com/ruby/prism/compare/v0.24.0...v0.25.0
464
508
  [0.24.0]: https://github.com/ruby/prism/compare/v0.23.0...v0.24.0
data/Makefile CHANGED
@@ -13,6 +13,7 @@ SOEXT ?= $(shell ruby -e 'puts RbConfig::CONFIG["SOEXT"]')
13
13
  CPPFLAGS := -Iinclude $(CPPFLAGS)
14
14
  CFLAGS := -g -O2 -std=c99 -Wall -Werror -Wextra -Wpedantic -Wundef -Wconversion -Wno-missing-braces -fPIC -fvisibility=hidden $(CFLAGS)
15
15
  CC ?= cc
16
+ AR ?= ar
16
17
  WASI_SDK_PATH := /opt/wasi-sdk
17
18
 
18
19
  MAKEDIRS ?= mkdir -p
@@ -31,11 +32,11 @@ wasm: javascript/src/prism.wasm
31
32
  java-wasm: java-wasm/src/test/resources/prism.wasm
32
33
 
33
34
  build/libprism.$(SOEXT): $(SHARED_OBJECTS)
34
- $(ECHO) "linking $@"
35
+ $(ECHO) "linking $@ with $(CC)"
35
36
  $(Q) $(CC) $(DEBUG_FLAGS) $(CFLAGS) -shared -o $@ $(SHARED_OBJECTS)
36
37
 
37
38
  build/libprism.a: $(STATIC_OBJECTS)
38
- $(ECHO) "building $@"
39
+ $(ECHO) "building $@ with $(AR)"
39
40
  $(Q) $(AR) $(ARFLAGS) $@ $(STATIC_OBJECTS) $(Q1:0=>/dev/null)
40
41
 
41
42
  javascript/src/prism.wasm: Makefile $(SOURCES) $(HEADERS)
data/config.yml CHANGED
@@ -123,17 +123,20 @@ errors:
123
123
  - HASH_ROCKET
124
124
  - HASH_TERM
125
125
  - HASH_VALUE
126
+ - HEREDOC_IDENTIFIER
126
127
  - HEREDOC_TERM
127
128
  - INCOMPLETE_QUESTION_MARK
128
129
  - INCOMPLETE_VARIABLE_CLASS
129
- - INCOMPLETE_VARIABLE_CLASS_3_3_0
130
+ - INCOMPLETE_VARIABLE_CLASS_3_3
130
131
  - INCOMPLETE_VARIABLE_INSTANCE
131
- - INCOMPLETE_VARIABLE_INSTANCE_3_3_0
132
+ - INCOMPLETE_VARIABLE_INSTANCE_3_3
132
133
  - INSTANCE_VARIABLE_BARE
133
134
  - INVALID_BLOCK_EXIT
134
135
  - INVALID_CHARACTER
135
136
  - INVALID_ENCODING_MAGIC_COMMENT
136
137
  - INVALID_FLOAT_EXPONENT
138
+ - INVALID_LOCAL_VARIABLE_READ
139
+ - INVALID_LOCAL_VARIABLE_WRITE
137
140
  - INVALID_MULTIBYTE_CHAR
138
141
  - INVALID_MULTIBYTE_CHARACTER
139
142
  - INVALID_MULTIBYTE_ESCAPE
@@ -141,14 +144,16 @@ errors:
141
144
  - INVALID_NUMBER_DECIMAL
142
145
  - INVALID_NUMBER_HEXADECIMAL
143
146
  - INVALID_NUMBER_OCTAL
144
- - INVALID_NUMBER_UNDERSCORE
147
+ - INVALID_NUMBER_UNDERSCORE_INNER
148
+ - INVALID_NUMBER_UNDERSCORE_TRAILING
145
149
  - INVALID_PERCENT
146
150
  - INVALID_PRINTABLE_CHARACTER
147
151
  - INVALID_RETRY_AFTER_ELSE
148
152
  - INVALID_RETRY_AFTER_ENSURE
149
153
  - INVALID_RETRY_WITHOUT_RESCUE
154
+ - INVALID_SYMBOL
150
155
  - INVALID_VARIABLE_GLOBAL
151
- - INVALID_VARIABLE_GLOBAL_3_3_0
156
+ - INVALID_VARIABLE_GLOBAL_3_3
152
157
  - INVALID_YIELD
153
158
  - IT_NOT_ALLOWED_NUMBERED
154
159
  - IT_NOT_ALLOWED_ORDINARY
@@ -192,6 +197,7 @@ errors:
192
197
  - PARAMETER_STAR
193
198
  - PARAMETER_UNEXPECTED_FWD
194
199
  - PARAMETER_WILD_LOOSE_COMMA
200
+ - PARAMETER_UNEXPECTED_NO_KW
195
201
  - PATTERN_CAPTURE_DUPLICATE
196
202
  - PATTERN_EXPRESSION_AFTER_BRACKET
197
203
  - PATTERN_EXPRESSION_AFTER_COMMA
@@ -206,6 +212,7 @@ errors:
206
212
  - PATTERN_HASH_KEY
207
213
  - PATTERN_HASH_KEY_DUPLICATE
208
214
  - PATTERN_HASH_KEY_LABEL
215
+ - PATTERN_HASH_KEY_LOCALS
209
216
  - PATTERN_IDENT_AFTER_HROCKET
210
217
  - PATTERN_LABEL_AFTER_COMMA
211
218
  - PATTERN_REST
@@ -244,6 +251,9 @@ errors:
244
251
  - UNARY_RECEIVER
245
252
  - UNDEF_ARGUMENT
246
253
  - UNEXPECTED_BLOCK_ARGUMENT
254
+ - UNEXPECTED_INDEX_BLOCK
255
+ - UNEXPECTED_INDEX_KEYWORDS
256
+ - UNEXPECTED_SAFE_NAVIGATION
247
257
  - UNEXPECTED_TOKEN_CLOSE_CONTEXT
248
258
  - UNEXPECTED_TOKEN_IGNORE
249
259
  - UNTIL_TERM
@@ -263,7 +273,7 @@ warnings:
263
273
  - COMPARISON_AFTER_COMPARISON
264
274
  - DOT_DOT_DOT_EOL
265
275
  - EQUAL_IN_CONDITIONAL
266
- - EQUAL_IN_CONDITIONAL_3_3_0
276
+ - EQUAL_IN_CONDITIONAL_3_3
267
277
  - END_IN_METHOD
268
278
  - DUPLICATED_HASH_KEY
269
279
  - DUPLICATED_WHEN_CLAUSE
@@ -614,6 +624,8 @@ tokens:
614
624
  flags:
615
625
  - name: ArgumentsNodeFlags
616
626
  values:
627
+ - name: CONTAINS_KEYWORDS
628
+ comment: "if arguments contain keywords"
617
629
  - name: CONTAINS_KEYWORD_SPLAT
618
630
  comment: "if arguments contain keyword splat"
619
631
  comment: Flags for arguments nodes.
@@ -703,6 +715,11 @@ flags:
703
715
  - name: FORCED_US_ASCII_ENCODING
704
716
  comment: "internal bytes forced the encoding to US-ASCII"
705
717
  comment: Flags for regular expression and match last line nodes.
718
+ - name: ReturnNodeFlags
719
+ values:
720
+ - name: REDUNDANT
721
+ comment: "a return statement that is redundant because it is the last statement in a method"
722
+ comment: Flags for return nodes.
706
723
  - name: ShareableConstantNodeFlags
707
724
  values:
708
725
  - name: LITERAL
@@ -737,10 +754,25 @@ nodes:
737
754
  fields:
738
755
  - name: new_name
739
756
  type: node
757
+ comment: |
758
+ Represents the new name of the global variable that can be used after aliasing. This can be either a global variable, a back reference, or a numbered reference.
759
+
760
+ alias $foo $bar
761
+ ^^^^
740
762
  - name: old_name
741
763
  type: node
764
+ comment: |
765
+ Represents the old name of the global variable that could be used before aliasing. This can be either a global variable, a back reference, or a numbered reference.
766
+
767
+ alias $foo $bar
768
+ ^^^^
742
769
  - name: keyword_loc
743
770
  type: location
771
+ comment: |
772
+ The location of the `alias` keyword.
773
+
774
+ alias $foo $bar
775
+ ^^^^^
744
776
  comment: |
745
777
  Represents the use of the `alias` keyword to alias a global variable.
746
778
 
@@ -825,10 +857,25 @@ nodes:
825
857
  kind: ArrayNodeFlags
826
858
  - name: elements
827
859
  type: node[]
860
+ comment: Represent the list of zero or more [non-void expressions](https://github.com/ruby/prism/blob/main/docs/parsing_rules.md#non-void-expression) within the array.
828
861
  - name: opening_loc
829
862
  type: location?
863
+ comment: |
864
+ Represents the optional source location for the opening token.
865
+
866
+ [1,2,3] # "["
867
+ %w[foo bar baz] # "%w["
868
+ %I(apple orange banana) # "%I("
869
+ foo = 1, 2, 3 # nil
830
870
  - name: closing_loc
831
871
  type: location?
872
+ comment: |
873
+ Represents the optional source location for the closing token.
874
+
875
+ [1,2,3] # "]"
876
+ %w[foo bar baz] # "]"
877
+ %I(apple orange banana) # ")"
878
+ foo = 1, 2, 3 # nil
832
879
  comment: |
833
880
  Represents an array literal. This can be a regular array using brackets or a special array using % like %w or %i.
834
881
 
@@ -1047,8 +1094,18 @@ nodes:
1047
1094
  - name: arguments
1048
1095
  type: node?
1049
1096
  kind: ArgumentsNode
1097
+ comment: |
1098
+ The arguments to the break statement, if present. These can be any [non-void expressions](https://github.com/ruby/prism/blob/main/docs/parsing_rules.md#non-void-expression).
1099
+
1100
+ break foo
1101
+ ^^^
1050
1102
  - name: keyword_loc
1051
1103
  type: location
1104
+ comment: |
1105
+ The location of the `break` keyword.
1106
+
1107
+ break foo
1108
+ ^^^^^
1052
1109
  comment: |
1053
1110
  Represents the use of the `break` keyword.
1054
1111
 
@@ -1374,8 +1431,7 @@ nodes:
1374
1431
  - name: value
1375
1432
  type: node
1376
1433
  comment: |
1377
- The value to assign to the class variable. Can be any node that
1378
- represents a non-void expression.
1434
+ The value to write to the class variable. This can be any [non-void expression](https://github.com/ruby/prism/blob/main/docs/parsing_rules.md#non-void-expression).
1379
1435
 
1380
1436
  @@foo = :bar
1381
1437
  ^^^^
@@ -1459,13 +1515,40 @@ nodes:
1459
1515
  fields:
1460
1516
  - name: parent
1461
1517
  type: node?
1462
- - name: child
1463
- type: node
1464
- kind:
1465
- - ConstantReadNode
1466
- - MissingNode
1518
+ comment: |
1519
+ The left-hand node of the path, if present. It can be `nil` or any [non-void expression](https://github.com/ruby/prism/blob/main/docs/parsing_rules.md#non-void-expression). It will be `nil` when the constant lookup is at the root of the module tree.
1520
+
1521
+ Foo::Bar
1522
+ ^^^
1523
+
1524
+ self::Test
1525
+ ^^^^
1526
+
1527
+ a.b::C
1528
+ ^^^
1529
+ - name: name
1530
+ type: constant?
1531
+ comment: The name of the constant being accessed. This could be `nil` in the event of a syntax error.
1467
1532
  - name: delimiter_loc
1468
1533
  type: location
1534
+ comment: |
1535
+ The location of the `::` delimiter.
1536
+
1537
+ ::Foo
1538
+ ^^
1539
+
1540
+ One::Two
1541
+ ^^
1542
+ - name: name_loc
1543
+ type: location
1544
+ comment: |
1545
+ The location of the name of the constant.
1546
+
1547
+ ::Foo
1548
+ ^^^
1549
+
1550
+ One::Two
1551
+ ^^^
1469
1552
  comment: |
1470
1553
  Represents accessing a constant through a path of `::` operators.
1471
1554
 
@@ -1505,13 +1588,12 @@ nodes:
1505
1588
  fields:
1506
1589
  - name: parent
1507
1590
  type: node?
1508
- - name: child
1509
- type: node
1510
- kind:
1511
- - ConstantReadNode
1512
- - MissingNode
1591
+ - name: name
1592
+ type: constant?
1513
1593
  - name: delimiter_loc
1514
1594
  type: location
1595
+ - name: name_loc
1596
+ type: location
1515
1597
  comment: |
1516
1598
  Represents writing to a constant path in a context that doesn't have an explicit value.
1517
1599
 
@@ -1522,10 +1604,28 @@ nodes:
1522
1604
  - name: target
1523
1605
  type: node
1524
1606
  kind: ConstantPathNode
1607
+ comment: |
1608
+ A node representing the constant path being written to.
1609
+
1610
+ Foo::Bar = 1
1611
+ ^^^^^^^^
1612
+
1613
+ ::Foo = :abc
1614
+ ^^^^^
1525
1615
  - name: operator_loc
1526
1616
  type: location
1617
+ comment: |
1618
+ The location of the `=` operator.
1619
+
1620
+ ::ABC = 123
1621
+ ^
1527
1622
  - name: value
1528
1623
  type: node
1624
+ comment: |
1625
+ The value to write to the constant path. It can be any [non-void expression](https://github.com/ruby/prism/blob/main/docs/parsing_rules.md#non-void-expression).
1626
+
1627
+ FOO::BAR = :abc
1628
+ ^^^^
1529
1629
  comment: |
1530
1630
  Represents writing to a constant path.
1531
1631
 
@@ -1565,12 +1665,36 @@ nodes:
1565
1665
  fields:
1566
1666
  - name: name
1567
1667
  type: constant
1668
+ comment: |
1669
+ The name of the [constant](https://github.com/ruby/prism/blob/main/docs/parsing_rules.md#constants).
1670
+
1671
+ Foo = :bar # name `:Foo`
1672
+
1673
+ XYZ = 1 # name `:XYZ`
1568
1674
  - name: name_loc
1569
1675
  type: location
1676
+ comment: |
1677
+ The location of the constant name.
1678
+
1679
+ FOO = 1
1680
+ ^^^
1570
1681
  - name: value
1571
1682
  type: node
1683
+ comment: |
1684
+ The value to write to the constant. It can be any [non-void expression](https://github.com/ruby/prism/blob/main/docs/parsing_rules.md#non-void-expression).
1685
+
1686
+ FOO = :bar
1687
+ ^^^^
1688
+
1689
+ MyClass = Class.new
1690
+ ^^^^^^^^^
1572
1691
  - name: operator_loc
1573
1692
  type: location
1693
+ comment: |
1694
+ The location of the `=` operator.
1695
+
1696
+ FOO = :bar
1697
+ ^
1574
1698
  comment: |
1575
1699
  Represents writing to a constant.
1576
1700
 
@@ -1860,12 +1984,36 @@ nodes:
1860
1984
  fields:
1861
1985
  - name: name
1862
1986
  type: constant
1987
+ comment: |
1988
+ The name of the global variable, which is a `$` followed by an [identifier](https://github.com/ruby/prism/blob/main/docs/parsing_rules.md#identifier). Alternatively, it can be one of the special global variables designated by a symbol.
1989
+
1990
+ $foo = :bar # name `:$foo`
1991
+
1992
+ $_Test = 123 # name `:$_Test`
1863
1993
  - name: name_loc
1864
1994
  type: location
1995
+ comment: |
1996
+ The location of the global variable's name.
1997
+
1998
+ $foo = :bar
1999
+ ^^^^
1865
2000
  - name: value
1866
2001
  type: node
2002
+ comment: |
2003
+ The value to write to the global variable. It can be any [non-void expression](https://github.com/ruby/prism/blob/main/docs/parsing_rules.md#non-void-expression).
2004
+
2005
+ $foo = :bar
2006
+ ^^^^
2007
+
2008
+ $-xyz = 123
2009
+ ^^^
1867
2010
  - name: operator_loc
1868
2011
  type: location
2012
+ comment: |
2013
+ The location of the `=` operator.
2014
+
2015
+ $foo = :bar
2016
+ ^
1869
2017
  comment: |
1870
2018
  Represents writing to a global variable.
1871
2019
 
@@ -1933,26 +2081,87 @@ nodes:
1933
2081
  fields:
1934
2082
  - name: if_keyword_loc
1935
2083
  type: location?
2084
+ comment: |
2085
+ The location of the `if` keyword if present.
2086
+
2087
+ bar if foo
2088
+ ^^
2089
+
2090
+ The `if_keyword_loc` field will be `nil` when the `IfNode` represents a ternary expression.
1936
2091
  - name: predicate
1937
2092
  type: node
2093
+ comment: |
2094
+ The node for the condition the `IfNode` is testing.
2095
+
2096
+ if foo
2097
+ ^^^
2098
+ bar
2099
+ end
2100
+
2101
+ bar if foo
2102
+ ^^^
2103
+
2104
+ foo ? bar : baz
2105
+ ^^^
1938
2106
  - name: then_keyword_loc
1939
2107
  type: location?
2108
+ comment: |
2109
+ The location of the `then` keyword (if present) or the `?` in a ternary expression, `nil` otherwise.
2110
+
2111
+ if foo then bar end
2112
+ ^^^^
2113
+
2114
+ a ? b : c
2115
+ ^
1940
2116
  - name: statements
1941
2117
  type: node?
1942
2118
  kind: StatementsNode
2119
+ comment: |
2120
+ Represents the body of statements that will be executed when the predicate is evaluated as truthy. Will be `nil` when no body is provided.
2121
+
2122
+ if foo
2123
+ bar
2124
+ ^^^
2125
+ baz
2126
+ ^^^
2127
+ end
1943
2128
  - name: consequent
1944
2129
  type: node?
2130
+ comment: |
2131
+ Represents an `ElseNode` or an `IfNode` when there is an `else` or an `elsif` in the `if` statement.
2132
+
2133
+ if foo
2134
+ bar
2135
+ elsif baz
2136
+ ^^^^^^^^^
2137
+ qux
2138
+ ^^^
2139
+ end
2140
+ ^^^
2141
+
2142
+ if foo then bar else baz end
2143
+ ^^^^^^^^^^^^
1945
2144
  - name: end_keyword_loc
1946
2145
  type: location?
2146
+ comment: |
2147
+ The location of the `end` keyword if present, `nil` otherwise.
2148
+
2149
+ if foo
2150
+ bar
2151
+ end
2152
+ ^^^
1947
2153
  newline: predicate
1948
2154
  comment: |
1949
- Represents the use of the `if` keyword, either in the block form or the modifier form.
2155
+ Represents the use of the `if` keyword, either in the block form or the modifier form, or a ternary expression.
1950
2156
 
1951
2157
  bar if foo
1952
2158
  ^^^^^^^^^^
1953
2159
 
1954
2160
  if foo then bar end
1955
2161
  ^^^^^^^^^^^^^^^^^^^
2162
+
2163
+ foo ? bar : baz
2164
+ ^^^^^^^^^^^^^^^
1956
2165
  - name: ImaginaryNode
1957
2166
  fields:
1958
2167
  - name: numeric
@@ -2215,8 +2424,7 @@ nodes:
2215
2424
  - name: value
2216
2425
  type: node
2217
2426
  comment: |
2218
- The value to assign to the instance variable. Can be any node that
2219
- represents a non-void expression.
2427
+ The value to write to the instance variable. It can be any [non-void expression](https://github.com/ruby/prism/blob/main/docs/parsing_rules.md#non-void-expression).
2220
2428
 
2221
2429
  @foo = :bar
2222
2430
  ^^^^
@@ -2507,14 +2715,50 @@ nodes:
2507
2715
  fields:
2508
2716
  - name: name
2509
2717
  type: constant
2718
+ comment: |
2719
+ The name of the local variable, which is an [identifier](https://github.com/ruby/prism/blob/main/docs/parsing_rules.md#identifiers).
2720
+
2721
+ foo = :bar # name `:foo`
2722
+
2723
+ abc = 123 # name `:abc`
2510
2724
  - name: depth
2511
2725
  type: uint32
2726
+ comment: |
2727
+ The number of semantic scopes we have to traverse to find the declaration of this variable.
2728
+
2729
+ foo = 1 # depth 0
2730
+
2731
+ tap { foo = 1 } # depth 1
2732
+
2733
+ The specific rules for calculating the depth may differ from individual Ruby implementations, as they are not specified by the language. For more information, see [the Prism documentation](https://github.com/ruby/prism/blob/main/docs/local_variable_depth.md).
2512
2734
  - name: name_loc
2513
2735
  type: location
2736
+ comment: |
2737
+ The location of the variable name.
2738
+
2739
+ foo = :bar
2740
+ ^^^
2514
2741
  - name: value
2515
2742
  type: node
2743
+ comment: |
2744
+ The value to write to the local variable. It can be any [non-void expression](https://github.com/ruby/prism/blob/main/docs/parsing_rules.md#non-void-expression).
2745
+
2746
+ foo = :bar
2747
+ ^^^^
2748
+
2749
+ abc = 1234
2750
+ ^^^^
2751
+
2752
+ Note that since the name of a local variable is known before the value is parsed, it is valid for a local variable to appear within the value of its own write.
2753
+
2754
+ foo = foo
2516
2755
  - name: operator_loc
2517
2756
  type: location
2757
+ comment: |
2758
+ The location of the `=` operator.
2759
+
2760
+ x = :y
2761
+ ^
2518
2762
  comment: |
2519
2763
  Represents writing to a local variable.
2520
2764
 
@@ -3095,6 +3339,9 @@ nodes:
3095
3339
  ^^^^^
3096
3340
  - name: ReturnNode
3097
3341
  fields:
3342
+ - name: flags
3343
+ type: flags
3344
+ kind: ReturnNodeFlags
3098
3345
  - name: keyword_loc
3099
3346
  type: location
3100
3347
  - name: arguments
@@ -3166,6 +3413,7 @@ nodes:
3166
3413
  kind: StringFlags
3167
3414
  - name: filepath
3168
3415
  type: string
3416
+ comment: Represents the file path being parsed. This corresponds directly to the `filepath` option given to the various `Prism::parse*` APIs.
3169
3417
  comment: |
3170
3418
  Represents the use of the `__FILE__` keyword.
3171
3419
 
@@ -3287,18 +3535,55 @@ nodes:
3287
3535
  fields:
3288
3536
  - name: keyword_loc
3289
3537
  type: location
3538
+ comment: |
3539
+ The location of the `unless` keyword.
3540
+
3541
+ unless cond then bar end
3542
+ ^^^^^^
3543
+
3544
+ bar unless cond
3545
+ ^^^^^^
3290
3546
  - name: predicate
3291
3547
  type: node
3548
+ comment: |
3549
+ The condition to be evaluated for the unless expression. It can be any [non-void expression](https://github.com/ruby/prism/blob/main/docs/parsing_rules.md#non-void-expression).
3550
+
3551
+ unless cond then bar end
3552
+ ^^^^
3553
+
3554
+ bar unless cond
3555
+ ^^^^
3292
3556
  - name: then_keyword_loc
3293
3557
  type: location?
3558
+ comment:
3559
+ The location of the `then` keyword, if present.
3560
+
3561
+ unless cond then bar end
3562
+ ^^^^
3294
3563
  - name: statements
3295
3564
  type: node?
3296
3565
  kind: StatementsNode
3566
+ comment: |
3567
+ The body of statements that will executed if the unless condition is
3568
+ falsey. Will be `nil` if no body is provided.
3569
+
3570
+ unless cond then bar end
3571
+ ^^^
3297
3572
  - name: consequent
3298
3573
  type: node?
3299
3574
  kind: ElseNode
3575
+ comment: |
3576
+ The else clause of the unless expression, if present.
3577
+
3578
+ unless cond then bar else baz end
3579
+ ^^^^^^^^
3300
3580
  - name: end_keyword_loc
3301
3581
  type: location?
3582
+ comment: |
3583
+ The location of the `end` keyword, if present.
3584
+
3585
+ unless cond then bar end
3586
+ ^^^
3302
3587
  newline: predicate
3303
3588
  comment: |
3304
3589
  Represents the use of the `unless` keyword, either in the block form or the modifier form.
@@ -14,6 +14,7 @@ A lot of code in prism's repository is templated from a single configuration fil
14
14
  * `lib/prism/dispatcher.rb` - for defining the dispatch visitors for the nodes in Ruby
15
15
  * `lib/prism/dot_visitor.rb` - for defining the dot visitor for the nodes in Ruby
16
16
  * `lib/prism/dsl.rb` - for defining the DSL for the nodes in Ruby
17
+ * `lib/prism/inspect_visitor.rb` - for defining the `#inspect` methods on nodes in Ruby
17
18
  * `lib/prism/mutation_compiler.rb` - for defining the mutation compiler for the nodes in Ruby
18
19
  * `lib/prism/node.rb` - for defining the nodes in Ruby
19
20
  * `lib/prism/reflection.rb` - for defining the reflection API in Ruby