prism 0.26.0 → 0.28.0

data/include/prism/ast.h

@@ -1099,16 +1099,31 @@ typedef struct pm_alias_global_variable_node {
 
     /**
      * AliasGlobalVariableNode#new_name
+     *
+     * 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.
+     *
+     *     alias $foo $bar
+     *           ^^^^
      */
     struct pm_node *new_name;
 
     /**
      * AliasGlobalVariableNode#old_name
+     *
+     * 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.
+     *
+     *     alias $foo $bar
+     *                ^^^^
      */
     struct pm_node *old_name;
 
     /**
      * AliasGlobalVariableNode#keyword_loc
+     *
+     * The location of the `alias` keyword.
+     *
+     *     alias $foo $bar
+     *     ^^^^^
      */
     pm_location_t keyword_loc;
 } pm_alias_global_variable_node_t;
@@ -1220,6 +1235,7 @@ typedef struct pm_and_node {
  *
  * Type: PM_ARGUMENTS_NODE
  * Flags:
+ *    PM_ARGUMENTS_NODE_FLAGS_CONTAINS_KEYWORDS
  *    PM_ARGUMENTS_NODE_FLAGS_CONTAINS_KEYWORD_SPLAT
  *
  * @extends pm_node_t
@@ -1249,16 +1265,32 @@ typedef struct pm_array_node {
 
     /**
      * ArrayNode#elements
+     *
+     * 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.
      */
     struct pm_node_list elements;
 
     /**
      * ArrayNode#opening_loc
+     *
+     * Represents the optional source location for the opening token.
+     *
+     *     [1,2,3]                 # "["
+     *     %w[foo bar baz]         # "%w["
+     *     %I(apple orange banana) # "%I("
+     *     foo = 1, 2, 3           # nil
      */
     pm_location_t opening_loc;
 
     /**
      * ArrayNode#closing_loc
+     *
+     * Represents the optional source location for the closing token.
+     *
+     *     [1,2,3]                 # "]"
+     *     %w[foo bar baz]         # "]"
+     *     %I(apple orange banana) # ")"
+     *     foo = 1, 2, 3           # nil
      */
     pm_location_t closing_loc;
 } pm_array_node_t;
@@ -1605,11 +1637,21 @@ typedef struct pm_break_node {
 
     /**
      * BreakNode#arguments
+     *
+     * 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).
+     *
+     *     break foo
+     *           ^^^
      */
     struct pm_arguments_node *arguments;
 
     /**
      * BreakNode#keyword_loc
+     *
+     * The location of the `break` keyword.
+     *
+     *     break foo
+     *     ^^^^^
      */
     pm_location_t keyword_loc;
 } pm_break_node_t;
@@ -2209,8 +2251,7 @@ typedef struct pm_class_variable_write_node {
     /**
      * ClassVariableWriteNode#value
      *
-     * The value to assign to the class variable. Can be any node that
-     * represents a non-void expression.
+     * 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).
      *
      *     @@foo = :bar
      *             ^^^^
@@ -2372,18 +2413,52 @@ typedef struct pm_constant_path_node {
 
     /**
      * ConstantPathNode#parent
+     *
+     * 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.
+     *
+     *     Foo::Bar
+     *     ^^^
+     *
+     *     self::Test
+     *     ^^^^
+     *
+     *     a.b::C
+     *     ^^^
      */
     struct pm_node *parent;
 
     /**
-     * ConstantPathNode#child
+     * ConstantPathNode#name
+     *
+     * The name of the constant being accessed. This could be `nil` in the event of a syntax error.
      */
-    struct pm_node *child;
+    pm_constant_id_t name;
 
     /**
      * ConstantPathNode#delimiter_loc
+     *
+     * The location of the `::` delimiter.
+     *
+     *     ::Foo
+     *     ^^
+     *
+     *     One::Two
+     *        ^^
      */
     pm_location_t delimiter_loc;
+
+    /**
+     * ConstantPathNode#name_loc
+     *
+     * The location of the name of the constant.
+     *
+     *     ::Foo
+     *       ^^^
+     *
+     *     One::Two
+     *          ^^^
+     */
+    pm_location_t name_loc;
 } pm_constant_path_node_t;
 
 /**
@@ -2462,14 +2537,19 @@ typedef struct pm_constant_path_target_node {
     struct pm_node *parent;
 
     /**
-     * ConstantPathTargetNode#child
+     * ConstantPathTargetNode#name
      */
-    struct pm_node *child;
+    pm_constant_id_t name;
 
     /**
      * ConstantPathTargetNode#delimiter_loc
      */
     pm_location_t delimiter_loc;
+
+    /**
+     * ConstantPathTargetNode#name_loc
+     */
+    pm_location_t name_loc;
 } pm_constant_path_target_node_t;
 
 /**
@@ -2485,16 +2565,34 @@ typedef struct pm_constant_path_write_node {
 
     /**
      * ConstantPathWriteNode#target
+     *
+     * A node representing the constant path being written to.
+     *
+     *     Foo::Bar = 1
+     *     ^^^^^^^^
+     *
+     *     ::Foo = :abc
+     *     ^^^^^
      */
     struct pm_constant_path_node *target;
 
     /**
      * ConstantPathWriteNode#operator_loc
+     *
+     * The location of the `=` operator.
+     *
+     *     ::ABC = 123
+     *           ^
      */
     pm_location_t operator_loc;
 
     /**
      * ConstantPathWriteNode#value
+     *
+     * 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).
+     *
+     *     FOO::BAR = :abc
+     *                ^^^^
      */
     struct pm_node *value;
 } pm_constant_path_write_node_t;
