docspring 3.0.0 → 3.1.0

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Parser
+  module Source
+
+    ##
+    # A comment in the source code.
+    #
+    # @!attribute [r] text
+    #  @return [String]
+    #
+    # @!attribute [r] location
+    #  @return [Parser::Source::Range]
+    #
+    # @api public
+    #
+    class Comment
+      attr_reader  :text
+
+      attr_reader  :location
+      alias_method :loc, :location
+
+      ##
+      # Associate `comments` with `ast` nodes by their corresponding node.
+      #
+      # @param [Parser::AST::Node] ast
+      # @param [Array<Comment>]    comments
+      # @return [Hash<Parser::AST::Node, Array<Comment>>]
+      # @see Parser::Source::Comment::Associator#associate
+      # @deprecated Use {associate_locations}.
+      #
+      def self.associate(ast, comments)
+        associator = Associator.new(ast, comments)
+        associator.associate
+      end
+
+      ##
+      # Associate `comments` with `ast` nodes by their location in the
+      # source.
+      #
+      # @param [Parser::AST::Node] ast
+      # @param [Array<Comment>]    comments
+      # @return [Hash<Parser::Source::Map, Array<Comment>>]
+      # @see Parser::Source::Comment::Associator#associate_locations
+      #
+      def self.associate_locations(ast, comments)
+        associator = Associator.new(ast, comments)
+        associator.associate_locations
+      end
+
+      ##
+      # Associate `comments` with `ast` nodes using identity.
+      #
+      # @param [Parser::AST::Node] ast
+      # @param [Array<Comment>]    comments
+      # @return [Hash<Parser::Source::Node, Array<Comment>>]
+      # @see Parser::Source::Comment::Associator#associate_by_identity
+      #
+      def self.associate_by_identity(ast, comments)
+        associator = Associator.new(ast, comments)
+        associator.associate_by_identity
+      end
+
+      ##
+      # @param [Parser::Source::Range] range
+      #
+      def initialize(range)
+        @location = Parser::Source::Map.new(range)
+        @text     = range.source.freeze
+
+        freeze
+      end
+
+      ##
+      # Type of this comment.
+      #
+      #   * Inline comments correspond to `:inline`:
+      #
+      #         # whatever
+      #
+      #   * Block comments correspond to `:document`:
+      #
+      #         =begin
+      #         hi i am a document
+      #         =end
+      #
+      # @return [Symbol]
+      #
+      def type
+        if text.start_with?("#".freeze)
+          :inline
+        elsif text.start_with?("=begin".freeze)
+          :document
+        end
+      end
+
+      ##
+      # @see #type
+      # @return [Boolean] true if this is an inline comment.
+      #
+      def inline?
+        type == :inline
+      end
+
+      ##
+      # @see #type
+      # @return [Boolean] true if this is a block comment.
+      #
+      def document?
+        type == :document
+      end
+
+      ##
+      # Compares comments. Two comments are equal if they
+      # correspond to the same source range.
+      #
+      # @param [Object] other
+      # @return [Boolean]
+      #
+      def ==(other)
+        other.is_a?(Source::Comment) &&
+          @location == other.location
+      end
+
+      ##
+      # @return [String] a human-readable representation of this comment
+      #
+      def inspect
+        "#<Parser::Source::Comment #{@location.expression.to_s} #{text.inspect}>"
+      end
+    end
+
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/parser-3.3.7.2/lib/parser/source/map/collection.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Parser
+  module Source
+
+    class Map::Collection < Map
+      attr_reader :begin
+      attr_reader :end
+
+      def initialize(begin_l, end_l, expression_l)
+        @begin, @end = begin_l, end_l
+
+        super(expression_l)
+      end
+    end
+
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/parser-3.3.7.2/lib/parser/source/map/condition.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Parser
+  module Source
+
+    class Map::Condition < Map
+      attr_reader :keyword
+      attr_reader :begin
+      attr_reader :else
+      attr_reader :end
+
+      def initialize(keyword_l, begin_l, else_l, end_l, expression_l)
+        @keyword = keyword_l
+        @begin, @else, @end = begin_l, else_l, end_l
+
+        super(expression_l)
+      end
+    end
+
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/parser-3.3.7.2/lib/parser/source/map/constant.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Parser
+  module Source
+
+    class Map::Constant < Map
+      attr_reader :double_colon
+      attr_reader :name
+      attr_reader :operator
+
+      def initialize(double_colon, name, expression)
+        @double_colon, @name = double_colon, name
+
+        super(expression)
+      end
+
+      ##
+      # @api private
+      #
+      def with_operator(operator_l)
+        with { |map| map.update_operator(operator_l) }
+      end
+
+      protected
+
+      def update_operator(operator_l)
+        @operator = operator_l
+      end
+    end
+
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/parser-3.3.7.2/lib/parser/source/map/definition.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Parser
+  module Source
+
+    class Map::Definition < Map
+      attr_reader :keyword
+      attr_reader :operator
+      attr_reader :name
+      attr_reader :end
+
+      def initialize(keyword_l, operator_l, name_l, end_l)
+        @keyword  = keyword_l
+        @operator = operator_l
+        @name     = name_l
+        @end      = end_l
+
+        super(@keyword.join(@end))
+      end
+    end
+
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/parser-3.3.7.2/lib/parser/source/map/for.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Parser
+  module Source
+
+    class Map::For < Map
+      attr_reader :keyword, :in
+      attr_reader :begin, :end
+
+      def initialize(keyword_l, in_l, begin_l, end_l, expression_l)
+        @keyword, @in = keyword_l, in_l
+        @begin, @end  = begin_l, end_l
+
+        super(expression_l)
+      end
+    end
+
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/parser-3.3.7.2/lib/parser/source/map/heredoc.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Parser
+  module Source
+
+    class Map::Heredoc < Map
+      attr_reader :heredoc_body
+      attr_reader :heredoc_end
+
+      def initialize(begin_l, body_l, end_l)
+        @heredoc_body = body_l
+        @heredoc_end  = end_l
+
+        super(begin_l)
+      end
+    end
+
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/parser-3.3.7.2/lib/parser/source/map/index.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Parser
+  module Source
+
+    class Map::Index < Map
+      attr_reader :begin
+      attr_reader :end
+      attr_reader :operator
+
+      def initialize(begin_l, end_l, expression_l)
+        @begin, @end = begin_l, end_l
+        @operator = nil
+
+        super(expression_l)
+      end
+
+      ##
+      # @api private
+      #
+      def with_operator(operator_l)
+        with { |map| map.update_operator(operator_l) }
+      end
+
+      protected
+
+      def update_operator(operator_l)
+        @operator = operator_l
+      end
+    end
+
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/parser-3.3.7.2/lib/parser/source/map/keyword.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Parser
+  module Source
+
+    class Map::Keyword < Map
+      attr_reader :keyword
+      attr_reader :begin
+      attr_reader :end
+
+      def initialize(keyword_l, begin_l, end_l, expression_l)
+        @keyword     = keyword_l
+        @begin, @end = begin_l, end_l
+
+        super(expression_l)
+      end
+    end
+
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/parser-3.3.7.2/lib/parser/source/map/method_definition.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Parser
+  module Source
+
+    class Map::MethodDefinition < Map
+      attr_reader :keyword
+      attr_reader :operator
+      attr_reader :name
+      attr_reader :end
+      attr_reader :assignment
+
+      def initialize(keyword_l, operator_l, name_l, end_l, assignment_l, body_l)
+        @keyword  = keyword_l
+        @operator = operator_l
+        @name     = name_l
+        @end      = end_l
+        @assignment = assignment_l
+
+        super(@keyword.join(end_l || body_l))
+      end
+    end
+
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/parser-3.3.7.2/lib/parser/source/map/objc_kwarg.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Parser
+  module Source
+
+    class Map::ObjcKwarg < Map
+      attr_reader :keyword
+      attr_reader :operator
+      attr_reader :argument
+
+      def initialize(keyword_l, operator_l, argument_l, expression_l)
+        @keyword, @operator, @argument = keyword_l, operator_l, argument_l
+
+        super(expression_l)
+      end
+    end
+
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/parser-3.3.7.2/lib/parser/source/map/operator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Parser
+  module Source
+
+    class Map::Operator < Map
+      attr_reader :operator
+
+      def initialize(operator, expression)
+        @operator = operator
+
+        super(expression)
+      end
+    end
+
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/parser-3.3.7.2/lib/parser/source/map/rescue_body.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Parser
+  module Source
+
+    class Map::RescueBody < Map
+      attr_reader :keyword
+      attr_reader :assoc
+      attr_reader :begin
+
+      def initialize(keyword_l, assoc_l, begin_l, expression_l)
+        @keyword = keyword_l
+        @assoc   = assoc_l
+        @begin   = begin_l
+
+        super(expression_l)
+      end
+    end
+
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/parser-3.3.7.2/lib/parser/source/map/send.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Parser
+  module Source
+
+    class Map::Send < Map
+      attr_reader :dot
+      attr_reader :selector
+      attr_reader :operator
+      attr_reader :begin
+      attr_reader :end
+
+      def initialize(dot_l, selector_l, begin_l, end_l, expression_l)
+        @dot         = dot_l
+        @selector    = selector_l
+        @begin, @end = begin_l, end_l
+
+        super(expression_l)
+      end
+
+      ##
+      # @api private
+      #
+      def with_operator(operator_l)
+        with { |map| map.update_operator(operator_l) }
+      end
+
+      protected
+
+      def update_operator(operator_l)
+        @operator = operator_l
+      end
+    end
+
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/parser-3.3.7.2/lib/parser/source/map/ternary.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Parser
+  module Source
+
+    class Map::Ternary < Map
+      attr_reader :question
+      attr_reader :colon
+
+      def initialize(question_l, colon_l, expression_l)
+        @question, @colon = question_l, colon_l
+
+        super(expression_l)
+      end
+    end
+
+  end
+end

