prism 0.15.1 → 0.17.0

data/lib/prism/parse_result.rb

@@ -5,31 +5,71 @@ module Prism
   # conjunction with locations to allow them to resolve line numbers and source
   # ranges.
   class Source
-    attr_reader :source, :offsets
+    # The source code that this source object represents.
+    attr_reader :source
 
-    def initialize(source, offsets = compute_offsets(source))
+    # The line number where this source starts.
+    attr_accessor :start_line
+
+    # The list of newline byte offsets in the source code.
+    attr_reader :offsets
+
+    # Create a new source object with the given source code and newline byte
+    # offsets. If no newline byte offsets are given, they will be computed from
+    # the source code.
+    def initialize(source, start_line = 1, offsets = compute_offsets(source))
       @source = source
+      @start_line = start_line
       @offsets = offsets
     end
 
+    # Perform a byteslice on the source code using the given byte offset and
+    # byte length.
     def slice(offset, length)
       source.byteslice(offset, length)
     end
 
+    # Binary search through the offsets to find the line number for the given
+    # byte offset.
     def line(value)
-      offsets.bsearch_index { |offset| offset > value } || offsets.length
+      start_line + find_line(value)
     end
 
+    # Return the byte offset of the start of the line corresponding to the given
+    # byte offset.
     def line_offset(value)
-      offsets[line(value) - 1]
+      offsets[find_line(value)]
     end
 
+    # Return the column number for the given byte offset.
     def column(value)
-      value - offsets[line(value) - 1]
+      value - offsets[find_line(value)]
     end
 
     private
 
+    # Binary search through the offsets to find the line number for the given
+    # byte offset.
+    def find_line(value)
+      left = 0
+      right = offsets.length - 1
+
+      while left <= right
+        mid = left + (right - left) / 2
+        return mid if offsets[mid] == value
+
+        if offsets[mid] < value
+          left = mid + 1
+        else
+          right = mid - 1
+        end
+      end
+
+      left - 1
+    end
+
+    # Find all of the newlines in the source code and return their byte offsets
+    # from the start of the string an array.
     def compute_offsets(code)
       offsets = [0]
       code.b.scan("\n") { offsets << $~.end(0) }
@@ -53,6 +93,8 @@ module Prism
     # The list of comments attached to this location
     attr_reader :comments
 
+    # Create a new location object with the given source, start byte offset, and
+    # byte length.
     def initialize(source, start_offset, length)
       @source = source
       @start_offset = start_offset
@@ -97,7 +139,7 @@ module Prism
 
     # The line number where this location ends.
     def end_line
-      source.line(end_offset - 1)
+      source.line(end_offset)
     end
 
     # The column number in bytes where this location starts from the start of
@@ -112,14 +154,17 @@ module Prism
       source.column(end_offset)
     end
 
+    # Implement the hash pattern matching interface for Location.
     def deconstruct_keys(keys)
       { start_offset: start_offset, end_offset: end_offset }
     end
 
+    # Implement the pretty print interface for Location.
     def pretty_print(q)
       q.text("(#{start_line},#{start_column})-(#{end_line},#{end_column})")
     end
 
+    # Returns true if the given other location is equal to this location.
     def ==(other)
       other.is_a?(Location) &&
         other.start_offset == start_offset &&
@@ -136,57 +181,99 @@ module Prism
       Location.new(source, start_offset, other.end_offset - start_offset)
     end
 
+    # Returns a null location that does not correspond to a source and points to
+    # the beginning of the file. Useful for when you want a location object but
+    # do not care where it points.
     def self.null
       new(nil, 0, 0)
     end
   end
 
-  # This represents a comment that was encountered during parsing.
+  # This represents a comment that was encountered during parsing. It is the
+  # base class for all comment types.
   class Comment
-    TYPES = [:inline, :embdoc, :__END__]
+    # The location of this comment in the source.
+    attr_reader :location
 
-    attr_reader :type, :location
-
-    def initialize(type, location)
-      @type = type
+    # Create a new comment object with the given location.
+    def initialize(location)
       @location = location
     end
 