@@ -2552,21 +2650,45 @@ typedef struct pm_constant_write_node {
 
     /**
      * ConstantWriteNode#name
+     *
+     * The name of the [constant](https://github.com/ruby/prism/blob/main/docs/parsing_rules.md#constants).
+     *
+     *     Foo = :bar # name `:Foo`
+     *
+     *     XYZ = 1    # name `:XYZ`
      */
     pm_constant_id_t name;
 
     /**
      * ConstantWriteNode#name_loc
+     *
+     * The location of the constant name.
+     *
+     *     FOO = 1
+     *     ^^^
      */
     pm_location_t name_loc;
 
     /**
      * ConstantWriteNode#value
+     *
+     * 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).
+     *
+     *     FOO = :bar
+     *           ^^^^
+     *
+     *     MyClass = Class.new
+     *               ^^^^^^^^^
      */
     struct pm_node *value;
 
     /**
      * ConstantWriteNode#operator_loc
+     *
+     * The location of the `=` operator.
+     *
+     *     FOO = :bar
+     *         ^
      */
     pm_location_t operator_loc;
 } pm_constant_write_node_t;
@@ -3122,21 +3244,45 @@ typedef struct pm_global_variable_write_node {
 
     /**
      * GlobalVariableWriteNode#name
+     *
+     * 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.
+     *
+     *     $foo = :bar  # name `:$foo`
+     *
+     *     $_Test = 123 # name `:$_Test`
      */
     pm_constant_id_t name;
 
     /**
      * GlobalVariableWriteNode#name_loc
+     *
+     * The location of the global variable's name.
+     *
+     *     $foo = :bar
+     *     ^^^^
      */
     pm_location_t name_loc;
 
     /**
      * GlobalVariableWriteNode#value
+     *
+     * 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).
+     *
+     *     $foo = :bar
+     *            ^^^^
+     *
+     *     $-xyz = 123
+     *             ^^^
      */
     struct pm_node *value;
 
     /**
      * GlobalVariableWriteNode#operator_loc
+     *
+     * The location of the `=` operator.
+     *
+     *     $foo = :bar
+     *          ^
      */
     pm_location_t operator_loc;
 } pm_global_variable_write_node_t;
