prism 0.15.1 → 0.17.0

data/lib/prism/node_ext.rb

@@ -3,6 +3,19 @@
 # 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 # :nodoc:
+    # Returns a numeric value that represents the flags that were used to create
+    # the regular expression.
+    def options
+      o = flags & (RegularExpressionFlags::IGNORE_CASE | RegularExpressionFlags::EXTENDED | RegularExpressionFlags::MULTI_LINE)
+      o |= Regexp::FIXEDENCODING if flags.anybits?(RegularExpressionFlags::EUC_JP | RegularExpressionFlags::WINDOWS_31J | RegularExpressionFlags::UTF_8)
+      o |= Regexp::NOENCODING if flags.anybits?(RegularExpressionFlags::ASCII_8BIT)
+      o
+    end
+  end
+
+  private_constant :RegularExpressionOptions
+
   class FloatNode < Node
     # Returns the value of the node as a Ruby Float.
     def value
@@ -24,15 +37,16 @@ module Prism
     end
   end
 
+  class InterpolatedMatchLastLineNode < Node
+    include RegularExpressionOptions
+  end
+
   class InterpolatedRegularExpressionNode < Node
-    # Returns a numeric value that represents the flags that were used to create
-    # the regular expression.
-    def options
-      o = flags & (RegularExpressionFlags::IGNORE_CASE | RegularExpressionFlags::EXTENDED | RegularExpressionFlags::MULTI_LINE)
-      o |= Regexp::FIXEDENCODING if flags.anybits?(RegularExpressionFlags::EUC_JP | RegularExpressionFlags::WINDOWS_31J | RegularExpressionFlags::UTF_8)
-      o |= Regexp::NOENCODING if flags.anybits?(RegularExpressionFlags::ASCII_8BIT)
-      o
-    end
+    include RegularExpressionOptions
+  end
+
+  class MatchLastLineNode < Node
+    include RegularExpressionOptions
   end
 
   class RationalNode < Node
@@ -43,14 +57,7 @@ module Prism
   end
 
   class RegularExpressionNode < Node
-    # Returns a numeric value that represents the flags that were used to create
-    # the regular expression.
-    def options
-      o = flags & (RegularExpressionFlags::IGNORE_CASE | RegularExpressionFlags::EXTENDED | RegularExpressionFlags::MULTI_LINE)
-      o |= Regexp::FIXEDENCODING if flags.anybits?(RegularExpressionFlags::EUC_JP | RegularExpressionFlags::WINDOWS_31J | RegularExpressionFlags::UTF_8)
-      o |= Regexp::NOENCODING if flags.anybits?(RegularExpressionFlags::ASCII_8BIT)
-      o
-    end
+    include RegularExpressionOptions
   end
 
   class ConstantReadNode < Node

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)