parser 2.0.0.pre8 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 784e6ea2b211d0e66b2c9b557ac575c2f7204444
-  data.tar.gz: 381fae65cbb0abd8400e382c8bf926221f74929f
+  metadata.gz: bf0b6a5c97a393fd82aae713e9a10d4aa2108a0f
+  data.tar.gz: cf126c874ffc8d2430ccec47583b9dfca2afc7a1
 SHA512:
-  metadata.gz: 720ec8f90cb16e1e38ddd02006afe4dda5ca2c9ccf31087a0906cafd406ba6865e57d5545be81f64dd17cc710c33d108e73476742475264147049d034c97c6c4
-  data.tar.gz: f0b89adbfa47c7ba825c9d54df1d32cb0c81dec28866caea61baebd77290eb860317f3e357c10f4953056b9b1339085d0b9f2bd418848de46053b961044479c0
+  metadata.gz: 07a91a9884e3f0a22010c7cf60089de7b4bd4e0285df85771b9f0b52317d3b6930ba6bea44fa57c4c168723a92a3ccf4602b354a9e9e55ed7461e1009fa8431b
+  data.tar.gz: c95ab5caef72d3c0f936def4dd0dcb28298fbc335c9558d9d642edcfb9398a7f2b6479983cd5406ca62512f07c864b1884f4d0269bb34fb7fe75182a5086984c

data/CHANGELOG.md

@@ -1,6 +1,20 @@
 Changelog
 =========
 
+v2.0.0 (2013-10-06)
+-------------------
+
+API modifications:
+ * Source::Rewriter: raise an exception if updates clobber each other. (Peter Zotov)
+ * Source::Range#inspect: use full class name. (Peter Zotov)
+ * lexer.rl: make EOF tokens actually pointing at EOF and zero-length. (Peter Zotov)
+ * Source::Range#column_range: raise RangeError if range spans >1 line. (Peter Zotov)
+ * Source::Comment::Associator: fix argument order. (Peter Zotov)
+
+Features implemented:
+ * Source::Comment: implement #inspect. (Peter Zotov)
+ * Backport Array#bsearch from Ruby 2.0. (Peter Zotov)
+
 v2.0.0.pre8 (2013-09-15)
 ------------------------
 

data/README.md

@@ -31,13 +31,14 @@ Parse a chunk of code:
 Access the AST's source map:
 
     p Parser::CurrentRuby.parse("2 + 2").loc
-    # #<Parser::Source::Map::Send:0x007fe0ca8a69b8
-    #   @begin=nil,
-    #   @end=nil,
-    #   @expression=#<Source::Range (string) 0...5>,
-    #   @selector=#<Source::Range (string) 2...3>>
-
-    p Parser::CurrentRuby.parse("2 + 2").loc.selector.to_source
+    # #<Parser::Source::Map::Send:0x007fe5a1ac2388 
+    #   @dot=nil, 
+    #   @begin=nil, 
+    #   @end=nil, 
+    #   @selector=#<Source::Range (string) 2...3>, 
+    #   @expression=#<Source::Range (string) 0...5>>
+
+    p Parser::CurrentRuby.parse("2 + 2").loc.selector.source
     # "+"
 
 Parse a chunk of code and display all diagnostics:

data/doc/AST_FORMAT.md

@@ -138,6 +138,8 @@ Format:
 (array (int 1) (int 2))
 
 "[1, 2]"
+ ^ begin
+      ^ end
  ~~~~~~ expression
 ~~~
 

data/lib/parser.rb

@@ -7,6 +7,10 @@ if RUBY_VERSION < '1.9'
   require 'parser/compatibility/ruby1_8'
 end
 
+if RUBY_VERSION < '2.0'
+  require 'parser/compatibility/ruby1_9'
+end
+
 ##
 # @api public
 #

data/lib/parser/base.rb

@@ -182,6 +182,7 @@ module Parser
     # Ruby source code.
     #
     # @see #parse