data/vendor/bundle/ruby/3.3.0/gems/parser-3.3.7.2/lib/parser/source/map/variable.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Parser
+  module Source
+
+    class Map::Variable < Map
+      attr_reader :name
+      attr_reader :operator
+
+      def initialize(name_l, expression_l=name_l)
+        @name = name_l
+
+        super(expression_l)
+      end
+
+      ##
+      # @api private
+      #
+      def with_operator(operator_l)
+        with { |map| map.update_operator(operator_l) }
+      end
+
+      protected
+
+      def update_operator(operator_l)
+        @operator = operator_l
+      end
+    end
+
+  end
+end

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

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Parser
+  module Source
+
+    ##
+    # {Map} relates AST nodes to the source code they were parsed from.
+    # More specifically, a {Map} or its subclass contains a set of ranges:
+    #
+    #  * `expression`: smallest range which includes all source corresponding
+    #    to the node and all `expression` ranges of its children.
+    #  * other ranges (`begin`, `end`, `operator`, ...): node-specific ranges
+    #    pointing to various interesting tokens corresponding to the node.
+    #
+    # Note that the {Map::Heredoc} map is the only one whose `expression` does
+    # not include other ranges. It only covers the heredoc marker (`<<HERE`),
+    # not the here document itself.
+    #
+    # All ranges except `expression` are defined by {Map} subclasses.
+    #
+    # Ranges (except `expression`) can be `nil` if the corresponding token is
+    # not present in source. For example, a hash may not have opening/closing
+    # braces, and so would its source map.
+    #
+    #     p Parser::CurrentRuby.parse('[1 => 2]').children[0].loc
+    #     # => <Parser::Source::Map::Collection:0x007f5492b547d8
+    #     #  @end=nil, @begin=nil,
+    #     #  @expression=#<Source::Range (string) 1...7>>
+    #
+    # The {file:doc/AST_FORMAT.md} document describes how ranges associated to source
+    # code tokens. For example, the entry
+    #
+    #     (array (int 1) (int 2))
+    #
+    #     "[1, 2]"
+    #      ^ begin
+    #           ^ end
+    #      ~~~~~~ expression
+    #
+    # means that if `node` is an {Parser::AST::Node} `(array (int 1) (int 2))`,
+    # then `node.loc` responds to `begin`, `end` and `expression`, and
+    # `node.loc.begin` returns a range pointing at the opening bracket, and so on.
+    #
+    # If you want to write code polymorphic by the source map (i.e. accepting
+    # several subclasses of {Map}), use `respond_to?` instead of `is_a?` to
+    # check whether the map features the range you need. Concrete {Map}
+    # subclasses may not be preserved between versions, but their interfaces
+    # will be kept compatible.
+    #
+    # You can visualize the source maps with `ruby-parse -E` command-line tool.
+    #
+    # @example
+    #  require 'parser/current'
+    #
+    #  p Parser::CurrentRuby.parse('[1, 2]').loc
+    #  # => #<Parser::Source::Map::Collection:0x007f14b80eccd8
+    #  #  @end=#<Source::Range (string) 5...6>,
+    #  #  @begin=#<Source::Range (string) 0...1>,
+    #  #  @expression=#<Source::Range (string) 0...6>>
+    #
+    # @!attribute [r] node
+    #  The node that is described by this map. Nodes and maps have 1:1 correspondence.
+    #  @return [Parser::AST::Node]
+    #
+    # @!attribute [r] expression
+    #  @return [Range]
+    #
+    # @api public
+    #
+    class Map
+      attr_reader :node
+      attr_reader :expression
+
+      ##
+      # @param [Range] expression
+      def initialize(expression)
+        @expression = expression
+      end
+
+      ##
+      # @api private
+      def initialize_copy(other)
+        super
+        @node = nil
+      end
+
+      ##
+      # @api private
+      def node=(node)
+        @node = node
+        freeze
+        @node
+      end
+
+      ##
+      # A shortcut for `self.expression.line`.
+      # @return [Integer]
+      #
+      def line
+        @expression.line
+      end
+
+      alias_method :first_line, :line
+
+      ##
+      # A shortcut for `self.expression.column`.
+      # @return [Integer]
+      #
+      def column
+        @expression.column
+      end
+
+      ##
+      # A shortcut for `self.expression.last_line`.
+      # @return [Integer]
+      #
+      def last_line
+        @expression.last_line
+      end
+
+      ##
+      # A shortcut for `self.expression.last_column`.
+      # @return [Integer]
+      #
+      def last_column
+        @expression.last_column
+      end
+
+      ##
+      # @api private
+      #
+      def with_expression(expression_l)
+        with { |map| map.update_expression(expression_l) }
+      end
+
+      ##
+      # Compares source maps.
+      # @return [Boolean]
+      #
+      def ==(other)
+        other.class == self.class &&
+          instance_variables.map do |ivar|
+            instance_variable_get(ivar) ==
+              other.send(:instance_variable_get, ivar)
+          end.reduce(:&)
+      end
+
+      ##
+      # Converts this source map to a hash with keys corresponding to
+      # ranges. For example, if called on an instance of {Collection},
+      # which adds the `begin` and `end` ranges, the resulting hash
+      # will contain keys `:expression`, `:begin` and `:end`.
+      #
+      # @example
+      #  require 'parser/current'
+      #
+      #  p Parser::CurrentRuby.parse('[1, 2]').loc.to_hash
+      #  # => {
+      #  #   :begin => #<Source::Range (string) 0...1>,
+      #  #   :end => #<Source::Range (string) 5...6>,
+      #  #   :expression => #<Source::Range (string) 0...6>
+      #  # }
+      #
+      # @return [Hash<Symbol, Parser::Source::Range>]
+      #
+      def to_hash
+        instance_variables.inject({}) do |hash, ivar|
+          next hash if ivar.to_sym == :@node
+          hash[ivar[1..-1].to_sym] = instance_variable_get(ivar)
+          hash
+        end
+      end
+
+      protected
+
+      def with(&block)
+        dup.tap(&block)
+      end
+
+      def update_expression(expression_l)
+        @expression = expression_l
+      end
+    end
+
+  end
+end