prism 1.4.0 → 1.6.0

data/include/prism/ast.h

@@ -1,3 +1,5 @@
+/* :markup: markdown */
+
 /*----------------------------------------------------------------------------*/
 /* This file is generated by the templates/template.rb script and should not  */
 /* be modified manually. See                                                  */
@@ -10,6 +12,8 @@
  * @file ast.h
  *
  * The abstract syntax tree.
+ *
+ * --
  */
 #ifndef PRISM_AST_H
 #define PRISM_AST_H
@@ -30,11 +34,50 @@ typedef enum pm_token_type {
     /** final token in the file */
     PM_TOKEN_EOF = 1,
 
-    /** a token that was expected but not found */
-    PM_TOKEN_MISSING,
+    /** } */
+    PM_TOKEN_BRACE_RIGHT,
 
-    /** a token that was not present but it is okay */
-    PM_TOKEN_NOT_PROVIDED,
+    /** , */
+    PM_TOKEN_COMMA,
+
+    /** } */
+    PM_TOKEN_EMBEXPR_END,
+
+    /** do */
+    PM_TOKEN_KEYWORD_DO,
+
+    /** else */
+    PM_TOKEN_KEYWORD_ELSE,
+
+    /** elsif */
+    PM_TOKEN_KEYWORD_ELSIF,
+
+    /** end */
+    PM_TOKEN_KEYWORD_END,
+
+    /** ensure */
+    PM_TOKEN_KEYWORD_ENSURE,
+
+    /** in */
+    PM_TOKEN_KEYWORD_IN,
+
+    /** rescue */
+    PM_TOKEN_KEYWORD_RESCUE,
+
+    /** then */
+    PM_TOKEN_KEYWORD_THEN,
+
+    /** when */
+    PM_TOKEN_KEYWORD_WHEN,
+
+    /** a newline character outside of other tokens */
+    PM_TOKEN_NEWLINE,
+
+    /** ) */
+    PM_TOKEN_PARENTHESIS_RIGHT,
+
+    /** ; */
+    PM_TOKEN_SEMICOLON,
 
     /** & */
     PM_TOKEN_AMPERSAND,
@@ -69,9 +112,6 @@ typedef enum pm_token_type {
     /** { */
     PM_TOKEN_BRACE_LEFT,
 
-    /** } */
-    PM_TOKEN_BRACE_RIGHT,
-
     /** [ */
     PM_TOKEN_BRACKET_LEFT,
 
@@ -105,9 +145,6 @@ typedef enum pm_token_type {
     /** :: */
     PM_TOKEN_COLON_COLON,
 
-    /** , */
-    PM_TOKEN_COMMA,
-
     /** a comment */
     PM_TOKEN_COMMENT,
 
@@ -135,9 +172,6 @@ typedef enum pm_token_type {
     /** #{ */
     PM_TOKEN_EMBEXPR_BEGIN,
 
-    /** } */
-    PM_TOKEN_EMBEXPR_END,
-
     /** # */
     PM_TOKEN_EMBVAR,
 
@@ -237,27 +271,12 @@ typedef enum pm_token_type {
     /** defined? */
     PM_TOKEN_KEYWORD_DEFINED,
 
-    /** do */
-    PM_TOKEN_KEYWORD_DO,
-
     /** do keyword for a predicate in a while, until, or for loop */
     PM_TOKEN_KEYWORD_DO_LOOP,
 
-    /** else */
-    PM_TOKEN_KEYWORD_ELSE,
-
-    /** elsif */
-    PM_TOKEN_KEYWORD_ELSIF,
-
-    /** end */
-    PM_TOKEN_KEYWORD_END,
-
     /** END */
     PM_TOKEN_KEYWORD_END_UPCASE,
 
-    /** ensure */
-    PM_TOKEN_KEYWORD_ENSURE,
-
     /** false */
     PM_TOKEN_KEYWORD_FALSE,
 
@@ -270,9 +289,6 @@ typedef enum pm_token_type {
     /** if in the modifier form */
     PM_TOKEN_KEYWORD_IF_MODIFIER,
 
-    /** in */
-    PM_TOKEN_KEYWORD_IN,
-
     /** module */
     PM_TOKEN_KEYWORD_MODULE,
 
@@ -291,9 +307,6 @@ typedef enum pm_token_type {
     /** redo */
     PM_TOKEN_KEYWORD_REDO,
 
-    /** rescue */
-    PM_TOKEN_KEYWORD_RESCUE,
-
     /** rescue in the modifier form */
     PM_TOKEN_KEYWORD_RESCUE_MODIFIER,
 
@@ -309,9 +322,6 @@ typedef enum pm_token_type {
     /** super */
     PM_TOKEN_KEYWORD_SUPER,
 
-    /** then */
-    PM_TOKEN_KEYWORD_THEN,
-
     /** true */
     PM_TOKEN_KEYWORD_TRUE,
 
@@ -330,9 +340,6 @@ typedef enum pm_token_type {
     /** until in the modifier form */
     PM_TOKEN_KEYWORD_UNTIL_MODIFIER,
 
-    /** when */
-    PM_TOKEN_KEYWORD_WHEN,
-
     /** while */
     PM_TOKEN_KEYWORD_WHILE,
 
@@ -387,9 +394,6 @@ typedef enum pm_token_type {
     /** -> */
     PM_TOKEN_MINUS_GREATER,
 
-    /** a newline character outside of other tokens */
-    PM_TOKEN_NEWLINE,
-
     /** a numbered reference to a capture group in the previous regular expression match */
     PM_TOKEN_NUMBERED_REFERENCE,
 
@@ -399,9 +403,6 @@ typedef enum pm_token_type {
     /** ( for a parentheses node */
     PM_TOKEN_PARENTHESIS_LEFT_PARENTHESES,
 
-    /** ) */
-    PM_TOKEN_PARENTHESIS_RIGHT,
-
     /** % */
     PM_TOKEN_PERCENT,
 
@@ -450,9 +451,6 @@ typedef enum pm_token_type {
     /** the end of a regular expression */
     PM_TOKEN_REGEXP_END,
 
-    /** ; */
-    PM_TOKEN_SEMICOLON,
-
     /** / */
     PM_TOKEN_SLASH,
 
@@ -519,6 +517,12 @@ typedef enum pm_token_type {
     /** marker for the point in the file at which the parser should stop */
     PM_TOKEN___END__,
 
+    /** a token that was expected but not found */
+    PM_TOKEN_MISSING,
+
+    /** a token that was not present but it is okay */
+    PM_TOKEN_NOT_PROVIDED,
+
     /** The maximum token value. */
     PM_TOKEN_MAXIMUM,
 } pm_token_type_t;
@@ -1420,6 +1424,17 @@ typedef struct pm_array_pattern_node {
 
     /**
      * ArrayPatternNode#constant
+     *
+     * Represents the optional constant preceding the Array
+     *
+     *     foo in Bar[]
+     *            ^^^
+     *
+     *     foo in Bar[1, 2, 3]
+     *            ^^^
+     *
+     *     foo in Bar::Baz[1, 2, 3]
+     *            ^^^^^^^^
      */
     struct pm_node *constant;
 
@@ -2623,7 +2638,7 @@ typedef struct pm_case_node {
      * Represents the predicate of the case statement. This can be either `nil` or any [non-void expressions](https://github.com/ruby/prism/blob/main/docs/parsing_rules.md#non-void-expression).
      *
      *     case true; when false; end
-     *     ^^^^
+     *          ^^^^
      */
     struct pm_node *predicate;
 
@@ -2692,6 +2707,11 @@ typedef struct pm_class_node {
 
     /**
      * ClassNode#class_keyword_loc
+     *
+     * Represents the location of the `class` keyword.
+     *
+     *     class Foo end
+     *     ^^^^^
      */
     pm_location_t class_keyword_loc;
 
@@ -2702,26 +2722,51 @@ typedef struct pm_class_node {
 
     /**
      * ClassNode#inheritance_operator_loc
+     *
+     * Represents the location of the `<` operator.
+     *
+     *     class Foo < Bar
+     *               ^
      */
     pm_location_t inheritance_operator_loc;
 
     /**
      * ClassNode#superclass
+     *
+     * Represents the superclass of the class.
+     *
+     *     class Foo < Bar
+     *                 ^^^
      */
     struct pm_node *superclass;
 
     /**
      * ClassNode#body
+     *
+     * Represents the body of the class.
+     *
+     *     class Foo
+     *       foo
+     *       ^^^
      */
     struct pm_node *body;
 
     /**
      * ClassNode#end_keyword_loc
+     *
+     * Represents the location of the `end` keyword.
+     *
+     *     class Foo end
+     *               ^^^
      */
     pm_location_t end_keyword_loc;
 
     /**
      * ClassNode#name
+     *
+     * The name of the class.
+     *
+     *     class Foo end # name `:Foo`
      */
     pm_constant_id_t name;
 } pm_class_node_t;
@@ -3758,6 +3803,9 @@ typedef struct pm_false_node {
  *     foo in Foo(*bar, baz, *qux)
  *            ^^^^^^^^^^^^^^^^^^^^
  *
+ *     foo => *bar, baz, *qux
+ *            ^^^^^^^^^^^^^^^
+ *
  * Type: ::PM_FIND_PATTERN_NODE
  *
  * @extends pm_node_t
@@ -3769,31 +3817,76 @@ typedef struct pm_find_pattern_node {
 
     /**
      * FindPatternNode#constant
+     *
+     * Represents the optional constant preceding the pattern
+     *
+     *     foo in Foo(*bar, baz, *qux)
+     *            ^^^
      */
     struct pm_node *constant;
 
     /**
      * FindPatternNode#left
+     *
+     * Represents the first wildcard node in the pattern.
+     *
+     *     foo in *bar, baz, *qux
+     *            ^^^^
+     *
+     *     foo in Foo(*bar, baz, *qux)
+     *                ^^^^
      */
     struct pm_splat_node *left;
 
     /**
      * FindPatternNode#requireds
+     *
+     * Represents the nodes in between the wildcards.
+     *
+     *     foo in *bar, baz, *qux
+     *                  ^^^
+     *
+     *     foo in Foo(*bar, baz, 1, *qux)
+     *                      ^^^^^^
      */
     struct pm_node_list requireds;
 
     /**
      * FindPatternNode#right
+     *
+     * Represents the second wildcard node in the pattern.
+     *
+     *     foo in *bar, baz, *qux
+     *                       ^^^^
+     *
+     *     foo in Foo(*bar, baz, *qux)
+     *                           ^^^^
      */
     struct pm_node *right;
 
     /**
      * FindPatternNode#opening_loc
+     *
+     * The location of the opening brace.
+     *
+     *     foo in [*bar, baz, *qux]
+     *            ^
+     *
+     *     foo in Foo(*bar, baz, *qux)
+     *               ^
      */
     pm_location_t opening_loc;
 
     /**
      * FindPatternNode#closing_loc
+     *
+     * The location of the closing brace.
+     *
+     *     foo in [*bar, baz, *qux]
+     *                            ^
+     *
+     *     foo in Foo(*bar, baz, *qux)
+     *                               ^
      */
     pm_location_t closing_loc;
 } pm_find_pattern_node_t;
@@ -4306,6 +4399,12 @@ typedef struct pm_hash_node {
  *     foo => { a: 1, b: 2, **c }
  *            ^^^^^^^^^^^^^^^^^^^
  *
+ *     foo => Bar[a: 1, b: 2]
+ *            ^^^^^^^^^^^^^^^
+ *
+ *     foo in { a: 1, b: 2 }
+ *            ^^^^^^^^^^^^^^
+ *
  * Type: ::PM_HASH_PATTERN_NODE
  *
  * @extends pm_node_t
@@ -4317,26 +4416,66 @@ typedef struct pm_hash_pattern_node {
 
     /**
      * HashPatternNode#constant
+     *
+     * Represents the optional constant preceding the Hash.
+     *
+     *     foo => Bar[a: 1, b: 2]
+     *          ^^^
+     *
+     *     foo => Bar::Baz[a: 1, b: 2]
+     *          ^^^^^^^^
      */
     struct pm_node *constant;
 
     /**
      * HashPatternNode#elements
+     *
+     * Represents the explicit named hash keys and values.
+     *
+     *     foo => { a: 1, b:, ** }
+     *              ^^^^^^^^
      */
     struct pm_node_list elements;
 
     /**
      * HashPatternNode#rest
+     *
+     * Represents the rest of the Hash keys and values. This can be named, unnamed, or explicitly forbidden via `**nil`, this last one results in a `NoKeywordsParameterNode`.
+     *
+     *     foo => { a: 1, b:, **c }
+     *                        ^^^
+     *
+     *     foo => { a: 1, b:, ** }
+     *                        ^^
+     *
+     *     foo => { a: 1, b:, **nil }
+     *                        ^^^^^
      */
     struct pm_node *rest;
 
     /**
      * HashPatternNode#opening_loc
+     *
+     * The location of the opening brace.
+     *
+     *     foo => { a: 1 }
+     *            ^
+     *
+     *     foo => Bar[a: 1]
+     *               ^
      */
     pm_location_t opening_loc;
 
     /**
      * HashPatternNode#closing_loc
+     *
+     * The location of the closing brace.
+     *
+     *     foo => { a: 1 }
+     *                   ^
+     *
+     *     foo => Bar[a: 1]
+     *                    ^
      */
     pm_location_t closing_loc;
 } pm_hash_pattern_node_t;
@@ -5618,6 +5757,9 @@ typedef struct pm_local_variable_read_node {
  *     foo, bar = baz
  *     ^^^  ^^^
  *
+ *     foo => baz
+ *            ^^^
+ *
  * Type: ::PM_LOCAL_VARIABLE_TARGET_NODE
  *
  * @extends pm_node_t
@@ -5820,16 +5962,70 @@ typedef struct pm_match_required_node {
 
     /**
      * MatchRequiredNode#value
+     *
+     * Represents the left-hand side of the operator.
+     *
+     *     foo => bar
+     *     ^^^
      */
     struct pm_node *value;
 
     /**
      * MatchRequiredNode#pattern
+     *
+     * Represents the right-hand side of the operator. The type of the node depends on the expression.
+     *
+     * Anything that looks like a local variable name (including `_`) will result in a `LocalVariableTargetNode`.
+     *
+     *     foo => a # This is equivalent to writing `a = foo`
+     *            ^
+     *
+     * Using an explicit `Array` or combining expressions with `,` will result in a `ArrayPatternNode`. This can be preceded by a constant.
+     *
+     *     foo => [a]
+     *            ^^^
+     *
+     *     foo => a, b
+     *            ^^^^
+     *
+     *     foo => Bar[a, b]
+     *            ^^^^^^^^^
+     *
+     * If the array pattern contains at least two wildcard matches, a `FindPatternNode` is created instead.
+     *
+     *     foo => *, 1, *a
+     *            ^^^^^
+     *
+     * Using an explicit `Hash` or a constant with square brackets and hash keys in the square brackets will result in a `HashPatternNode`.
+     *
+     *     foo => { a: 1, b: }
+     *
+     *     foo => Bar[a: 1, b:]
+     *
+     *     foo => Bar[**]
+     *
+     * To use any variable that needs run time evaluation, pinning is required. This results in a `PinnedVariableNode`
+     *
+     *     foo => ^a
+     *            ^^
+     *
+     * Similar, any expression can be used with pinning. This results in a `PinnedExpressionNode`.
+     *
+     *     foo => ^(a + 1)
+     *
+     * Anything else will result in the regular node for that expression, for example a `ConstantReadNode`.
+     *
+     *     foo => CONST
      */
     struct pm_node *pattern;
 
     /**
      * MatchRequiredNode#operator_loc
+     *
+     * The location of the operator.
+     *
+     *     foo => bar
+     *         ^^
      */
     pm_location_t operator_loc;
 } pm_match_required_node_t;
@@ -6487,21 +6683,41 @@ typedef struct pm_pinned_expression_node {
 
     /**
      * PinnedExpressionNode#expression
+     *
+     * The expression used in the pinned expression
+     *
+     *     foo in ^(bar)
+     *              ^^^
      */
     struct pm_node *expression;
 
     /**
      * PinnedExpressionNode#operator_loc
+     *
+     * The location of the `^` operator
+     *
+     *     foo in ^(bar)
+     *            ^
      */
     pm_location_t operator_loc;
 
     /**
      * PinnedExpressionNode#lparen_loc
+     *
+     * The location of the opening parenthesis.
+     *
+     *     foo in ^(bar)
+     *             ^
      */
     pm_location_t lparen_loc;
 
     /**
      * PinnedExpressionNode#rparen_loc
+     *
+     * The location of the closing parenthesis.
+     *
+     *     foo in ^(bar)
+     *                 ^
      */
     pm_location_t rparen_loc;
 } pm_pinned_expression_node_t;
@@ -6525,11 +6741,21 @@ typedef struct pm_pinned_variable_node {
 
     /**
      * PinnedVariableNode#variable
+     *
+     * The variable used in the pinned expression
+     *
+     *     foo in ^bar
+     *             ^^^
      */
     struct pm_node *variable;
 
     /**
      * PinnedVariableNode#operator_loc
+     *
+     * The location of the `^` operator
+     *
+     *     foo in ^bar
+     *            ^
      */
     pm_location_t operator_loc;
 } pm_pinned_variable_node_t;
@@ -7764,6 +7990,8 @@ typedef enum pm_arguments_node_flags {
 
     /** if the arguments contain multiple splats */
     PM_ARGUMENTS_NODE_FLAGS_CONTAINS_MULTIPLE_SPLATS = 64,
+
+    PM_ARGUMENTS_NODE_FLAGS_LAST,
 } pm_arguments_node_flags_t;
 
 /**
@@ -7772,6 +8000,8 @@ typedef enum pm_arguments_node_flags {
 typedef enum pm_array_node_flags {
     /** if array contains splat nodes */
     PM_ARRAY_NODE_FLAGS_CONTAINS_SPLAT = 4,
+
+    PM_ARRAY_NODE_FLAGS_LAST,
 } pm_array_node_flags_t;
 
 /**
@@ -7789,6 +8019,8 @@ typedef enum pm_call_node_flags {
 
     /** a call that ignores method visibility */
     PM_CALL_NODE_FLAGS_IGNORE_VISIBILITY = 32,
+
+    PM_CALL_NODE_FLAGS_LAST,
 } pm_call_node_flags_t;
 
 /**
@@ -7800,6 +8032,8 @@ typedef enum pm_encoding_flags {
 
     /** internal bytes forced the encoding to binary */
     PM_ENCODING_FLAGS_FORCED_BINARY_ENCODING = 8,
+
+    PM_ENCODING_FLAGS_LAST,
 } pm_encoding_flags_t;
 
 /**
@@ -7817,6 +8051,8 @@ typedef enum pm_integer_base_flags {
 
     /** 0x prefix */
     PM_INTEGER_BASE_FLAGS_HEXADECIMAL = 32,
+
+    PM_INTEGER_BASE_FLAGS_LAST,
 } pm_integer_base_flags_t;
 
 /**
@@ -7828,6 +8064,8 @@ typedef enum pm_interpolated_string_node_flags {
 
     /** mutable by virtue of a `frozen_string_literal: false` comment or `--disable-frozen-string-literal`; only for adjacent string literals like `'a' 'b'` */
     PM_INTERPOLATED_STRING_NODE_FLAGS_MUTABLE = 8,
+
+    PM_INTERPOLATED_STRING_NODE_FLAGS_LAST,
 } pm_interpolated_string_node_flags_t;
 
 /**
@@ -7836,6 +8074,8 @@ typedef enum pm_interpolated_string_node_flags {
 typedef enum pm_keyword_hash_node_flags {
     /** a keyword hash which only has `AssocNode` elements all with symbol keys, which means the elements can be treated as keyword arguments */
     PM_KEYWORD_HASH_NODE_FLAGS_SYMBOL_KEYS = 4,
+
+    PM_KEYWORD_HASH_NODE_FLAGS_LAST,
 } pm_keyword_hash_node_flags_t;
 
 /**
@@ -7844,6 +8084,8 @@ typedef enum pm_keyword_hash_node_flags {
 typedef enum pm_loop_flags {
     /** a loop after a begin statement, so the body is executed first before the condition */
     PM_LOOP_FLAGS_BEGIN_MODIFIER = 4,
+
+    PM_LOOP_FLAGS_LAST,
 } pm_loop_flags_t;
 
 /**
@@ -7852,6 +8094,8 @@ typedef enum pm_loop_flags {
 typedef enum pm_parameter_flags {
     /** a parameter name that has been repeated in the method signature */
     PM_PARAMETER_FLAGS_REPEATED_PARAMETER = 4,
+
+    PM_PARAMETER_FLAGS_LAST,
 } pm_parameter_flags_t;
 
 /**
@@ -7860,6 +8104,8 @@ typedef enum pm_parameter_flags {
 typedef enum pm_parentheses_node_flags {
     /** parentheses that contain multiple potentially void statements */
     PM_PARENTHESES_NODE_FLAGS_MULTIPLE_STATEMENTS = 4,
+
+    PM_PARENTHESES_NODE_FLAGS_LAST,
 } pm_parentheses_node_flags_t;
 
 /**
@@ -7868,6 +8114,8 @@ typedef enum pm_parentheses_node_flags {
 typedef enum pm_range_flags {
     /** ... operator */
     PM_RANGE_FLAGS_EXCLUDE_END = 4,
+
+    PM_RANGE_FLAGS_LAST,
 } pm_range_flags_t;
 
 /**
@@ -7906,6 +8154,8 @@ typedef enum pm_regular_expression_flags {
 
     /** internal bytes forced the encoding to US-ASCII */
     PM_REGULAR_EXPRESSION_FLAGS_FORCED_US_ASCII_ENCODING = 4096,
+
+    PM_REGULAR_EXPRESSION_FLAGS_LAST,
 } pm_regular_expression_flags_t;
 
 /**
@@ -7920,6 +8170,8 @@ typedef enum pm_shareable_constant_node_flags {
 
     /** constant writes that should be modified with shareable constant value experimental copy */
     PM_SHAREABLE_CONSTANT_NODE_FLAGS_EXPERIMENTAL_COPY = 16,
+
+    PM_SHAREABLE_CONSTANT_NODE_FLAGS_LAST,
 } pm_shareable_constant_node_flags_t;
 
 /**
@@ -7937,6 +8189,8 @@ typedef enum pm_string_flags {
 
     /** mutable by virtue of a `frozen_string_literal: false` comment or `--disable-frozen-string-literal` */
     PM_STRING_FLAGS_MUTABLE = 32,
+
+    PM_STRING_FLAGS_LAST,
 } pm_string_flags_t;
 
 /**
@@ -7951,6 +8205,8 @@ typedef enum pm_symbol_flags {
 
     /** internal bytes forced the encoding to US-ASCII */
     PM_SYMBOL_FLAGS_FORCED_US_ASCII_ENCODING = 16,
+
+    PM_SYMBOL_FLAGS_LAST,
 } pm_symbol_flags_t;
 
 /**