prism 0.26.0 → 0.27.0

data/ext/prism/extension.c

@@ -19,7 +19,9 @@ VALUE rb_cPrismEmbDocComment;
 VALUE rb_cPrismMagicComment;
 VALUE rb_cPrismParseError;
 VALUE rb_cPrismParseWarning;
+VALUE rb_cPrismResult;
 VALUE rb_cPrismParseResult;
+VALUE rb_cPrismParseLexResult;
 
 VALUE rb_cPrismDebugEncoding;
 
@@ -515,7 +517,7 @@ parser_warnings(pm_parser_t *parser, rb_encoding *encoding, VALUE source) {
  * Create a new parse result from the given parser, value, encoding, and source.
  */
 static VALUE
-parse_result_create(pm_parser_t *parser, VALUE value, rb_encoding *encoding, VALUE source) {
+parse_result_create(VALUE class, pm_parser_t *parser, VALUE value, rb_encoding *encoding, VALUE source) {
     VALUE result_argv[] = {
         value,
         parser_comments(parser, source),
@@ -526,7 +528,7 @@ parse_result_create(pm_parser_t *parser, VALUE value, rb_encoding *encoding, VAL
         source
     };
 
-    return rb_class_new_instance(7, result_argv, rb_cPrismParseResult);
+    return rb_class_new_instance(7, result_argv, class);
 }
 
 /******************************************************************************/
@@ -635,7 +637,7 @@ parse_lex_input(pm_string_t *input, const pm_options_t *options, bool return_nod
         value = parse_lex_data.tokens;
     }
 
-    VALUE result = parse_result_create(&parser, value, parse_lex_data.encoding, source);
+    VALUE result = parse_result_create(rb_cPrismParseLexResult, &parser, value, parse_lex_data.encoding, source);
     pm_node_destroy(&parser, node);
     pm_parser_free(&parser);
 
@@ -700,7 +702,7 @@ parse_input(pm_string_t *input, const pm_options_t *options) {
 
     VALUE source = pm_source_new(&parser, encoding);
     VALUE value = pm_ast_new(&parser, node, encoding, source);
-    VALUE result = parse_result_create(&parser, value, encoding, source) ;
+    VALUE result = parse_result_create(rb_cPrismParseResult, &parser, value, encoding, source) ;
 
     pm_node_destroy(&parser, node);
     pm_parser_free(&parser);
@@ -804,7 +806,7 @@ parse_stream(int argc, VALUE *argv, VALUE self) {
 
     VALUE source = pm_source_new(&parser, encoding);
     VALUE value = pm_ast_new(&parser, node, encoding, source);
-    VALUE result = parse_result_create(&parser, value, encoding, source);
+    VALUE result = parse_result_create(rb_cPrismParseResult, &parser, value, encoding, source);
 
     pm_node_destroy(&parser, node);
     pm_buffer_free(&buffer);
@@ -1362,7 +1364,10 @@ Init_prism(void) {
     rb_cPrismMagicComment = rb_define_class_under(rb_cPrism, "MagicComment", rb_cObject);
     rb_cPrismParseError = rb_define_class_under(rb_cPrism, "ParseError", rb_cObject);
     rb_cPrismParseWarning = rb_define_class_under(rb_cPrism, "ParseWarning", rb_cObject);
-    rb_cPrismParseResult = rb_define_class_under(rb_cPrism, "ParseResult", rb_cObject);
+
+    rb_cPrismResult = rb_define_class_under(rb_cPrism, "Result", rb_cObject);
+    rb_cPrismParseResult = rb_define_class_under(rb_cPrism, "ParseResult", rb_cPrismResult);
+    rb_cPrismParseLexResult = rb_define_class_under(rb_cPrism, "ParseLexResult", rb_cPrismResult);
 
     // Intern all of the options that we support so that we don't have to do it
     // every time we parse.

data/ext/prism/extension.h

@@ -1,7 +1,7 @@
 #ifndef PRISM_EXT_NODE_H
 #define PRISM_EXT_NODE_H
 
-#define EXPECTED_PRISM_VERSION "0.26.0"
+#define EXPECTED_PRISM_VERSION "0.27.0"
 
 #include <ruby.h>
 #include <ruby/encoding.h>

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;
@@ -1249,16 +1264,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 +1636,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 +2250,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,16 +2412,47 @@ 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
+     *
+     * The right-hand node of the path. Always a `ConstantReadNode` in a
+     * valid Ruby syntax tree.
+     *
+     *     ::Foo
+     *       ^^^
+     *
+     *     self::Test
+     *           ^^^^
+     *
+     *     a.b::C
+     *          ^
      */
     struct pm_node *child;
 
     /**
      * ConstantPathNode#delimiter_loc
+     *
+     * The location of the `::` delimiter.
+     *
+     *     ::Foo
+     *     ^^
+     *
+     *     One::Two
+     *        ^^
      */
     pm_location_t delimiter_loc;
 } pm_constant_path_node_t;
@@ -2485,16 +2556,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 +2641,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 +3235,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 +3373,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 +3932,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 +4436,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;
@@ -5350,6 +5580,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 +5794,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;

data/include/prism/diagnostic.h

@@ -163,6 +163,8 @@ typedef enum {
     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,
@@ -235,6 +237,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,

data/include/prism/version.h

@@ -14,7 +14,7 @@
 /**
  * The minor version of the Prism library as an int.
  */
-#define PRISM_VERSION_MINOR 26
+#define PRISM_VERSION_MINOR 27
 
 /**
  * The patch version of the Prism library as an int.
@@ -24,6 +24,6 @@
 /**
  * The version of the Prism library as a constant string.
  */
-#define PRISM_VERSION "0.26.0"
+#define PRISM_VERSION "0.27.0"
 
 #endif

data/lib/prism/ffi.rb

@@ -350,7 +350,7 @@ module Prism
         node, comments, magic_comments, data_loc, errors, warnings = loader.load_nodes
         tokens.each { |token,| token.value.force_encoding(loader.encoding) }
 
-        ParseResult.new([node, tokens], comments, magic_comments, data_loc, errors, warnings, source)
+        ParseLexResult.new([node, tokens], comments, magic_comments, data_loc, errors, warnings, source)
       end
     end
 

data/lib/prism/lex_compat.rb

@@ -10,6 +10,23 @@ module Prism
   # generally lines up. However, there are a few cases that require special
   # handling.
   class LexCompat # :nodoc:
+    # A result class specialized for holding tokens produced by the lexer.
+    class Result < Prism::Result
+      # The list of tokens that were produced by the lexer.
+      attr_reader :value
+
+      # Create a new lex compat result object with the given values.
+      def initialize(value, comments, magic_comments, data_loc, errors, warnings, source)
+        @value = value
+        super(comments, magic_comments, data_loc, errors, warnings, source)
+      end
+
+      # Implement the hash pattern matching interface for Result.
+      def deconstruct_keys(keys)
+        super.merge!(value: value)
+      end
+    end
+
     # This is a mapping of prism token types to Ripper token types. This is a
     # many-to-one mapping because we split up our token types, whereas Ripper
     # tends to group them.
@@ -844,7 +861,7 @@ module Prism
       # We sort by location to compare against Ripper's output
       tokens.sort_by!(&:location)
 
-      ParseResult.new(tokens, result.comments, result.magic_comments, result.data_loc, result.errors, result.warnings, Source.new(source))
+      Result.new(tokens, result.comments, result.magic_comments, result.data_loc, result.errors, result.warnings, Source.new(source))
     end
   end