Class Parser::Source::Rewriter
In: lib/parser/source/rewriter.rb
Parent: Object

{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 section of code. (However, if two updates modify the same section in exactly the same way, they are merged.)

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

Methods

insert_after   insert_after_multi   insert_before   insert_before_multi   new   process   remove   replace   transaction  

Attributes

diagnostics  [R] 
source_buffer  [R] 

Public Class methods

new(source_buffer)

@param [Source::Buffer] source_buffer

Public Instance methods

insert_after(range, content)

Inserts new code after the given source range.

@param [Range] range @param [String] content @return [Rewriter] self @raise [ClobberingError] when clobbering is detected

insert_after_multi(range, content)

Inserts new code after the given source range by allowing other insertions at the same position. Note that an insertion with latter invocation comes after earlier insertion at the same position in the rewritten source.

@example Inserting ’)]’ 

  rewriter.
    insert_after_multi(range, ')').
    insert_after_multi(range, ']').
    process

@param [Range] range @param [String] content @return [Rewriter] self @raise [ClobberingError] when clobbering is detected

insert_before(range, content)

Inserts new code before the given source range.

@param [Range] range @param [String] content @return [Rewriter] self @raise [ClobberingError] when clobbering is detected

insert_before_multi(range, content)

Inserts new code before the given source range by allowing other insertions at the same position. Note that an insertion with latter invocation comes before earlier insertion at the same position in the rewritten source.

@example Inserting ’[(‘ 

  rewriter.
    insert_before_multi(range, '(').
    insert_before_multi(range, '[').
    process

@param [Range] range @param [String] content @return [Rewriter] self @raise [ClobberingError] when clobbering is detected

process()

Applies all scheduled changes to the `source_buffer` and returns modified source as a new string.

@return [String]

remove(range)

Removes the source range.

@param [Range] range @return [Rewriter] self @raise [ClobberingError] when clobbering is detected

replace(range, content)

Replaces the code of the source range `range` with `content`.

@param [Range] range @param [String] content @return [Rewriter] self @raise [ClobberingError] when clobbering is detected

transaction() {|| ...}

Provides a protected block where a sequence of multiple rewrite actions are handled atomically. If any of the actions failed by clobbering, all the actions are rolled back.

@example 

 begin
   rewriter.transaction do
     rewriter.insert_before(range_of_something, '(')
     rewriter.insert_after(range_of_something, ')')
   end
 rescue Parser::ClobberingError
 end

@raise [RuntimeError] when no block is passed @raise [RuntimeError] when already in a transaction

[Validate]