+    # @see Parser::Source::Comment#associate
     # @return [Array]
     #
     def parse_with_comments(source_buffer)
@@ -217,7 +218,7 @@ module Parser
 
     ##
     # @api private
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     #
     def in_def?
       @def_level > 0

data/lib/parser/builders/default.rb

@@ -17,7 +17,7 @@ module Parser
     #
     # Source maps are identical in both cases.
     #
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     attr_accessor :emit_file_line_as_literals
 
     ##

data/lib/parser/compatibility/ruby1_9.rb

@@ -0,0 +1,32 @@
+unless Array.method_defined? :bsearch
+  class Array
+    def bsearch
+      return to_enum(__method__) unless block_given?
+      from = 0
+      to   = size - 1
+      satisfied = nil
+      while from <= to
+        midpoint = (from + to).div(2)
+        result = yield(cur = self[midpoint])
+        case result
+        when Numeric
+          return cur if result == 0
+          result = result < 0
+        when true
+          satisfied = cur
+        when nil, false
+          # nothing to do
+        else
+          fail TypeError, "wrong argument type #{result.class} (must be numeric, true, false or nil)"
+        end
+
+        if result
+          to = midpoint - 1
+        else
+          from = midpoint + 1
+        end
+      end
+      satisfied
+    end
+  end
+end

data/lib/parser/diagnostic/engine.rb

@@ -25,11 +25,11 @@ module Parser
   # @!attribute [rw] all_errors_are_fatal
   #  When set to `true` any error that is encountered will result in
   #  {Parser::SyntaxError} being raised.
-  #  @return [TrueClass|FalseClass]
+  #  @return [Boolean]
   #
   # @!attribute [rw] ignore_warnings
   #  When set to `true` warnings will be ignored.
-  #  @return [TrueClass|FalseClass]
+  #  @return [Boolean]
   #
   class Diagnostic::Engine
     attr_accessor :consumer
@@ -79,7 +79,7 @@ module Parser
     # Checks whether `diagnostic` should be ignored.
     #
     # @param [Parser::Diagnostic] diagnostic
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     #
     def ignore?(diagnostic)
       @ignore_warnings &&