@@ -3236,31 +3382,89 @@ typedef struct pm_if_node {
 
     /**
      * IfNode#if_keyword_loc
+     *
+     * The location of the `if` keyword if present.
+     *
+     *     bar if foo
+     *         ^^
+     *
+     * The `if_keyword_loc` field will be `nil` when the `IfNode` represents a ternary expression.
      */
     pm_location_t if_keyword_loc;
 
     /**
      * IfNode#predicate
+     *
+     * The node for the condition the `IfNode` is testing.
+     *
+     *     if foo
+     *        ^^^
+     *       bar
+     *     end
+     *
+     *     bar if foo
+     *            ^^^
+     *
+     *     foo ? bar : baz
+     *     ^^^
      */
     struct pm_node *predicate;
 
     /**
      * IfNode#then_keyword_loc
+     *
+     * The location of the `then` keyword (if present) or the `?` in a ternary expression, `nil` otherwise.
+     *
+     *     if foo then bar end
+     *            ^^^^
+     *
+     *     a ? b : c
+     *       ^
      */
     pm_location_t then_keyword_loc;
 
     /**
      * IfNode#statements
+     *
+     * Represents the body of statements that will be executed when the predicate is evaluated as truthy. Will be `nil` when no body is provided.
+     *
+     *     if foo
+     *       bar
+     *       ^^^
+     *       baz
+     *       ^^^
+     *     end
      */
     struct pm_statements_node *statements;
 
     /**
      * IfNode#consequent
+     *
+     * Represents an `ElseNode` or an `IfNode` when there is an `else` or an `elsif` in the `if` statement.
+     *
+     *     if foo
+     *       bar
+     *     elsif baz
+     *     ^^^^^^^^^
+     *       qux
+     *       ^^^
+     *     end
+     *     ^^^
+     *
+     *     if foo then bar else baz end
+     *                     ^^^^^^^^^^^^
      */
     struct pm_node *consequent;
 
     /**
      * IfNode#end_keyword_loc
+     *
+     * The location of the `end` keyword if present, `nil` otherwise.
+     *
+     *     if foo
+     *       bar
+     *     end
+     *     ^^^
      */
     pm_location_t end_keyword_loc;
 } pm_if_node_t;
@@ -3737,8 +3941,7 @@ typedef struct pm_instance_variable_write_node {
     /**
      * InstanceVariableWriteNode#value
      *
-     * The value to assign to the instance variable. Can be any node that
-     * represents a non-void expression.
+     * 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).
      *
      *     @foo = :bar
      *            ^^^^
@@ -4242,26 +4445,62 @@ typedef struct pm_local_variable_write_node {
 
     /**
      * LocalVariableWriteNode#name
+     *
+     * The name of the local variable, which is an [identifier](https://github.com/ruby/prism/blob/main/docs/parsing_rules.md#identifiers).
+     *
+     *     foo = :bar # name `:foo`
+     *
+     *     abc = 123  # name `:abc`
      */
     pm_constant_id_t name;
 
     /**
      * LocalVariableWriteNode#depth
+     *
+     * The number of semantic scopes we have to traverse to find the declaration of this variable.
+     *
+     *     foo = 1         # depth 0
+     *
+     *     tap { foo = 1 } # depth 1
+     *
+     * 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).
      */
     uint32_t depth;
 
     /**
      * LocalVariableWriteNode#name_loc
+     *
+     * The location of the variable name.
+     *
+     *     foo = :bar
+     *     ^^^
      */
     pm_location_t name_loc;
 
     /**
      * LocalVariableWriteNode#value
+     *
+     * 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).
+     *
+     *     foo = :bar
+     *           ^^^^
+     *
+     *     abc = 1234
+     *           ^^^^
+     *
+     * 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.
+     *
+     *     foo = foo
      */
     struct pm_node *value;
 
     /**
      * LocalVariableWriteNode#operator_loc
+     *
+     * The location of the `=` operator.
+     *
+     *     x = :y
+     *       ^
      */
     pm_location_t operator_loc;
 } pm_local_variable_write_node_t;
