docspring 3.0.0 → 3.1.0

data/vendor/bundle/ruby/3.3.0/gems/parser-3.3.7.2/lib/parser/ast/processor.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+module Parser
+  module AST
+
+    ##
+    # @api public
+    #
+    class Processor
+      include ::AST::Processor::Mixin
+
+      def process_regular_node(node)
+        node.updated(nil, process_all(node))
+      end
+
+      alias on_dstr     process_regular_node
+      alias on_dsym     process_regular_node
+      alias on_regexp   process_regular_node
+      alias on_xstr     process_regular_node
+      alias on_splat    process_regular_node
+      alias on_kwsplat  process_regular_node
+      alias on_array    process_regular_node
+      alias on_pair     process_regular_node
+      alias on_hash     process_regular_node
+      alias on_kwargs   process_regular_node
+      alias on_irange   process_regular_node
+      alias on_erange   process_regular_node
+
+      def on_var(node)
+        node
+      end
+
+      # @private
+      def process_variable_node(node)
+        on_var(node)
+      end
+
+      alias on_lvar     process_variable_node
+      alias on_ivar     process_variable_node
+      alias on_gvar     process_variable_node
+      alias on_cvar     process_variable_node
+      alias on_back_ref process_variable_node
+      alias on_nth_ref  process_variable_node
+
+      def on_vasgn(node)
+        name, value_node = *node
+
+        if !value_node.nil?
+          node.updated(nil, [
+            name, process(value_node)
+          ])
+        else
+          node
+        end
+      end
+
+      # @private
+      def process_var_asgn_node(node)
+        on_vasgn(node)
+      end
+
+      alias on_lvasgn   process_var_asgn_node
+      alias on_ivasgn   process_var_asgn_node
+      alias on_gvasgn   process_var_asgn_node
+      alias on_cvasgn   process_var_asgn_node
+
+      alias on_and_asgn process_regular_node
+      alias on_or_asgn  process_regular_node
+
+      def on_op_asgn(node)
+        var_node, method_name, value_node = *node
+
+        node.updated(nil, [
+          process(var_node), method_name, process(value_node)
+        ])
+      end
+
+      alias on_mlhs     process_regular_node
+      alias on_masgn    process_regular_node
+
+      def on_const(node)
+        scope_node, name = *node
+
+        node.updated(nil, [
+          process(scope_node), name
+        ])
+      end
+
+      def on_casgn(node)
+        scope_node, name, value_node = *node
+
+        if !value_node.nil?
+          node.updated(nil, [
+            process(scope_node), name, process(value_node)
+          ])
+        else
+          node.updated(nil, [
+            process(scope_node), name
+          ])
+        end
+      end
+
+      alias on_args     process_regular_node
+
+      def on_argument(node)
+        arg_name, value_node = *node
+
+        if !value_node.nil?
+          node.updated(nil, [
+            arg_name, process(value_node)
+          ])
+        else
+          node
+        end
+      end
+
+      # @private
+      def process_argument_node(node)
+        on_argument(node)
+      end
+
+      alias on_arg            process_argument_node
+      alias on_optarg         process_argument_node
+      alias on_restarg        process_argument_node
+      alias on_blockarg       process_argument_node
+      alias on_shadowarg      process_argument_node
+      alias on_kwarg          process_argument_node
+      alias on_kwoptarg       process_argument_node
+      alias on_kwrestarg      process_argument_node
+      alias on_forward_arg    process_argument_node
+
+      def on_procarg0(node)
+        if node.children[0].is_a?(Symbol)
+          # This branch gets executed when the builder
+          # is not configured to emit and 'arg' inside 'procarg0', i.e. when
+          #   Parser::Builders::Default.emit_arg_inside_procarg0
+          # is set to false.
+          #
+          # If this flag is set to true this branch is unreachable.
+          # s(:procarg0, :a)
+          on_argument(node)
+        else
+          # s(:procarg0, s(:arg, :a), s(:arg, :b))
+          process_regular_node(node)
+        end
+      end
+
+      alias on_arg_expr       process_regular_node
+      alias on_restarg_expr   process_regular_node
+      alias on_blockarg_expr  process_regular_node
+      alias on_block_pass     process_regular_node
+
+      alias on_forwarded_restarg   process_regular_node
+      alias on_forwarded_kwrestarg process_regular_node
+
+      alias on_module         process_regular_node
+      alias on_class          process_regular_node
+      alias on_sclass         process_regular_node
+
+      def on_def(node)
+        name, args_node, body_node = *node
+
+        node.updated(nil, [
+          name,
+          process(args_node), process(body_node)
+        ])
+      end
+
+      def on_defs(node)
+        definee_node, name, args_node, body_node = *node
+
+        node.updated(nil, [
+          process(definee_node), name,
+          process(args_node), process(body_node)
+        ])
+      end
+
+      alias on_undef    process_regular_node
+      alias on_alias    process_regular_node
+
+      def on_send(node)
+        receiver_node, method_name, *arg_nodes = *node
+
+        receiver_node = process(receiver_node) if receiver_node
+        node.updated(nil, [
+          receiver_node, method_name, *process_all(arg_nodes)
+        ])
+      end
+
+      alias on_csend on_send
+
+      alias on_index     process_regular_node
+      alias on_indexasgn process_regular_node
+
+      alias on_block    process_regular_node
+      alias on_lambda   process_regular_node
+
+      def on_numblock(node)
+        method_call, max_numparam, body = *node
+
+        node.updated(nil, [
+          process(method_call), max_numparam, process(body)
+        ])
+      end
+
+      alias on_while      process_regular_node
+      alias on_while_post process_regular_node
+      alias on_until      process_regular_node
+      alias on_until_post process_regular_node
+      alias on_for        process_regular_node
+
+      alias on_return   process_regular_node
+      alias on_break    process_regular_node
+      alias on_next     process_regular_node
+      alias on_redo     process_regular_node
+      alias on_retry    process_regular_node
+      alias on_super    process_regular_node
+      alias on_yield    process_regular_node
+      alias on_defined? process_regular_node
+
+      alias on_not      process_regular_node
+      alias on_and      process_regular_node
+      alias on_or       process_regular_node
+
+      alias on_if       process_regular_node
+
+      alias on_when     process_regular_node
+      alias on_case     process_regular_node
+
+      alias on_iflipflop process_regular_node
+      alias on_eflipflop process_regular_node
+
+      alias on_match_current_line process_regular_node
+      alias on_match_with_lvasgn  process_regular_node
+
+      alias on_resbody  process_regular_node
+      alias on_rescue   process_regular_node
+      alias on_ensure   process_regular_node
+
+      alias on_begin    process_regular_node
+      alias on_kwbegin  process_regular_node
+
+      alias on_preexe   process_regular_node
+      alias on_postexe  process_regular_node
+
+      alias on_case_match              process_regular_node
+      alias on_in_match                process_regular_node
+      alias on_match_pattern           process_regular_node
+      alias on_match_pattern_p         process_regular_node
+      alias on_in_pattern              process_regular_node
+      alias on_if_guard                process_regular_node
+      alias on_unless_guard            process_regular_node
+      alias on_match_var               process_variable_node
+      alias on_match_rest              process_regular_node
+      alias on_pin                     process_regular_node
+      alias on_match_alt               process_regular_node
+      alias on_match_as                process_regular_node
+      alias on_array_pattern           process_regular_node
+      alias on_array_pattern_with_tail process_regular_node
+      alias on_hash_pattern            process_regular_node
+      alias on_const_pattern           process_regular_node
+      alias on_find_pattern            process_regular_node
+
+      # @private
+      def process_variable_node(node)
+        warn 'Parser::AST::Processor#process_variable_node is deprecated as a' \
+          ' public API and will be removed. Please use ' \
+          'Parser::AST::Processor#on_var instead.'
+        on_var(node)
+      end
+
+      # @private
+      def process_var_asgn_node(node)
+        warn 'Parser::AST::Processor#process_var_asgn_node is deprecated as a' \
+          ' public API and will be removed. Please use ' \
+          'Parser::AST::Processor#on_vasgn instead.'
+        on_vasgn(node)
+      end
+
+      # @private
+      def process_argument_node(node)
+        warn 'Parser::AST::Processor#process_argument_node is deprecated as a' \
+          ' public API and will be removed. Please use ' \
+          'Parser::AST::Processor#on_argument instead.'
+        on_argument(node)
+      end
+
+      def on_empty_else(node)
+        node
+      end
+    end
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/parser-3.3.7.2/lib/parser/base.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module Parser
+
+  ##
+  # Base class for version-specific parsers.
+  #
+  # @api public
+  #
+  # @!attribute [r] diagnostics
+  #  @return [Parser::Diagnostic::Engine]
+  #
+  # @!attribute [r] static_env
+  #  @return [Parser::StaticEnvironment]
+  #
+  class Base < Racc::Parser
+    ##
+    # Parses a string of Ruby code and returns the AST. If the source
+    # cannot be parsed, {SyntaxError} is raised and a diagnostic is
+    # printed to `stderr`.
+    #
+    # @example
+    #  Parser::Base.parse('puts "hello"')
+    #
+    # @param [String] string The block of code to parse.
+    # @param [String] file The name of the file the code originated from.
+    # @param [Numeric] line The initial line number.
+    # @return [Parser::AST::Node]
+    #
+    def self.parse(string, file='(string)', line=1)
+      parser = default_parser
+      source_buffer = setup_source_buffer(file, line, string, parser.default_encoding)
+      parser.parse(source_buffer)
+    end
+
+    ##
+    # Parses a string of Ruby code and returns the AST and comments. If the
+    # source cannot be parsed, {SyntaxError} is raised and a diagnostic is
+    # printed to `stderr`.
+    #
+    # @example
+    #  Parser::Base.parse_with_comments('puts "hello"')
+    #
+    # @param [String] string The block of code to parse.
+    # @param [String] file The name of the file the code originated from.
+    # @param [Numeric] line The initial line number.
+    # @return [Array]
+    #
+    def self.parse_with_comments(string, file='(string)', line=1)
+      parser = default_parser
+      source_buffer = setup_source_buffer(file, line, string, parser.default_encoding)
+      parser.parse_with_comments(source_buffer)
+    end
+
+    ##
+    # Parses Ruby source code by reading it from a file. If the source
+    # cannot be parsed, {SyntaxError} is raised and a diagnostic is
+    # printed to `stderr`.
+    #
+    # @param [String] filename Path to the file to parse.
+    # @return [Parser::AST::Node]
+    # @see #parse
+    #
+    def self.parse_file(filename)
+      parse(File.read(filename), filename)
+    end
+
+    ##
+    # Parses Ruby source code by reading it from a file and returns the AST and
+    # comments. If the source cannot be parsed, {SyntaxError} is raised and a
+    # diagnostic is printed to `stderr`.
+    #
+    # @param [String] filename Path to the file to parse.
+    # @return [Array]
+    # @see #parse
+    #
+    def self.parse_file_with_comments(filename)
+      parse_with_comments(File.read(filename), filename)
+    end
+
+    ##
+    # @return [Parser::Base] parser with the default options set.
+    #
+    def self.default_parser
+      parser = new
+
+      parser.diagnostics.all_errors_are_fatal = true
+      parser.diagnostics.ignore_warnings      = true
+
+      parser.diagnostics.consumer = lambda do |diagnostic|
+        $stderr.puts(diagnostic.render)
+      end
+
+      parser
+    end
+
+    def self.setup_source_buffer(file, line, string, encoding)
+      string = string.dup.force_encoding(encoding)
+
+      source_buffer = Source::Buffer.new(file, line)
+
+      if name == 'Parser::Ruby18'
+        source_buffer.raw_source = string
+      else
+        source_buffer.source     = string
+      end
+
+      source_buffer
+    end
+    private_class_method :setup_source_buffer
+
+    attr_reader :lexer
+    attr_reader :diagnostics
+    attr_reader :builder
+    attr_reader :static_env
+    attr_reader :source_buffer
+    attr_reader :context
+    attr_reader :max_numparam_stack
+    attr_reader :current_arg_stack
+    attr_reader :pattern_variables
+    attr_reader :pattern_hash_keys
+
+    ##
+    # @param [Parser::Builders::Default] builder The AST builder to use.
+    #
+    def initialize(builder=Parser::Builders::Default.new)
+      @diagnostics = Diagnostic::Engine.new
+
+      @static_env  = StaticEnvironment.new
+
+      # Stack that holds current parsing context
+      @context = Context.new
+
+      # Maximum numbered parameters stack
+      @max_numparam_stack = MaxNumparamStack.new
+
+      # Current argument names stack
+      @current_arg_stack = CurrentArgStack.new
+
+      # Stack of set of variables used in the current pattern
+      @pattern_variables = VariablesStack.new
+
+      # Stack of set of keys used in the current hash in pattern matchinig
+      @pattern_hash_keys = VariablesStack.new
+
+      @lexer = Lexer.new(version)
+      @lexer.diagnostics = @diagnostics
+      @lexer.static_env  = @static_env
+      @lexer.context     = @context
+
+      @builder = builder
+      @builder.parser = self
+
+      # Last emitted token
+      @last_token = nil
+
+      if self.class::Racc_debug_parser && ENV['RACC_DEBUG']
+        @yydebug = true
+      end
+
+      reset
+    end
+
+    ##
+    # Resets the state of the parser.
+    #
+    def reset
+      @source_buffer = nil
+
+      @lexer.reset
+      @static_env.reset
+      @context.reset
+      @current_arg_stack.reset
+      @pattern_variables.reset
+      @pattern_hash_keys.reset
+
+      self
+    end
+
+    ##
+    # Parses a source buffer and returns the AST, or `nil` in case of a non fatal error.
+    #
+    # @param [Parser::Source::Buffer] source_buffer The source buffer to parse.
+    # @return [Parser::AST::Node, nil]
+    #
+    def parse(source_buffer)
+      @lexer.source_buffer = source_buffer
+      @source_buffer       = source_buffer
+
+      do_parse || nil # Force `false` to `nil`, see https://github.com/ruby/racc/pull/136
+    ensure
+      # Don't keep references to the source file.
+      @source_buffer       = nil
+      @lexer.source_buffer = nil
+    end
+
+    ##
+    # Parses a source buffer and returns the AST and the source code comments.
+    #
+    # @see #parse
+    # @see Parser::Source::Comment#associate
+    # @return [Array]
+    #
+    def parse_with_comments(source_buffer)
+      @lexer.comments = []
+
+      [ parse(source_buffer), @lexer.comments ]
+    ensure
+      @lexer.comments = nil
+    end
+
+    ##
+    # Parses a source buffer and returns the AST, the source code comments,
+    # and the tokens emitted by the lexer. In case of a fatal error, a {SyntaxError}
+    # is raised, unless `recover` is true. In case of an error
+    # (non-fatal or recovered), `nil` is returned instead of the AST, and
+    # comments as well as tokens are only returned up to the location of
+    # the error.
+    #
+    # Currently, token stream format returned by #tokenize is not documented,
+    # but is considered part of a public API and only changed according
+    # to Semantic Versioning.
+    #
+    # However, note that the exact token composition of various constructs
+    # might vary. For example, a string `"foo"` is represented equally well
+    # by `:tSTRING_BEG " :tSTRING_CONTENT foo :tSTRING_END "` and
+    # `:tSTRING "foo"`; such details must not be relied upon.
+    #
+    # @param [Parser::Source::Buffer] source_buffer
+    # @param [Boolean] recover If true, recover from syntax errors. False by default.
+    # @return [Array]
+    #
+    def tokenize(source_buffer, recover=false)
+      @lexer.tokens = []
+      @lexer.comments = []
+
+      begin
+        ast = parse(source_buffer)
+      rescue Parser::SyntaxError
+        raise if !recover
+      end
+
+      [ ast, @lexer.comments, @lexer.tokens ]
+    ensure
+      @lexer.tokens = nil
+      @lexer.comments = nil
+    end
+
+    private
+
+    def next_token
+      token = @lexer.advance
+      @last_token = token
+      token
+    end
+
+    def check_kwarg_name(name_t)
+      case name_t[0]
+      when /^[a-z_]/
+        # OK
+      when /^[A-Z]/
+        diagnostic :error, :argument_const, nil, name_t
+      end
+    end
+
+    def diagnostic(level, reason, arguments, location_t, highlights_ts=[])
+      _, location = location_t
+
+      highlights = highlights_ts.map do |token|
+        _, range = token
+        range
+      end
+
+      @diagnostics.process(
+          Diagnostic.new(level, reason, arguments, location, highlights))
+
+      if level == :error
+        yyerror
+      end
+    end
+
+    def on_error(error_token_id, error_value, value_stack)
+      token_name = token_to_str(error_token_id)
+      _, location = error_value
+
+      @diagnostics.process(Diagnostic.new(
+          :error, :unexpected_token, { :token => token_name }, location))
+    end
+  end
+
+end