@@ -90,7 +90,7 @@ module Parser
     # Checks whether `diagnostic` should be raised as an exception.
     #
     # @param [Parser::Diagnostic] diagnostic
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     #
     def raise?(diagnostic)
       (@all_errors_are_fatal &&

data/lib/parser/lexer.rl

@@ -259,7 +259,7 @@ class Parser::Lexer
     elsif @cs == self.class.lex_error
       [ false, [ '$error', range(p - 1, p) ] ]
     else
-      [ false, [ '$eof',   range(p - 1, p) ] ]
+      [ false, [ '$eof',   range(p, p)     ] ]
     end
   end
 

data/lib/parser/rewriter.rb

@@ -1,4 +1,5 @@
 module Parser
+
   ##
   # {Parser::Rewriter} offers a basic API that makes it easy to rewrite
   # existing ASTs. It's built on top of {Parser::AST::Processor} and
@@ -7,6 +8,8 @@ module Parser
   # For example, assume you want to remove `do` tokens from a while statement.
   # You can do this as following:
   #
+  #     require 'parser/current'
+  #
   #     class RemoveDo < Parser::Rewriter
   #       def on_while(node)
   #         # Check if the statement starts with "do"
@@ -40,6 +43,9 @@ module Parser
   # Keep in mind that {Parser::Rewriter} does not take care of indentation when
   # inserting/replacing code so you'll have to do this yourself.
   #
+  # See also [a blog entry](http://whitequark.org/blog/2013/04/26/lets-play-with-ruby-code/)
+  # describing rewriters in greater detail.
+  #
   # @api public
   #
   class Rewriter < Parser::AST::Processor
@@ -59,14 +65,12 @@ module Parser
       @source_rewriter.process
     end
 
-    private
-
     ##
     # Returns `true` if the specified node is an assignment node, returns false
     # otherwise.
     #
     # @param [Parser::AST::Node] node
-    # @return [TrueClass|FalseClass]
+    # @return [Boolean]
     #
     def assignment?(node)
       [:lvasgn, :ivasgn, :gvasgn, :cvasgn, :casgn].include?(node.type)
@@ -111,4 +115,5 @@ module Parser
       @source_rewriter.replace(range, content)
     end
   end
+
 end

data/lib/parser/source/buffer.rb

@@ -1,14 +1,32 @@
-# encoding:ascii-8bit
+# encoding: ascii-8bit
 
 module Parser
   module Source
 
     ##
+    # A buffer with source code. {Buffer} contains the source code itself,
+    # associated location information (name and first line), and takes care
+    # of encoding.
+    #
+    # A source buffer is immutable once populated.
+    #
+    # @!attribute [r] name
+    #  Buffer name. If the buffer was created from a file, the name corresponds
+    #  to relative path to the file.
+    #  @return [String] buffer name
+    #
+    # @!attribute [r] first_line
+    #  First line of the buffer, 1 by default.
+    #  @return [Integer] first line
+    #
     # @api public
     #
     class Buffer
       attr_reader :name, :first_line
 
+      ##
+      # @api private
+      #
       ENCODING_RE =
         /\#.*coding\s*[:=]\s*
           (
@@ -22,6 +40,13 @@ module Parser
           )
         /x
 
+      ##
+      # Try to recognize encoding of `string` as Ruby would, i.e. by looking for
+      # magic encoding comment or UTF-8 BOM. `string` can be in any encoding.
+      #
+      # @param [String]  string
+      # @return [String|nil] encoding name, if recognized
+      #
       def self.recognize_encoding(string)
         return if string.empty?
 
@@ -44,20 +69,31 @@ module Parser
         end
       end
 
-      # Lexer expects UTF-8 input. This method processes the input
-      # in an arbitrary valid Ruby encoding and returns an UTF-8 encoded
-      # string.
+      ##
+      # Recognize encoding of `input` and process it so it could be lexed.
+      #
+      #  * If `input` does not contain BOM or magic encoding comment, it is
+      #    kept in the original encoding.
+      #  * If the detected encoding is binary, `input` is kept in binary.
+      #  * Otherwise, `input` is re-encoded into UTF-8 and returned as a
+      #    new string.
+      #
+      # This method mutates the encoding of `input`, but not its content.
       #
-      def self.reencode_string(string)
-        original_encoding = string.encoding
-        detected_encoding = recognize_encoding(string.force_encoding(Encoding::BINARY))
+      # @param  [String] input
+      # @return [String]
+      # @raise  [EncodingError]
+      #
+      def self.reencode_string(input)
+        original_encoding = input.encoding
+        detected_encoding = recognize_encoding(input.force_encoding(Encoding::BINARY))
 
         if detected_encoding.nil?
-          string.force_encoding(original_encoding)
+          input.force_encoding(original_encoding)
         elsif detected_encoding == Encoding::BINARY
-          string
+          input
         else
-          string.
+          input.
             force_encoding(detected_encoding).
             encode(Encoding::UTF_8)
         end
@@ -72,6 +108,15 @@ module Parser
         @line_begins = nil
       end
 
+      ##
+      # Populate this buffer from correspondingly named file.
+      #
+      # @example
+      #  Parser::Source::Buffer.new('foo/bar.rb').read
+      #
+      # @return [Buffer] self
+      # @raise  [ArgumentError] if already populated
+      #
       def read
         File.open(@name, 'rb') do |io|
           self.source = io.read
@@ -80,6 +125,12 @@ module Parser
         self
       end
 
+      ##
+      # Source code contained in this buffer.
+      #
+      # @return [String] source code
+      # @raise  [RuntimeError] if buffer is not populated yet
+      #
       def source
         if @source.nil?
           raise RuntimeError, 'Cannot extract source from uninitialized Source::Buffer'
@@ -88,41 +139,68 @@ module Parser
         @source
       end
 
-      def source=(source)
+      ##
+      # Populate this buffer from a string with encoding autodetection.
+      # `input` is mutated if not frozen.
+      #
+      # @param [String] input
+      # @raise [ArgumentError] if already populated
+      # @return [String]
+      #
+      def source=(input)
         if defined?(Encoding)
-          source = source.dup if source.frozen?
-          source = self.class.reencode_string(source)
+          input = input.dup if input.frozen?
+          input = self.class.reencode_string(input)
         end
 
-        self.raw_source = source
+        self.raw_source = input
       end
 
-      def raw_source=(source)
+      ##
+      # Populate this buffer from a string without encoding autodetection.
+      #
+      # @param [String] input
+      # @raise [ArgumentError] if already populated
+      # @return [String]
+      #
+      def raw_source=(input)
         if @source
           raise ArgumentError, 'Source::Buffer is immutable'
         end
 
-        @source = source.gsub(/\r\n/, "\n").freeze
+        @source = input.gsub(/\r\n/, "\n").freeze
       end
 
+      ##
+      # Convert a character index into the source to a `[line, column]` tuple.
+      #
+      # @param  [Integer] position
+      # @return [[Integer, Integer]] `[line, column]`
+      #
       def decompose_position(position)
         line_no, line_begin = line_for(position)
 
         [ @first_line + line_no, position - line_begin ]
       end
 
+      ##
+      # Extract line `lineno` from source, taking `first_line` into account.
+      #
+      # @param  [Integer] lineno
+      # @return [String]
+      # @raise  [IndexError] if `lineno` is out of bounds
+      #
       def source_line(lineno)
         unless @lines
           @lines = @source.lines.to_a
           @lines.each { |line| line.gsub!(/\n$/, '') }
 
-          # Lexer has an "infinite stream of EOF symbols" after the
-          # actual EOF, so in some cases (e.g. EOF token of ruby-parse -E)
-          # tokens will refer to one line past EOF.
+          # If a file ends with a newline, the EOF token will appear
+          # to be one line further than the end of file.
           @lines << ""
         end
 
-        @lines[lineno - @first_line].dup
+        @lines.fetch(lineno - @first_line).dup
       end
 
       private

data/lib/parser/source/comment.rb

@@ -2,13 +2,16 @@ module Parser
   module Source
 
     ##
-    # @api public
+    # A comment in the source code.
     #
     # @!attribute [r] text
-    #  @return String
+    #  @return [String]
     #
     # @!attribute [r] location
-    #  @return Parser::Source::Map
+    #  @return [Parser::Source::Map]
+    #
+    # @api public
+    #
     class Comment
       attr_reader  :text
 
@@ -16,14 +19,22 @@ module Parser
       alias_method :loc, :location
 
       ##
+      # Associate `comments` with `ast` nodes by their location in the
+      # source.
+      #
+      # @param [Parser::AST::Node] ast
+      # @param [Array(Comment)]    comments
+      # @return [Hash(Parser::AST::Node, Array(Comment))]
       # @see Parser::Source::Comment::Associator
+      #
       def self.associate(ast, comments)
-        associator = Associator.new(comments, ast)
+        associator = Associator.new(ast, comments)
         associator.associate
       end
 
       ##
       # @param [Parser::Source::Range] range
+      #
       def initialize(range)
         @location = Parser::Source::Map.new(range)
         @text     = range.source.freeze
@@ -32,7 +43,7 @@ module Parser
       end
 
       ##
-      # Returns the type of this comment.
+      # Type of this comment.
       #
       #   * Inline comments correspond to `:inline`:
       #
@@ -43,6 +54,9 @@ module Parser
       #         =begin
       #         hi i am a document
       #         =end
+      #
+      # @return [Symbol]
+      #
       def type
         case text
         when /^#/
@@ -53,28 +67,39 @@ module Parser
       end
 
       ##
-      # @see [#type]
-      # @return [TrueClass|FalseClass]
+      # @see #type
+      # @return [Boolean] true if this is an inline comment.
+      #
       def inline?
         type == :inline
       end
 
       ##
-      # @see [#type]
-      # @return [TrueClass|FalseClass]
+      # @see #type
+      # @return [Boolean] true if this is a block comment.
+      #
       def document?
         type == :document
       end
 
       ##
-      # Compares comments. Two comments are identical if they
+      # Compares comments. Two comments are equal if they
       # correspond to the same source range.
+      #
       # @param [Object] other
-      # @return [TrueClass|FalseClass]
+      # @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

data/lib/parser/source/comment/associator.rb

@@ -2,26 +2,82 @@ module Parser
   module Source
 
     ##
+    # A processor which associates AST nodes with comments based on their
+    # location in source code. It may be used, for example, to implement
+    # rdoc-style processing.
+    #
+    # @example
+    #   require 'parser/current'
+    #
+    #   ast, comments = Parser::CurrentRuby.parse_with_comments(<<-CODE)
+    #   # Class stuff
+    #   class Foo
+    #     # Attr stuff
+    #     # @see bar
+    #     attr_accessor :foo
+    #   end
+    #   CODE
+    #
+    #   p Parser::Source::Comment.associate(ast, comments)
+    #   # => {
+    #   #   (class (const nil :Foo) ...) =>
+    #   #     [#<Parser::Source::Comment (string):1:1 "# Class stuff">],
+    #   #   (send nil :attr_accessor (sym :foo)) =>
+    #   #     [#<Parser::Source::Comment (string):3:3 "# Attr stuff">,
+    #   #      #<Parser::Source::Comment (string):4:3 "# @see bar">]
+    #   # }
+    #
+    # @see #associate
     #
     # @!attribute skip_directives
-    #  Skip file processing directives disguised as comments,
-    #  namely:
+    #  Skip file processing directives disguised as comments.
+    #  Namely:
     #
     #    * Shebang line,
     #    * Magic encoding comment.
     #
+    #  @return [Boolean]
+    #
     # @api public
     #
     class Comment::Associator
       attr_accessor :skip_directives
 
-      def initialize(comments, ast)
-        @comments    = comments
+      ##
+      # @param [Parser::AST::Node] ast
+      # @param [Array(Parser::Source::Comment)] comments
+      def initialize(ast, comments)
         @ast         = ast
+        @comments    = comments
 
         @skip_directives = true
       end
 
+      ##
+      # Compute a mapping between AST nodes and comments.
+      #
+      # A comment belongs to a certain node if it begins after end
+      # of the previous node (if one exists) and ends before beginning of
+      # the current node.
+      #
+      # This rule is unambiguous and produces the result
+      # one could reasonably expect; for example, this code
+      #
+      #     # foo
+      #     hoge # bar
+      #       + fuga
+      #
+      # will result in the following association:
+      #
+      #     {
+      #       (send (lvar :hoge) :+ (lvar :fuga)) =>
+      #         [#<Parser::Source::Comment (string):2:1 "# foo">],
+      #       (lvar :fuga) =>
+      #         [#<Parser::Source::Comment (string):3:8 "# bar">]
+      #     }
+      #
+      # @return [Hash(Parser::AST::Node, Array(Parser::Source::Comment))]
+      #
       def associate
         @mapping     = Hash.new { |h, k| h[k] = [] }
         @comment_num = 0

data/lib/parser/source/map.rb

@@ -2,29 +2,99 @@ 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.
+    #
+    # 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] expression
+    #  @return [Range]
+    #
     # @api public
     #
     class Map
       attr_reader :expression
 
+      ##
+      # @param [Range] expression
       def initialize(expression)
         @expression = expression
 
         freeze
       end
 
+      ##
+      # A shortcut for `self.expression.line`.
+      # @return [Integer]
+      #
       def line
         @expression.line
       end
 
+      ##
+      # A shortcut for `self.expression.column`.
+      # @return [Integer]
+      #
       def column
         @expression.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|
@@ -33,6 +103,24 @@ module Parser
           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
         Hash[instance_variables.map do |ivar|
           [ ivar[1..-1].to_sym, instance_variable_get(ivar) ]

data/lib/parser/source/map/constant.rb

@@ -12,6 +12,9 @@ module Parser
         super(expression)
       end
 
+      ##
+      # @api private
+      #
       def with_operator(operator_l)
         with { |map| map.update_operator(operator_l) }
       end

data/lib/parser/source/map/send.rb

@@ -16,6 +16,9 @@ module Parser
         super(expression_l)
       end
 
+      ##
+      # @api private
+      #
       def with_operator(operator_l)
         with { |map| map.update_operator(operator_l) }
       end

data/lib/parser/source/map/variable.rb

@@ -11,6 +11,9 @@ module Parser
         super(expression_l)
       end
 
+      ##
+      # @api private
+      #
       def with_operator(operator_l)
         with { |map| map.update_operator(operator_l) }
       end

data/lib/parser/source/range.rb

@@ -2,12 +2,34 @@ module Parser
   module Source
 
     ##
+    # A range of characters in a particular source buffer.
+    #
+    # The range is always exclusive, i.e. a range with `begin_pos` of 3 and
+    # `end_pos` of 5 will contain the following characters:
+    #
+    #     example
+    #        ^^
+    #
+    # @!attribute [r] source_buffer
+    #  @return [Parser::Diagnostic::Engine]
+    #
+    # @!attribute [r] begin_pos
+    #  @return [Integer] index of the first character in the range
+    #
+    # @!attribute [r] end_pos
+    #  @return [Integer] index of the character after the last character in the range
+    #
     # @api public
     #
     class Range
       attr_reader :source_buffer
       attr_reader :begin_pos, :end_pos
 
+      ##
+      # @param [Buffer]  source_buffer
+      # @param [Integer] begin_pos
+      # @param [Integer] end_pos
+      #
       def initialize(source_buffer, begin_pos, end_pos)
         @source_buffer       = source_buffer
         @begin_pos, @end_pos = begin_pos, end_pos
@@ -15,68 +37,137 @@ module Parser
         freeze
       end
 
+      ##
+      # @return [Range] a zero-length range located just before the beginning
+      #   of this range.
+      #
       def begin
         Range.new(@source_buffer, @begin_pos, @begin_pos)
       end
 
+      ##
+      # @return [Range] a zero-length range located just after the end
+      #   of this range.
+      #
       def end
         Range.new(@source_buffer, @end_pos, @end_pos)
       end
 
+      ##
+      # @return [Integer] amount of characters included in this range.
+      #
       def size
         @end_pos - @begin_pos
       end
 
       alias length size
 
+      ##
+      # Line number of the beginning of this range. By default, the first line
+      # of a buffer is 1; as such, line numbers are most commonly one-based.
+      #
+      # @see Buffer
+      # @return [Integer] line number of the beginning of this range.
+      #
       def line
         line, _ = @source_buffer.decompose_position(@begin_pos)
 
         line
       end
 
+      ##
+      # @return [Integer] zero-based column number of the beginning of this range.
+      #
       def column
         _, column = @source_buffer.decompose_position(@begin_pos)
 
         column
       end
 
+      ##
+      # @return [::Range] a range of columns spanned by this range.
+      # @raise RangeError
+      #
       def column_range
+        if self.begin.line != self.end.line
+          raise RangeError, "#{self.inspect} spans more than one line"
+        end
+
         self.begin.column...self.end.column
       end
 
+      ##
+      # @return [String] a line of source code containing the beginning of this range.
+      #
       def source_line
         @source_buffer.source_line(line)
       end
 
+      ##
+      # @return [String] all source code covered by this range.
+      #
       def source
         @source_buffer.source[self.begin_pos...self.end_pos]
       end
 
+      ##
+      # `is?` provides a concise way to compare the source corresponding to this range.
+      # For example, `r.source == '(' || r.source == 'begin'` is equivalent to
+      # `r.is?('(', 'begin')`.
+      #
       def is?(*what)
         what.include?(source)
       end
 
+      ##
+      # @return [Array(Integer)] a set of character indexes contained in this range.
+      #
       def to_a
         (@begin_pos...@end_pos).to_a
       end
 
+      ##
+      # Composes a GNU/Clang-style string representation of the beginning of this
+      # range.
+      #
+      # For example, for the following range in file `foo.rb`,
+      #
+      #     def foo
+      #         ^^^
+      #
+      # `to_s` will return `foo.rb:1:5`.
+      # Note that the column index is one-based.
+      #
+      # @return [String]
+      #
       def to_s
         line, column = @source_buffer.decompose_position(@begin_pos)
 
         [@source_buffer.name, line, column + 1].join(':')
       end
 
+      ##
+      # @param [Integer] new_size
+      # @return [Range] a range beginning at the same point as this range and length `new_size`.
+      #
       def resize(new_size)
         Range.new(@source_buffer, @begin_pos, @begin_pos + new_size)
       end
 
+      ##
+      # @param [Range] other
+      # @return [Range] smallest possible range spanning both this range and `other`.
+      #
       def join(other)
         Range.new(@source_buffer,
             [@begin_pos, other.begin_pos].min,
             [@end_pos,   other.end_pos].max)
       end
 
+      ##
+      # Compares ranges.
+      # @return [Boolean]
+      #
       def ==(other)
         other.is_a?(Range) &&
           @source_buffer == other.source_buffer &&
@@ -84,8 +175,11 @@ module Parser
           @end_pos       == other.end_pos
       end
 
+      ##
+      # @return [String] a human-readable representation of this range.
+      #
       def inspect
-        "#<Source::Range #{@source_buffer.name} #{@begin_pos}...#{@end_pos}>"
+        "#<Parser::Source::Range #{@source_buffer.name} #{@begin_pos}...#{@end_pos}>"
       end
     end
 

data/lib/parser/source/rewriter.rb

@@ -2,11 +2,32 @@ module Parser
   module Source
 
     ##
+    # {Rewriter} performs the heavy lifting in the source rewriting process.
+    # It schedules code updates to be performed in the correct order and
+    # verifies that no two updates _clobber_ each other, that is, attempt to
+    # modify the same part of code.
+    #
+    # If it is detected that one update clobbers another one, an `:error` and
+    # a `:note` diagnostics describing both updates are generated and passed to
+    # the diagnostic engine. After that, an exception is raised.
+    #
+    # The default diagnostic engine consumer simply prints the diagnostics to `stderr`.
+    #
+    # @!attribute [r] source_buffer
+    #  @return [Source::Buffer]
+    #
+    # @!attribute [r] diagnostics
+    #  @return [Diagnostic::Engine]
+    #
     # @api public
     #
     class Rewriter
-      attr_accessor :diagnostics
+      attr_reader :source_buffer
+      attr_reader :diagnostics
 
+      ##
+      # @param [Source::Buffer] source_buffer
+      #
       def initialize(source_buffer)
         @diagnostics = Diagnostic::Engine.new
         @diagnostics.consumer = lambda do |diag|
@@ -18,28 +39,67 @@ module Parser
         @clobber       = 0
       end
 
+      ##
+      # Removes the source range.
+      #
+      # @param [Range] range
+      # @return [Rewriter] self
+      # @raise [RuntimeError] when clobbering is detected
+      #
       def remove(range)
         append Rewriter::Action.new(range, '')
       end
 
+      ##
+      # Inserts new code before the given source range.
+      #
+      # @param [Range] range
+      # @param [String] content
+      # @return [Rewriter] self
+      # @raise [RuntimeError] when clobbering is detected
+      #
       def insert_before(range, content)
         append Rewriter::Action.new(range.begin, content)
       end
 
+      ##
+      # Inserts new code after the given source range.
+      #
+      # @param [Range] range
+      # @param [String] content
+      # @return [Rewriter] self
+      # @raise [RuntimeError] when clobbering is detected
+      #
       def insert_after(range, content)
         append Rewriter::Action.new(range.end, content)
       end
 
+      ##
+      # Replaces the code of the source range `range` with `content`.
+      #
+      # @param [Range] range
+      # @param [String] content
+      # @return [Rewriter] self
+      # @raise [RuntimeError] when clobbering is detected
+      #
       def replace(range, content)
         append Rewriter::Action.new(range, content)
       end
 
+      ##
+      # Applies all scheduled changes to the `source_buffer` and returns
+      # modified source as a new string.
+      #
+      # @return [String]
+      #
       def process
-        adjustment   = 0
-        source       = @source_buffer.source.dup
+        adjustment = 0
+        source     = @source_buffer.source.dup
+
         sorted_queue = @queue.sort_by.with_index do |action, index|
           [action.range.begin_pos, index]
         end
+
         sorted_queue.each do |action|
           begin_pos = action.range.begin_pos + adjustment
           end_pos   = begin_pos + action.range.length
@@ -67,6 +127,8 @@ module Parser
                                       "clobbered by: #{clobber_action}",
                                       clobber_action.range)
           @diagnostics.process(diagnostic)
+
+          raise RuntimeError, "Parser::Source::Rewriter detected clobbering"
         else
           clobber(action.range)
 

data/lib/parser/version.rb

@@ -1,3 +1,3 @@
 module Parser
-  VERSION = '2.0.0.pre8'
+  VERSION = '2.0.0'
 end

data/parser.gemspec

@@ -35,7 +35,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'simplecov', '~> 0.7'
   spec.add_development_dependency 'coveralls'
   spec.add_development_dependency 'json_pure' # for coveralls on 1.9.2
-  spec.add_development_dependency 'cliver' # executable version detection
+  spec.add_development_dependency 'cliver',    '~> 0.2.2' # executable version detection
 
   spec.add_development_dependency 'simplecov-sublime-ruby-coverage'
 

data/test/test_source_rewriter.rb

@@ -74,9 +74,11 @@ class TestSourceRewriter < Minitest::Test
       diagnostics << diag
     end
 
-    @rewriter.
-      replace(range(3, 1), '---').
-      remove(range(3, 1))
+    assert_raises RuntimeError, /clobber/ do
+      @rewriter.
+        replace(range(3, 1), '---').
+        remove(range(3, 1))
+    end
 
     assert_equal 2, diagnostics.count
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parser
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre8
+  version: 2.0.0
 platform: ruby
 authors:
 - Peter Zotov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-15 00:00:00.000000000 Z
+date: 2013-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ast
@@ -146,16 +146,16 @@ dependencies:
   name: cliver
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.2.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.2.2
 - !ruby/object:Gem::Dependency
   name: simplecov-sublime-ruby-coverage
   requirement: !ruby/object:Gem::Requirement
@@ -246,6 +246,7 @@ files:
 - lib/parser/base.rb
 - lib/parser/builders/default.rb
 - lib/parser/compatibility/ruby1_8.rb
+- lib/parser/compatibility/ruby1_9.rb
 - lib/parser/current.rb
 - lib/parser/diagnostic.rb
 - lib/parser/diagnostic/engine.rb
@@ -321,9 +322,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>'
+  - - '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.0.0