@@ -5225,6 +5464,8 @@ typedef struct pm_retry_node {
  * ReturnNode
  *
  * Type: PM_RETURN_NODE
+ * Flags:
+ *    PM_RETURN_NODE_FLAGS_REDUNDANT
  *
  * @extends pm_node_t
  */
@@ -5350,6 +5591,8 @@ typedef struct pm_source_file_node {
 
     /**
      * SourceFileNode#filepath
+     *
+     * Represents the file path being parsed. This corresponds directly to the `filepath` option given to the various `Prism::parse*` APIs.
      */
     pm_string_t filepath;
 } pm_source_file_node_t;
@@ -5562,31 +5805,66 @@ typedef struct pm_unless_node {
 
     /**
      * UnlessNode#keyword_loc
+     *
+     * The location of the `unless` keyword.
+     *
+     *     unless cond then bar end
+     *     ^^^^^^
+     *
+     *     bar unless cond
+     *         ^^^^^^
      */
     pm_location_t keyword_loc;
 
     /**
      * UnlessNode#predicate
+     *
+     * 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).
+     *
+     *     unless cond then bar end
+     *            ^^^^
+     *
+     *     bar unless cond
+     *                ^^^^
      */
     struct pm_node *predicate;
 
     /**
      * UnlessNode#then_keyword_loc
+     *
+     * The location of the `then` keyword, if present.
+     * unless cond then bar end ^^^^
      */
     pm_location_t then_keyword_loc;
 
     /**
      * UnlessNode#statements
+     *
+     * The body of statements that will executed if the unless condition is
+     * falsey. Will be `nil` if no body is provided.
+     *
+     *     unless cond then bar end
+     *                      ^^^
      */
     struct pm_statements_node *statements;
 
     /**
      * UnlessNode#consequent
+     *
+     * The else clause of the unless expression, if present.
+     *
+     *     unless cond then bar else baz end
+     *                          ^^^^^^^^
      */
     struct pm_else_node *consequent;
 
     /**
      * UnlessNode#end_keyword_loc
+     *
+     * The location of the `end` keyword, if present.
+     *
+     *     unless cond then bar end
+     *                          ^^^
      */
     pm_location_t end_keyword_loc;
 } pm_unless_node_t;
@@ -5762,8 +6040,11 @@ typedef struct pm_yield_node {
  * Flags for arguments nodes.
  */
 typedef enum pm_arguments_node_flags {
+    /** if arguments contain keywords */
+    PM_ARGUMENTS_NODE_FLAGS_CONTAINS_KEYWORDS = 1,
+
     /** if arguments contain keyword splat */
-    PM_ARGUMENTS_NODE_FLAGS_CONTAINS_KEYWORD_SPLAT = 1,
+    PM_ARGUMENTS_NODE_FLAGS_CONTAINS_KEYWORD_SPLAT = 2,
 } pm_arguments_node_flags_t;
 
 /**
@@ -5900,6 +6181,14 @@ typedef enum pm_regular_expression_flags {
     PM_REGULAR_EXPRESSION_FLAGS_FORCED_US_ASCII_ENCODING = 1024,
 } pm_regular_expression_flags_t;
 
+/**
+ * Flags for return nodes.
+ */
+typedef enum pm_return_node_flags {
+    /** a return statement that is redundant because it is the last statement in a method */
+    PM_RETURN_NODE_FLAGS_REDUNDANT = 1,
+} pm_return_node_flags_t;
+
 /**
  * Flags for shareable constant nodes.
  */

data/include/prism/diagnostic.h

@@ -152,17 +152,20 @@ typedef enum {
     PM_ERR_HASH_ROCKET,
     PM_ERR_HASH_TERM,
     PM_ERR_HASH_VALUE,
+    PM_ERR_HEREDOC_IDENTIFIER,
     PM_ERR_HEREDOC_TERM,
     PM_ERR_INCOMPLETE_QUESTION_MARK,
     PM_ERR_INCOMPLETE_VARIABLE_CLASS,
-    PM_ERR_INCOMPLETE_VARIABLE_CLASS_3_3_0,
+    PM_ERR_INCOMPLETE_VARIABLE_CLASS_3_3,
     PM_ERR_INCOMPLETE_VARIABLE_INSTANCE,
-    PM_ERR_INCOMPLETE_VARIABLE_INSTANCE_3_3_0,
+    PM_ERR_INCOMPLETE_VARIABLE_INSTANCE_3_3,
     PM_ERR_INSTANCE_VARIABLE_BARE,
     PM_ERR_INVALID_BLOCK_EXIT,
     PM_ERR_INVALID_CHARACTER,
     PM_ERR_INVALID_ENCODING_MAGIC_COMMENT,
     PM_ERR_INVALID_FLOAT_EXPONENT,
+    PM_ERR_INVALID_LOCAL_VARIABLE_READ,
+    PM_ERR_INVALID_LOCAL_VARIABLE_WRITE,
     PM_ERR_INVALID_MULTIBYTE_CHAR,
     PM_ERR_INVALID_MULTIBYTE_CHARACTER,
     PM_ERR_INVALID_MULTIBYTE_ESCAPE,
@@ -170,14 +173,16 @@ typedef enum {
     PM_ERR_INVALID_NUMBER_DECIMAL,
     PM_ERR_INVALID_NUMBER_HEXADECIMAL,
     PM_ERR_INVALID_NUMBER_OCTAL,
-    PM_ERR_INVALID_NUMBER_UNDERSCORE,
+    PM_ERR_INVALID_NUMBER_UNDERSCORE_INNER,
+    PM_ERR_INVALID_NUMBER_UNDERSCORE_TRAILING,
     PM_ERR_INVALID_PERCENT,
     PM_ERR_INVALID_PRINTABLE_CHARACTER,
     PM_ERR_INVALID_RETRY_AFTER_ELSE,
     PM_ERR_INVALID_RETRY_AFTER_ENSURE,
     PM_ERR_INVALID_RETRY_WITHOUT_RESCUE,
+    PM_ERR_INVALID_SYMBOL,
     PM_ERR_INVALID_VARIABLE_GLOBAL,
-    PM_ERR_INVALID_VARIABLE_GLOBAL_3_3_0,
+    PM_ERR_INVALID_VARIABLE_GLOBAL_3_3,
     PM_ERR_INVALID_YIELD,
     PM_ERR_IT_NOT_ALLOWED_NUMBERED,
     PM_ERR_IT_NOT_ALLOWED_ORDINARY,
@@ -221,6 +226,7 @@ typedef enum {
     PM_ERR_PARAMETER_STAR,
     PM_ERR_PARAMETER_UNEXPECTED_FWD,
     PM_ERR_PARAMETER_WILD_LOOSE_COMMA,
+    PM_ERR_PARAMETER_UNEXPECTED_NO_KW,
     PM_ERR_PATTERN_CAPTURE_DUPLICATE,
     PM_ERR_PATTERN_EXPRESSION_AFTER_BRACKET,
     PM_ERR_PATTERN_EXPRESSION_AFTER_COMMA,
@@ -235,6 +241,7 @@ typedef enum {
     PM_ERR_PATTERN_HASH_KEY,
     PM_ERR_PATTERN_HASH_KEY_DUPLICATE,
     PM_ERR_PATTERN_HASH_KEY_LABEL,
+    PM_ERR_PATTERN_HASH_KEY_LOCALS,
     PM_ERR_PATTERN_IDENT_AFTER_HROCKET,
     PM_ERR_PATTERN_LABEL_AFTER_COMMA,
     PM_ERR_PATTERN_REST,
@@ -273,6 +280,9 @@ typedef enum {
     PM_ERR_UNARY_RECEIVER,
     PM_ERR_UNDEF_ARGUMENT,
     PM_ERR_UNEXPECTED_BLOCK_ARGUMENT,
+    PM_ERR_UNEXPECTED_INDEX_BLOCK,
+    PM_ERR_UNEXPECTED_INDEX_KEYWORDS,
+    PM_ERR_UNEXPECTED_SAFE_NAVIGATION,
     PM_ERR_UNEXPECTED_TOKEN_CLOSE_CONTEXT,
     PM_ERR_UNEXPECTED_TOKEN_IGNORE,
     PM_ERR_UNTIL_TERM,
@@ -293,7 +303,7 @@ typedef enum {
     PM_WARN_COMPARISON_AFTER_COMPARISON,
     PM_WARN_DOT_DOT_DOT_EOL,
     PM_WARN_EQUAL_IN_CONDITIONAL,
-    PM_WARN_EQUAL_IN_CONDITIONAL_3_3_0,
+    PM_WARN_EQUAL_IN_CONDITIONAL_3_3,
     PM_WARN_END_IN_METHOD,
     PM_WARN_DUPLICATED_HASH_KEY,
     PM_WARN_DUPLICATED_WHEN_CLAUSE,

data/include/prism/options.h

@@ -49,8 +49,8 @@ typedef enum {
     /** The current version of prism. */
     PM_OPTIONS_VERSION_LATEST = 0,
 
-    /** The vendored version of prism in CRuby 3.3.0. */
-    PM_OPTIONS_VERSION_CRUBY_3_3_0 = 1
+    /** The vendored version of prism in CRuby 3.3.x. */
+    PM_OPTIONS_VERSION_CRUBY_3_3 = 1
 } pm_options_version_t;
 
 /**

data/include/prism/parser.h

@@ -10,6 +10,7 @@
 #include "prism/ast.h"
 #include "prism/encoding.h"
 #include "prism/options.h"
+#include "prism/static_literals.h"
 #include "prism/util/pm_constant_pool.h"
 #include "prism/util/pm_list.h"
 #include "prism/util/pm_newline_list.h"
@@ -717,6 +718,15 @@ struct pm_parser {
     /** The current parsing context. */
     pm_context_node_t *current_context;
 
+    /**
+     * The hash keys for the hash that is currently being parsed. This is not
+     * usually necessary because it can pass it down the various call chains,
+     * but in the event that you're parsing a hash that is being directly
+     * pushed into another hash with **, we need to share the hash keys so that
+     * we can warn for the nested hash as well.
+     */
+    pm_static_literals_t *current_hash_keys;
+
     /**
      * The encoding functions for the current file is attached to the parser as
      * it's parsing so that it can change with a magic comment.