+    # Implement the hash pattern matching interface for Comment.
     def deconstruct_keys(keys)
-      { type: type, location: location }
+      { location: location }
+    end
+
+    # This can only be true for inline comments.
+    def trailing?
+      false
     end
+  end
 
-    # Returns true if the comment happens on the same line as other code and false if the comment is by itself
+  # InlineComment objects are the most common. They correspond to comments in
+  # the source file like this one that start with #.
+  class InlineComment < Comment
+    # Returns true if this comment happens on the same line as other code and
+    # false if the comment is by itself.
     def trailing?
-      type == :inline && !location.start_line_slice.strip.empty?
+      !location.start_line_slice.strip.empty?
+    end
+
+    # Returns a string representation of this comment.
+    def inspect
+      "#<Prism::InlineComment @location=#{location.inspect}>"
     end
+  end
 
+  # EmbDocComment objects correspond to comments that are surrounded by =begin
+  # and =end.
+  class EmbDocComment < Comment
+    # Returns a string representation of this comment.
     def inspect
-      "#<Prism::Comment @type=#{@type.inspect} @location=#{@location.inspect}>"
+      "#<Prism::EmbDocComment @location=#{location.inspect}>"
+    end
+  end
+
+  # DATAComment objects correspond to comments that are after the __END__
+  # keyword in a source file.
+  class DATAComment < Comment
+    # Returns a string representation of this comment.
+    def inspect
+      "#<Prism::DATAComment @location=#{location.inspect}>"
     end
   end
 
   # This represents a magic comment that was encountered during parsing.
   class MagicComment
-    attr_reader :key_loc, :value_loc
+    # A Location object representing the location of the key in the source.
+    attr_reader :key_loc
+
+    # A Location object representing the location of the value in the source.
+    attr_reader :value_loc
 
+    # Create a new magic comment object with the given key and value locations.
     def initialize(key_loc, value_loc)
       @key_loc = key_loc
       @value_loc = value_loc
     end
 
+    # Returns the key of the magic comment by slicing it from the source code.
     def key
       key_loc.slice
     end
 
+    # Returns the value of the magic comment by slicing it from the source code.
     def value
       value_loc.slice
     end
 
+    # Implement the hash pattern matching interface for MagicComment.
     def deconstruct_keys(keys)
       { key_loc: key_loc, value_loc: value_loc }
     end
 
+    # Returns a string representation of this magic comment.
     def inspect
       "#<Prism::MagicComment @key=#{key.inspect} @value=#{value.inspect}>"
     end
@@ -194,17 +281,24 @@ module Prism
 
   # This represents an error that was encountered during parsing.
   class ParseError
-    attr_reader :message, :location
+    # The message associated with this error.
+    attr_reader :message
 
+    # A Location object representing the location of this error in the source.
+    attr_reader :location
+
+    # Create a new error object with the given message and location.
     def initialize(message, location)
       @message = message
       @location = location
     end
 
+    # Implement the hash pattern matching interface for ParseError.
     def deconstruct_keys(keys)
       { message: message, location: location }
     end
 
+    # Returns a string representation of this error.
     def inspect
       "#<Prism::ParseError @message=#{@message.inspect} @location=#{@location.inspect}>"
     end
@@ -212,17 +306,24 @@ module Prism
 
   # This represents a warning that was encountered during parsing.
   class ParseWarning
-    attr_reader :message, :location
+    # The message associated with this warning.
+    attr_reader :message
+
+    # A Location object representing the location of this warning in the source.
+    attr_reader :location
 
+    # Create a new warning object with the given message and location.
     def initialize(message, location)
       @message = message
       @location = location
     end
 
+    # Implement the hash pattern matching interface for ParseWarning.
     def deconstruct_keys(keys)
       { message: message, location: location }
     end
 
+    # Returns a string representation of this warning.
     def inspect
       "#<Prism::ParseWarning @message=#{@message.inspect} @location=#{@location.inspect}>"
     end
