docspring 3.0.0 → 3.1.0

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Parser
+  ##
+  # {Parser::ClobberingError} is raised when {Parser::Source::Rewriter}
+  # detects a clobbering rewrite action. This class inherits {RuntimeError}
+  # rather than {StandardError} for backward compatibility.
+  #
+  # @api public
+  #
+  class ClobberingError < RuntimeError
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Parser
+  module Color
+    def self.color(str, code, bold: false)
+      return str unless STDOUT.tty?
+      code = Array(code)
+      code.unshift(1) if bold
+      "\e[#{code.join(';')}m#{str}\e[0m"
+    end
+
+    def self.red(str, bold: false)
+      color(str, 31, bold: bold)
+    end
+
+    def self.green(str, bold: false)
+      color(str, 32, bold: bold)
+    end
+
+    def self.yellow(str, bold: false)
+      color(str, 33, bold: bold)
+    end
+
+    def self.magenta(str, bold: false)
+      color(str, 35, bold: bold)
+    end
+
+    def self.underline(str)
+      color(str, 4)
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Parser
+  # Context of parsing that is represented by a stack of scopes.
+  #
+  # Supported states:
+  # + :class - in the class body (class A; end)
+  # + :module - in the module body (module M; end)
+  # + :sclass - in the singleton class body (class << obj; end)
+  # + :def - in the method body (def m; end)
+  # + :defs - in the singleton method body (def self.m; end)
+  # + :def_open_args - in the arglist of the method definition
+  #                    keep in mind that it's set **only** after reducing the first argument,
+  #                    if you need to handle the first argument check `lex_state == expr_fname`
+  # + :block - in the block body (tap {})
+  # + :lambda - in the lambda body (-> {})
+  #
+  class Context
+    FLAGS = %i[
+      in_defined
+      in_kwarg
+      in_argdef
+      in_def
+      in_class
+      in_block
+      in_lambda
+      cant_return
+    ]
+
+    def initialize
+      reset
+    end
+
+    def reset
+      @in_defined = false
+      @in_kwarg = false
+      @in_argdef = false
+      @in_def = false
+      @in_class = false
+      @in_block = false
+      @in_lambda = false
+      @cant_return = false
+    end
+
+    attr_accessor(*FLAGS)
+
+    def in_dynamic_block?
+      in_block || in_lambda
+    end
+  end
+end

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

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Parser
+  class << self
+    def warn_syntax_deviation(feature, version)
+      warn "warning: parser/current is loading #{feature}, which recognizes " \
+        "#{version}-compliant syntax, but you are running #{RUBY_VERSION}.\n" \
+        "Please see https://github.com/whitequark/parser#compatibility-with-ruby-mri."
+    end
+    private :warn_syntax_deviation
+  end
+
+  case RUBY_VERSION
+  when /^2\.0\./
+    current_version = '2.0.0'
+    if RUBY_VERSION != current_version
+      warn_syntax_deviation 'parser/ruby20', current_version
+    end
+
+    require_relative 'ruby20'
+    CurrentRuby = Ruby20
+
+  when /^2\.1\./
+    current_version = '2.1.10'
+    if RUBY_VERSION != current_version
+      warn_syntax_deviation 'parser/ruby21', current_version
+    end
+
+    require_relative 'ruby21'
+    CurrentRuby = Ruby21
+
+  when /^2\.2\./
+    current_version = '2.2.10'
+    if RUBY_VERSION != current_version
+      warn_syntax_deviation 'parser/ruby22', current_version
+    end
+
+    require_relative 'ruby22'
+    CurrentRuby = Ruby22
+
+  when /^2\.3\./
+    current_version = '2.3.8'
+    if RUBY_VERSION != current_version
+      warn_syntax_deviation 'parser/ruby23', current_version
+    end
+
+    require_relative 'ruby23'
+    CurrentRuby = Ruby23
+
+  when /^2\.4\./
+    current_version = '2.4.10'
+    if RUBY_VERSION != current_version
+      warn_syntax_deviation 'parser/ruby24', current_version
+    end
+
+    require_relative 'ruby24'
+    CurrentRuby = Ruby24
+
+  when /^2\.5\./
+    current_version = '2.5.9'
+    if RUBY_VERSION != current_version
+      warn_syntax_deviation 'parser/ruby25', current_version
+    end
+
+    require_relative 'ruby25'
+    CurrentRuby = Ruby25
+
+  when /^2\.6\./
+    current_version = '2.6.10'
+    if RUBY_VERSION != current_version
+      warn_syntax_deviation 'parser/ruby26', current_version
+    end
+
+    require_relative 'ruby26'
+    CurrentRuby = Ruby26
+
+  when /^2\.7\./
+    current_version = '2.7.8'
+    if RUBY_VERSION != current_version
+      warn_syntax_deviation 'parser/ruby27', current_version
+    end
+
+    require_relative 'ruby27'
+    CurrentRuby = Ruby27
+
+  when /^3\.0\./
+    current_version = '3.0.7'
+    if RUBY_VERSION != current_version
+      warn_syntax_deviation 'parser/ruby30', current_version
+    end
+
+    require_relative 'ruby30'
+    CurrentRuby = Ruby30
+
+  when /^3\.1\./
+    current_version = '3.1.6'
+    if RUBY_VERSION != current_version
+      warn_syntax_deviation 'parser/ruby31', current_version
+    end
+
+    require_relative 'ruby31'
+    CurrentRuby = Ruby31
+
+  when /^3\.2\./
+    current_version = '3.2.7'
+    if RUBY_VERSION != current_version
+      warn_syntax_deviation 'parser/ruby32', current_version
+    end
+
+    require_relative 'ruby32'
+    CurrentRuby = Ruby32
+
+  when /^3\.3\./
+    current_version = '3.3.7'
+    if RUBY_VERSION != current_version
+      warn_syntax_deviation 'parser/ruby33', current_version
+    end
+
+    require_relative 'ruby33'
+    CurrentRuby = Ruby33
+
+  when /^3\.4\./
+    current_version = '3.4.0-dev'
+    if RUBY_VERSION != current_version
+      warn_syntax_deviation 'parser/ruby34', current_version
+    end
+
+    require_relative 'ruby34'
+    CurrentRuby = Ruby34
+
+  else # :nocov:
+    # Keep this in sync with released Ruby.
+    warn_syntax_deviation 'parser/ruby33', '3.3.x'
+    require_relative 'ruby33'
+    CurrentRuby = Ruby33
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Parser
+  # Stack that holds names of current arguments,
+  # i.e. while parsing
+  #   def m1(a = (def m2(b = def m3(c = 1); end); end)); end
+  #                                   ^
+  # stack is [:a, :b, :c]
+  #
+  # Emulates `p->cur_arg` in MRI's parse.y
+  #
+  # @api private
+  #
+  class CurrentArgStack
+    attr_reader :stack
+
+    def initialize
+      @stack = []
+      freeze
+    end
+
+    def empty?
+      @stack.size == 0
+    end
+
+    def push(value)
+      @stack << value
+    end
+
+    def set(value)
+      @stack[@stack.length - 1] = value
+    end
+
+    def pop
+      @stack.pop
+    end
+
+    def reset
+      @stack.clear
+    end
+
+    def top
+      @stack.last
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Parser
+  ##
+  # @api private
+  #
+  module Deprecation
+    attr_writer :warned_of_deprecation
+    def warn_of_deprecation
+      @warned_of_deprecation ||= warn(self::DEPRECATION_WARNING) || true
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Parser
+
+  ##
+  # {Parser::Diagnostic::Engine} provides a basic API for dealing with
+  # diagnostics by delegating them to registered consumers.
+  #
+  # @example
+  #  buffer      = Parser::Source::Buffer.new(__FILE__, source: 'foobar')
+  #
+  #  consumer = lambda do |diagnostic|
+  #    puts diagnostic.message
+  #  end
+  #
+  #  engine     = Parser::Diagnostic::Engine.new(consumer)
+  #  diagnostic = Parser::Diagnostic.new(
+  #      :warning, :unexpected_token, { :token => 'abc' }, buffer, 1..2)
+  #
+  #  engine.process(diagnostic) # => "unexpected token abc"
+  #
+  # @api public
+  #
+  # @!attribute [rw] consumer
+  #  @return [#call(Diagnostic)]
+  #
+  # @!attribute [rw] all_errors_are_fatal
+  #  When set to `true` any error that is encountered will result in
+  #  {Parser::SyntaxError} being raised.
+  #  @return [Boolean]
+  #
+  # @!attribute [rw] ignore_warnings
+  #  When set to `true` warnings will be ignored.
+  #  @return [Boolean]
+  #
+  class Diagnostic::Engine
+    attr_accessor :consumer
+
+    attr_accessor :all_errors_are_fatal
+    attr_accessor :ignore_warnings
+
+    ##
+    # @param [#call(Diagnostic)] consumer
+    #
+    def initialize(consumer=nil)
+      @consumer             = consumer
+
+      @all_errors_are_fatal = false
+      @ignore_warnings      = false
+    end
+
+    ##
+    # Processes a `diagnostic`:
+    #   * Passes the diagnostic to the consumer, if it's not a warning when
+    #     `ignore_warnings` is set.
+    #   * After that, raises {Parser::SyntaxError} when `all_errors_are_fatal`
+    #     is set to true.
+    #
+    # @param [Parser::Diagnostic] diagnostic
+    # @return [Parser::Diagnostic::Engine]
+    # @see ignore?
+    # @see raise?
+    #
+    def process(diagnostic)
+      if ignore?(diagnostic)
+        # do nothing
+      elsif @consumer
+        @consumer.call(diagnostic)
+      end
+
+      if raise?(diagnostic)
+        raise Parser::SyntaxError, diagnostic
+      end
+
+      self
+    end
+
+    protected
+
+    ##
+    # Checks whether `diagnostic` should be ignored.
+    #
+    # @param [Parser::Diagnostic] diagnostic
+    # @return [Boolean]
+    #
+    def ignore?(diagnostic)
+      @ignore_warnings &&
+            diagnostic.level == :warning
+    end
+
+    ##
+    # Checks whether `diagnostic` should be raised as an exception.
+    #
+    # @param [Parser::Diagnostic] diagnostic
+    # @return [Boolean]
+    #
+    def raise?(diagnostic)
+      (@all_errors_are_fatal &&
+          diagnostic.level == :error) ||
+        diagnostic.level == :fatal
+    end
+  end
+
+end

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Parser
+
+  ##
+  # @api public
+  #
+  # @!attribute [r] level
+  #  @see LEVELS
+  #  @return [Symbol] diagnostic level
+  #
+  # @!attribute [r] reason
+  #  @see Parser::MESSAGES
+  #  @return [Symbol] reason for error
+  #
+  # @!attribute [r] arguments
+  #  @see Parser::MESSAGES
+  #  @return [Symbol] extended arguments that describe the error
+  #
+  # @!attribute [r] message
+  #  @return [String] error message
+  #
+  # @!attribute [r] location
+  #  Main error-related source range.
+  #  @return [Parser::Source::Range]
+  #
+  # @!attribute [r] highlights
+  #  Supplementary error-related source ranges.
+  #  @return [Array<Parser::Source::Range>]
+  #
+  class Diagnostic
+    ##
+    # Collection of the available diagnostic levels.
+    #
+    # @return [Array]
+    #
+    LEVELS = [:note, :warning, :error, :fatal].freeze
+
+    attr_reader :level, :reason, :arguments
+    attr_reader :location, :highlights
+
+    ##
+    # @param [Symbol] level
+    # @param [Symbol] reason
+    # @param [Hash] arguments
+    # @param [Parser::Source::Range] location
+    # @param [Array<Parser::Source::Range>] highlights
+    #
+    def initialize(level, reason, arguments, location, highlights=[])
+      unless LEVELS.include?(level)
+        raise ArgumentError,
+              "Diagnostic#level must be one of #{LEVELS.join(', ')}; " \
+              "#{level.inspect} provided."
+      end
+      raise 'Expected a location' unless location
+
+      @level       = level
+      @reason      = reason
+      @arguments   = (arguments || {}).dup.freeze
+      @location    = location
+      @highlights  = highlights.dup.freeze
+
+      freeze
+    end
+
+    ##
+    # @return [String] the rendered message.
+    #
+    def message
+      Messages.compile(@reason, @arguments)
+    end
+
+    ##
+    # Renders the diagnostic message as a clang-like diagnostic.
+    #
+    # @example
+    #  diagnostic.render # =>
+    #  # [
+    #  #   "(fragment:0):1:5: error: unexpected token $end",
+    #  #   "foo +",
+    #  #   "    ^"
+    #  # ]
+    #
+    # @return [Array<String>]
+    #
+    def render
+      if @location.line == @location.last_line || @location.is?("\n")
+        ["#{@location}: #{@level}: #{message}"] + render_line(@location)
+      else
+        # multi-line diagnostic
+        first_line = first_line_only(@location)
+        last_line  = last_line_only(@location)
+        num_lines  = (@location.last_line - @location.line) + 1
+        buffer     = @location.source_buffer
+
+        last_lineno, last_column = buffer.decompose_position(@location.end_pos)
+        ["#{@location}-#{last_lineno}:#{last_column}: #{@level}: #{message}"] +
+          render_line(first_line, num_lines > 2, false) +
+          render_line(last_line, false, true)
+      end
+    end
+
+    private
+
+    ##
+    # Renders one source line in clang diagnostic style, with highlights.
+    #
+    # @return [Array<String>]
+    #
+    def render_line(range, ellipsis=false, range_end=false)
+      source_line    = range.source_line
+      highlight_line = ' ' * source_line.length
+
+      @highlights.each do |highlight|
+       line_range = range.source_buffer.line_range(range.line)
+        if highlight = highlight.intersect(line_range)
+          highlight_line[highlight.column_range] = '~' * highlight.size
+        end
+      end
+
+      if range.is?("\n")
+        highlight_line += "^"
+      else
+        if !range_end && range.size >= 1
+          highlight_line[range.column_range] = '^' + '~' * (range.size - 1)
+        else
+          highlight_line[range.column_range] = '~' * range.size
+        end
+      end
+
+      highlight_line += '...' if ellipsis
+
+      [source_line, highlight_line].
+        map { |line| "#{range.source_buffer.name}:#{range.line}: #{line}" }
+    end
+
+    ##
+    # If necessary, shrink a `Range` so as to include only the first line.
+    #
+    # @return [Parser::Source::Range]
+    #
+    def first_line_only(range)
+      if range.line != range.last_line
+        range.resize(range.source =~ /\n/)
+      else
+        range
+      end
+    end
+
+    ##
+    # If necessary, shrink a `Range` so as to include only the last line.
+    #
+    # @return [Parser::Source::Range]
+    #
+    def last_line_only(range)
+      if range.line != range.last_line
+        range.adjust(begin_pos: range.source =~ /[^\n]*\z/)
+      else
+        range
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Parser
+
+  class Lexer::Dedenter
+    # Tab (\t) counts as 8 spaces
+    TAB_WIDTH = 8
+
+    def initialize(dedent_level)
+      @dedent_level = dedent_level
+      @at_line_begin = true
+      @indent_level  = 0
+    end
+
+    # For a heredoc like
+    #   <<-HERE
+    #     a
+    #     b
+    #   HERE
+    # this method gets called with "  a\n" and "  b\n"
+    #
+    # However, the following heredoc:
+    #
+    #   <<-HERE
+    #     a\
+    #     b
+    #   HERE
+    # calls this method only once with a string "  a\\\n  b\n"
+    #
+    # This is important because technically it's a single line,
+    # but it has to be concatenated __after__ dedenting.
+    #
+    # It has no effect for non-squiggly heredocs, i.e. it simply removes "\\\n"
+    # Of course, lexer could do it but once again: it's all because of dedenting.
+    #
+    def dedent(string)
+      original_encoding = string.encoding
+      # Prevent the following error when processing binary encoded source.
+      # "\xC0".split # => ArgumentError (invalid byte sequence in UTF-8)
+      lines = string.force_encoding(Encoding::BINARY).split("\\\n")
+      if lines.length == 1
+        # If the line continuation sequence was found but there is no second
+        # line, it was not really a line continuation and must be ignored.
+        lines = [string.force_encoding(original_encoding)]
+      else
+        lines.map! {|s| s.force_encoding(original_encoding) }
+      end
+
+      if @at_line_begin
+        lines_to_dedent = lines
+      else
+        _first, *lines_to_dedent = lines
+      end
+
+      lines_to_dedent.each do |line|
+        left_to_remove = @dedent_level
+        remove = 0
+
+        line.each_char do |char|
+          break if left_to_remove <= 0
+          case char
+          when ?\s
+            remove += 1
+            left_to_remove -= 1
+          when ?\t
+            break if TAB_WIDTH * (remove / TAB_WIDTH + 1) > @dedent_level
+            remove += 1
+            left_to_remove -= TAB_WIDTH
+          else
+            # no more spaces or tabs
+            break
+          end
+        end
+
+        line.slice!(0, remove)
+      end
+
+      string.replace(lines.join)
+
+      @at_line_begin = string.end_with?("\n")
+    end
+
+    def interrupt
+      @at_line_begin = false
+    end
+  end
+
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Parser
+
+  module Lexer::Explanation
+
+    def self.included(klass)
+      klass.class_exec do
+        alias_method :state_before_explanation=,  :state=
+        alias_method :advance_before_explanation, :advance
+
+        remove_method :state=, :advance
+      end
+    end
+
+    # Like #advance, but also pretty-print the token and its position
+    # in the stream to `stdout`.
+    def advance
+      type, (val, range) = advance_before_explanation
+
+      more = "(in-kwarg)" if @context.in_kwarg
+
+      puts decorate(range,
+                    Color.green("#{type} #{val.inspect}"),
+                    "#{state.to_s.ljust(12)} #{@cond} #{@cmdarg} #{more}")
+
+      [ type, [val, range] ]
+    end
+
+    def state=(new_state)
+      puts "  #{Color.yellow(">>> STATE SET <<<", bold: true)} " +
+           "#{new_state.to_s.ljust(12)} #{@cond} #{@cmdarg}".rjust(66)
+
+      self.state_before_explanation = new_state
+    end
+
+    private
+
+    def decorate(range, token, info)
+      from, to = range.begin.column, range.end.column
+
+      line = range.source_line + '   '
+      line[from...to] = Color.underline(line[from...to])
+
+      tail_len   = to - from - 1
+      tail       = '~' * (tail_len >= 0 ? tail_len : 0)
+      decoration =  "#{" " * from}#{Color.red("^#{tail}", bold: true)} #{token} ".
+                        ljust(68) + info
+
+      [ line, decoration ]
+    end
+
+  end
+
+end