prism 0.16.0 → 0.17.0

data/lib/prism/node_ext.rb

@@ -3,7 +3,7 @@
 # Here we are reopening the prism module to provide methods on nodes that aren't
 # templated and are meant as convenience methods.
 module Prism
-  module RegularExpressionOptions
+  module RegularExpressionOptions # :nodoc:
     # Returns a numeric value that represents the flags that were used to create
     # the regular expression.
     def options

data/lib/prism/node_inspector.rb

@@ -3,7 +3,7 @@
 module Prism
   # This object is responsible for generating the output for the inspect method
   # implementations of child nodes.
-  class NodeInspector
+  class NodeInspector # :nodoc:
     attr_reader :prefix, :output
 
     def initialize(prefix = "")

data/lib/prism/pack.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Prism
+  # A parser for the pack template language.
   module Pack
     %i[
       SPACE
@@ -54,9 +55,36 @@ module Prism
       const_set(const, const)
     end
 
+    # A directive in the pack template language.
     class Directive
-      attr_reader :version, :variant, :source, :type, :signed, :endian, :size, :length_type, :length
+      # A symbol representing the version of Ruby.
+      attr_reader :version
 
+      # A symbol representing whether or not we are packing or unpacking.
+      attr_reader :variant
+
+      # A byteslice of the source string that this directive represents.
+      attr_reader :source
+
+      # The type of the directive.
+      attr_reader :type
+
+      # The type of signedness of the directive.
+      attr_reader :signed
+
+      # The type of endianness of the directive.
+      attr_reader :endian
+
+      # The size of the directive.
+      attr_reader :size
+
+      # The length type of this directive (used for integers).
+      attr_reader :length_type
+
+      # The length of this directive (used for integers).
+      attr_reader :length
+
+      # Initialize a new directive with the given values.
       def initialize(version, variant, source, type, signed, endian, size, length_type, length)
         @version = version
         @variant = variant
@@ -69,38 +97,42 @@ module Prism
         @length = length
       end
 
+      # The descriptions of the various types of endianness.
       ENDIAN_DESCRIPTIONS = {
-        AGNOSTIC_ENDIAN: 'agnostic',
-        LITTLE_ENDIAN: 'little-endian (VAX)',
-        BIG_ENDIAN: 'big-endian (network)',
-        NATIVE_ENDIAN: 'native-endian',
-        ENDIAN_NA: 'n/a'
+        AGNOSTIC_ENDIAN: "agnostic",
+        LITTLE_ENDIAN: "little-endian (VAX)",
+        BIG_ENDIAN: "big-endian (network)",
+        NATIVE_ENDIAN: "native-endian",
+        ENDIAN_NA: "n/a"
       }
 
+      # The descriptions of the various types of signedness.
       SIGNED_DESCRIPTIONS = {
-        UNSIGNED: 'unsigned',
-        SIGNED: 'signed',
-        SIGNED_NA: 'n/a'
+        UNSIGNED: "unsigned",
+        SIGNED: "signed",
+        SIGNED_NA: "n/a"
       }
 
+      # The descriptions of the various types of sizes.
       SIZE_DESCRIPTIONS = {
-        SIZE_SHORT: 'short',
-        SIZE_INT: 'int-width',
-        SIZE_LONG: 'long',
-        SIZE_LONG_LONG: 'long long',
-        SIZE_8: '8-bit',
-        SIZE_16: '16-bit',
-        SIZE_32: '32-bit',
-        SIZE_64: '64-bit',
-        SIZE_P: 'pointer-width'
+        SIZE_SHORT: "short",
+        SIZE_INT: "int-width",
+        SIZE_LONG: "long",
+        SIZE_LONG_LONG: "long long",
+        SIZE_8: "8-bit",
+        SIZE_16: "16-bit",
+        SIZE_32: "32-bit",
+        SIZE_64: "64-bit",
+        SIZE_P: "pointer-width"
       }
 
+      # Provide a human-readable description of the directive.
       def describe
         case type
         when SPACE
-          'whitespace'
+          "whitespace"
         when COMMENT
-          'comment'
+          "comment"
         when INTEGER
           if size == SIZE_8
             base = "#{SIGNED_DESCRIPTIONS[signed]} #{SIZE_DESCRIPTIONS[size]} integer"
@@ -115,58 +147,65 @@ module Prism
               base
             end
           when LENGTH_MAX
-            base + ', as many as possible'
+            base + ", as many as possible"
           end
         when UTF8
-          'UTF-8 character'
+          "UTF-8 character"
         when BER
-          'BER-compressed integer'
+          "BER-compressed integer"
         when FLOAT
           "#{SIZE_DESCRIPTIONS[size]} #{ENDIAN_DESCRIPTIONS[endian]} float"
         when STRING_SPACE_PADDED
-          'arbitrary binary string (space padded)'
+          "arbitrary binary string (space padded)"
         when STRING_NULL_PADDED
-          'arbitrary binary string (null padded, count is width)'
+          "arbitrary binary string (null padded, count is width)"
         when STRING_NULL_TERMINATED
-          'arbitrary binary string (null padded, count is width), except that null is added with *'
+          "arbitrary binary string (null padded, count is width), except that null is added with *"
         when STRING_MSB
-          'bit string (MSB first)'
+          "bit string (MSB first)"
         when STRING_LSB
-          'bit string (LSB first)'
+          "bit string (LSB first)"
         when STRING_HEX_HIGH
-          'hex string (high nibble first)'
+          "hex string (high nibble first)"
         when STRING_HEX_LOW
-          'hex string (low nibble first)'
+          "hex string (low nibble first)"
         when STRING_UU
-          'UU-encoded string'
+          "UU-encoded string"
         when STRING_MIME
-          'quoted printable, MIME encoding'
+          "quoted printable, MIME encoding"
         when STRING_BASE64
-          'base64 encoded string'
+          "base64 encoded string"
         when STRING_FIXED
-          'pointer to a structure (fixed-length string)'
+          "pointer to a structure (fixed-length string)"
         when STRING_POINTER
-          'pointer to a null-terminated string'
+          "pointer to a null-terminated string"
         when MOVE
-          'move to absolute position'
+          "move to absolute position"
         when BACK
-          'back up a byte'
+          "back up a byte"
         when NULL
-          'null byte'
+          "null byte"
         else
           raise
         end
       end
     end
 
+    # The result of parsing a pack template.
     class Format
-      attr_reader :directives, :encoding
+      # A list of the directives in the template.
+      attr_reader :directives
+
+      # The encoding of the template.
+      attr_reader :encoding
 
+      # Create a new Format with the given directives and encoding.
       def initialize(directives, encoding)
         @directives = directives
         @encoding = encoding
       end
 
+      # Provide a human-readable description of the format.
       def describe
         source_width = directives.map { |d| d.source.inspect.length }.max
         directive_lines = directives.map do |directive|
@@ -178,7 +217,7 @@ module Prism
           "  #{source.ljust(source_width)}  #{directive.describe}"
         end
 
-        (['Directives:'] + directive_lines + ['Encoding:', "  #{encoding}"]).join("\n")
+        (["Directives:"] + directive_lines + ["Encoding:", "  #{encoding}"]).join("\n")
       end
     end
   end

data/lib/prism/parse_result/comments.rb

@@ -19,7 +19,7 @@ module Prism
     class Comments
       # A target for attaching comments that is based on a specific node's
       # location.
-      class NodeTarget
+      class NodeTarget # :nodoc:
         attr_reader :node
 
         def initialize(node)
@@ -46,7 +46,7 @@ module Prism
 
       # A target for attaching comments that is based on a location field on a
       # node. For example, the `end` token of a ClassNode.
-      class LocationTarget
+      class LocationTarget # :nodoc:
         attr_reader :location
 
         def initialize(location)
@@ -70,12 +70,17 @@ module Prism
         end
       end
 
+      # The parse result that we are attaching comments to.
       attr_reader :parse_result
 
+      # Create a new Comments object that will attach comments to the given
+      # parse result.
       def initialize(parse_result)
         @parse_result = parse_result
       end
 
+      # Attach the comments to their respective locations in the tree by
+      # mutating the parse result.
       def attach!
         parse_result.comments.each do |comment|
           preceding, enclosing, following = nearest_targets(parse_result.value, comment)

data/lib/prism/parse_result/newlines.rb

@@ -18,10 +18,12 @@ module Prism
     # MarkNewlinesVisitor, since that visitor is responsible for marking the
     # newlines for JRuby/TruffleRuby.
     class Newlines < Visitor
+      # Create a new Newlines visitor with the given newline offsets.
       def initialize(newline_marked)
         @newline_marked = newline_marked
       end
 
+      # Permit block/lambda nodes to mark newlines within themselves.
       def visit_block_node(node)
         old_newline_marked = @newline_marked
         @newline_marked = Array.new(old_newline_marked.size, false)
@@ -35,6 +37,7 @@ module Prism
 
       alias_method :visit_lambda_node, :visit_block_node
 
+      # Mark if/unless nodes as newlines.
       def visit_if_node(node)
         node.set_newline_flag(@newline_marked)
         super(node)
@@ -42,6 +45,7 @@ module Prism
 
       alias_method :visit_unless_node, :visit_if_node
 
+      # Permit statements lists to mark newlines within themselves.
       def visit_statements_node(node)
         node.body.each do |child|
           child.set_newline_flag(@newline_marked)

data/lib/prism/parse_result.rb

@@ -5,20 +5,52 @@ 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
-    # offset.
+    # byte offset.
     def line(value)
+      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[find_line(value)]
+    end
+
+    # Return the column number for the given byte offset.
+    def column(value)
+      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
 
@@ -36,16 +68,8 @@ module Prism
       left - 1
     end
 
-    def line_offset(value)
-      offsets[line(value)]
-    end
-
-    def column(value)
-      value - offsets[line(value)]
-    end
-
-    private
-
+    # 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) }
@@ -69,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
@@ -102,7 +128,7 @@ module Prism
 
     # The line number where this location starts.
     def start_line
-      source.line(start_offset) + 1
+      source.line(start_offset)
     end
 
     # The content of the line where this location starts before this location.
@@ -113,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
@@ -128,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 &&
@@ -152,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
 
-    # Returns true if the comment happens on the same line as other code and false if the comment is by itself
+    # This can only be true for inline comments.
     def trailing?
-      type == :inline && !location.start_line_slice.strip.empty?
+      false
     end
+  end
+
+  # 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?
+      !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::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::Comment @type=#{@type.inspect} @location=#{@location.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
@@ -210,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
@@ -228,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
@@ -248,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
@@ -259,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
@@ -274,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)
@@ -300,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?