@@ -232,8 +333,27 @@ module Prism
   # the AST, any comments that were encounters, and any errors that were
   # encountered.
   class ParseResult
-    attr_reader :value, :comments, :magic_comments, :errors, :warnings, :source
+    # The value that was generated by parsing. Normally this holds the AST, but
+    # it can sometimes how a list of tokens or other results passed back from
+    # the parser.
+    attr_reader :value
 
+    # The list of comments that were encountered during parsing.
+    attr_reader :comments
+
+    # The list of magic comments that were encountered during parsing.
+    attr_reader :magic_comments
+
+    # The list of errors that were generated during parsing.
+    attr_reader :errors
+
+    # The list of warnings that were generated during parsing.
+    attr_reader :warnings
+
+    # A Source instance that represents the source code that was parsed.
+    attr_reader :source
+
+    # Create a new parse result object with the given values.
     def initialize(value, comments, magic_comments, errors, warnings, source)
       @value = value
       @comments = comments
@@ -243,14 +363,19 @@ module Prism
       @source = source
     end
 
+    # Implement the hash pattern matching interface for ParseResult.
     def deconstruct_keys(keys)
       { value: value, comments: comments, magic_comments: magic_comments, errors: errors, warnings: warnings }
     end
 
+    # Returns true if there were no errors during parsing and false if there
+    # were.
     def success?
       errors.empty?
     end
 
+    # Returns true if there were errors during parsing and false if there were
+    # not.
     def failure?
       !success?
     end
@@ -258,18 +383,28 @@ module Prism
 
   # This represents a token from the Ruby source.
   class Token
-    attr_reader :type, :value, :location
+    # The type of token that this token is.
+    attr_reader :type
+
+    # A byteslice of the source that this token represents.
+    attr_reader :value
+
+    # A Location object representing the location of this token in the source.
+    attr_reader :location
 
+    # Create a new token object with the given type, value, and location.
     def initialize(type, value, location)
       @type = type
       @value = value
       @location = location
     end
 
+    # Implement the hash pattern matching interface for Token.
     def deconstruct_keys(keys)
       { type: type, value: value, location: location }
     end
 
+    # Implement the pretty print interface for Token.
     def pretty_print(q)
       q.group do
         q.text(type.to_s)
@@ -284,6 +419,7 @@ module Prism
       end
     end
 
+    # Returns true if the given other token is equal to this token.
     def ==(other)
       other.is_a?(Token) &&
         other.type == type &&

data/lib/prism/pattern.rb

@@ -38,6 +38,8 @@ module Prism
     # Raised when the query given to a pattern is either invalid Ruby syntax or
     # is using syntax that we don't yet support.
     class CompilationError < StandardError
+      # Create a new CompilationError with the given representation of the node
+      # that caused the error.
       def initialize(repr)
         super(<<~ERROR)
           prism was unable to compile the pattern you provided into a usable
@@ -53,18 +55,27 @@ module Prism
       end
     end
 
+    # The query that this pattern was initialized with.
     attr_reader :query
 
+    # Create a new pattern with the given query. The query should be a string
+    # containing a Ruby pattern matching expression.
     def initialize(query)
       @query = query
       @compiled = nil
     end
 
+    # Compile the query into a callable object that can be used to match against
+    # nodes.
     def compile
       result = Prism.parse("case nil\nin #{query}\nend")
       compile_node(result.value.statements.body.last.conditions.last.pattern)
     end
 
+    # Scan the given node and all of its children for nodes that match the
+    # pattern. If a block is given, it will be called with each node that
+    # matches the pattern. If no block is given, an enumerator will be returned
+    # that will yield each node that matches the pattern.
     def scan(root)
       return to_enum(__method__, root) unless block_given?
 
@@ -158,12 +169,12 @@ module Prism
     # in InstanceVariableReadNode[name: Symbol]
     # in { name: Symbol }
     def compile_hash_pattern_node(node)
-      compile_error(node) unless node.kwrest.nil?
+      compile_error(node) if node.rest
       compiled_constant = compile_node(node.constant) if node.constant
 
       preprocessed =
-        node.assocs.to_h do |assoc|
-          [assoc.key.unescaped.to_sym, compile_node(assoc.value)]
+        node.elements.to_h do |element|
+          [element.key.unescaped.to_sym, compile_node(element.value)]
         end
 
       compiled_keywords = ->(other) do

data/lib/prism/ripper_compat.rb

@@ -35,11 +35,11 @@ module Prism
     class SexpBuilderPP < SexpBuilder
       private
 
-      def _dispatch_event_new
+      def _dispatch_event_new # :nodoc:
         []
       end
 
-      def _dispatch_event_push(list, item)
+      def _dispatch_event_push(list, item) # :nodoc:
         list << item
         list
       end
@@ -54,8 +54,16 @@ module Prism
       end
     end
 
-    attr_reader :source, :lineno, :column
+    # The source that is being parsed.
+    attr_reader :source
 
+    # The current line number of the parser.
+    attr_reader :lineno
+
+    # The current column number of the parser.
+    attr_reader :column
+
+    # Create a new RipperCompat object with the given source.
     def initialize(source)
       @source = source
       @result = nil
@@ -67,10 +75,12 @@ module Prism
     # Public interface
     ############################################################################
 
+    # True if the parser encountered an error during parsing.
     def error?
       result.errors.any?
     end
 
+    # Parse the source and return the result.
     def parse
       result.value.accept(self) unless error?
     end
@@ -79,10 +89,13 @@ module Prism
     # Visitor methods
     ############################################################################
 
+    # This method is responsible for dispatching to the correct visitor method
+    # based on the type of the node.
     def visit(node)
       node&.accept(self)
     end
 
+    # Visit a CallNode node.
     def visit_call_node(node)
       if !node.opening_loc && node.arguments.arguments.length == 1
         bounds(node.receiver.location)
@@ -97,11 +110,13 @@ module Prism
       end
     end
 
+    # Visit an IntegerNode node.
     def visit_integer_node(node)
       bounds(node.location)
       on_int(source[node.location.start_offset...node.location.end_offset])
     end
 
+    # Visit a StatementsNode node.
     def visit_statements_node(node)
       bounds(node.location)
       node.body.inject(on_stmts_new) do |stmts, stmt|
@@ -109,6 +124,7 @@ module Prism
       end
     end
 
+    # Visit a token found during parsing.
     def visit_token(node)
       bounds(node.location)
 
@@ -122,6 +138,7 @@ module Prism
       end
     end
 
+    # Visit a ProgramNode node.
     def visit_program_node(node)
       bounds(node.location)
       on_program(visit(node.statements))
@@ -155,17 +172,18 @@ module Prism
       @column = start_offset - (source.rindex("\n", start_offset) || 0)
     end
 
+    # Lazily initialize the parse result.
     def result
       @result ||= Prism.parse(source)
     end
 
-    def _dispatch0; end
-    def _dispatch1(_); end
-    def _dispatch2(_, _); end
-    def _dispatch3(_, _, _); end
-    def _dispatch4(_, _, _, _); end
-    def _dispatch5(_, _, _, _, _); end
-    def _dispatch7(_, _, _, _, _, _, _); end
+    def _dispatch0; end # :nodoc:
+    def _dispatch1(_); end # :nodoc:
+    def _dispatch2(_, _); end # :nodoc:
+    def _dispatch3(_, _, _); end # :nodoc:
+    def _dispatch4(_, _, _, _); end # :nodoc:
+    def _dispatch5(_, _, _, _, _); end # :nodoc:
+    def _dispatch7(_, _, _, _, _, _, _); end # :nodoc:
 
     (Ripper::SCANNER_EVENT_TABLE.merge(Ripper::PARSER_EVENT_TABLE)).each do |event, arity|
       alias_method :"on_#{event}", :"_dispatch#{arity}"