Method: Parser::Source::TreeRewriter#diagnostics

Defined in:: lib/parser/source/tree_rewriter.rb,
lib/parser/source/tree_rewriter.rb
#diagnostics ⇒ `Diagnostic::Engine` (readonly)

Returns:
(Diagnostic::Engine)
# File 'lib/parser/source/tree_rewriter.rb', line 91

class TreeRewriter
  attr_reader :source_buffer
  attr_reader :diagnostics

  ##
  # @param [Source::Buffer] source_buffer
  #
  def initialize(source_buffer,
                 crossing_deletions: :accept,
                 different_replacements: :accept,
                 swallowed_insertions: :accept)
    @diagnostics = Diagnostic::Engine.new
    @diagnostics.consumer = -> diag { $stderr.puts diag.render }

    @source_buffer = source_buffer
    @in_transaction = false

    @policy = {crossing_deletions: crossing_deletions,
               different_replacements: different_replacements,
               swallowed_insertions: swallowed_insertions}.freeze
    check_policy_validity

    @enforcer = method(:enforce_policy)
    # We need a range that would be jugded as containing all other ranges,
    # including 0...0 and size...size:
    all_encompassing_range = @source_buffer.source_range.adjust(begin_pos: -1, end_pos: +1)
    @action_root = TreeRewriter::Action.new(all_encompassing_range, @enforcer)
  end

  ##
  # Returns true iff no (non trivial) update has been recorded
  #
  # @return [Boolean]
  #
  def empty?
    @action_root.empty?
  end

  ##
  # Merges the updates of argument with the receiver.
  # Policies of the receiver are used.
  # This action is atomic in that it won't change the receiver
  # unless it succeeds.
  #
  # @param [Rewriter] with
  # @return [Rewriter] self
  # @raise [ClobberingError] when clobbering is detected
  #
  def merge!(with)
    raise 'TreeRewriter are not for the same source_buffer' unless
      source_buffer == with.source_buffer

    @action_root = @action_root.combine(with.action_root)
    self
  end

  ##
  # Returns a new rewriter that consists of the updates of the received
  # and the given argument. Policies of the receiver are used.
  #
  # @param [Rewriter] with
  # @return [Rewriter] merge of receiver and argument
  # @raise [ClobberingError] when clobbering is detected
  #
  def merge(with)
    dup.merge!(with)
  end

  ##
  # For special cases where one needs to merge a rewriter attached to a different source_buffer
  # or that needs to be offset. Policies of the receiver are used.
  #
  # @param [TreeRewriter] rewriter from different source_buffer
  # @param [Integer] offset
  # @return [Rewriter] self
  # @raise [IndexError] if action ranges (once offset) don't fit the current buffer
  #
  def import!(foreign_rewriter, offset: 0)
    return self if foreign_rewriter.empty?

    contracted = foreign_rewriter.action_root.contract
    merge_effective_range = ::Parser::Source::Range.new(
      @source_buffer,
      contracted.range.begin_pos + offset,
      contracted.range.end_pos + offset,
    )
    check_range_validity(merge_effective_range)

    merge_with = contracted.moved(@source_buffer, offset)

    @action_root = @action_root.combine(merge_with)
    self
  end

  ##
  # 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
  #
  def replace(range, content)
    combine(range, replacement: content)
  end

  ##
  # Inserts the given strings before and after the given range.
  #
  # @param [Range] range
  # @param [String, nil] insert_before
  # @param [String, nil] insert_after
  # @return [Rewriter] self
  # @raise [ClobberingError] when clobbering is detected
  #
  def wrap(range, insert_before, insert_after)
    combine(range, insert_before: insert_before.to_s, insert_after: insert_after.to_s)
  end

  ##
  # Shortcut for `replace(range, '')`
  #
  # @param [Range] range
  # @return [Rewriter] self
  # @raise [ClobberingError] when clobbering is detected
  #
  def remove(range)
    replace(range, ''.freeze)
  end


  ##
  # Shortcut for `wrap(range, content, nil)`
  #
  # @param [Range] range
  # @param [String] content
  # @return [Rewriter] self
  # @raise [ClobberingError] when clobbering is detected
  #
  def insert_before(range, content)
    wrap(range, content, nil)
  end

  ##
  # Shortcut for `wrap(range, nil, content)`
  #
  # @param [Range] range
  # @param [String] content
  # @return [Rewriter] self
  # @raise [ClobberingError] when clobbering is detected
  #
  def insert_after(range, content)
    wrap(range, nil, content)
  end

  ##
  # Applies all scheduled changes to the `source_buffer` and returns
  # modified source as a new string.
  #
  # @return [String]
  #
  def process
    source     = @source_buffer.source

    chunks = []
    last_end = 0
    @action_root.ordered_replacements.each do |range, replacement|
      chunks << source[last_end...range.begin_pos] << replacement
      last_end = range.end_pos
    end
    chunks << source[last_end...source.length]
    chunks.join
  end

  ##
  # Returns a representation of the rewriter as an ordered list of replacements.
  #
  #     rewriter.as_replacements # => [ [1...1, '('],
  #                                     [2...4, 'foo'],
  #                                     [5...6, ''],
  #                                     [6...6, '!'],
  #                                     [10...10, ')'],
  #                                   ]
  #
  # This representation is sufficient to recreate the result of `process` but it is
  # not sufficient to recreate completely the rewriter for further merging/actions.
  # See `as_nested_actions`
  #
  # @return [Array<Range, String>] an ordered list of pairs of range & replacement
  #
  def as_replacements
    @action_root.ordered_replacements
  end

  ##
  # Returns a representation of the rewriter as nested insertions (:wrap) and replacements.
  #
  #     rewriter.as_actions # =>[ [:wrap, 1...10, '(', ')'],
  #                               [:wrap, 2...6, '', '!'],  # aka "insert_after"
  #                               [:replace, 2...4, 'foo'],
  #                               [:replace, 5...6, ''],  # aka "removal"
  #                             ],
  #
  # Contrary to `as_replacements`, this representation is sufficient to recreate exactly
  # the rewriter.
  #
  # @return [Array<(Symbol, Range, String{, String})>]
  #
  def as_nested_actions
    @action_root.nested_actions
  end

  ##
  # 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. Transactions can be nested.
  #
  # @raise [RuntimeError] when no block is passed
  #
  def transaction
    unless block_given?
      raise "#{self.class}##{__method__} requires block"
    end

    previous = @in_transaction
    @in_transaction = true
    restore_root = @action_root

    yield

    restore_root = nil

    self
  ensure
    @action_root = restore_root if restore_root
    @in_transaction = previous
  end

  def in_transaction?
    @in_transaction
  end

  # :nodoc:
  def inspect
    "#<#{self.class} #{source_buffer.name}: #{action_summary}>"
  end

  ##
  # @api private
  # @deprecated Use insert_after or wrap
  #
  def insert_before_multi(range, text)
    self.class.warn_of_deprecation
    insert_before(range, text)
  end

  ##
  # @api private
  # @deprecated Use insert_after or wrap
  #
  def insert_after_multi(range, text)
    self.class.warn_of_deprecation
    insert_after(range, text)
  end

  DEPRECATION_WARNING = [
    'TreeRewriter#insert_before_multi and insert_before_multi exist only for legacy compatibility.',
    'Please update your code to use `wrap`, `insert_before` or `insert_after` instead.'
  ].join("\n").freeze

  extend Deprecation

  protected

  attr_reader :action_root

  private

  def action_summary
    replacements = as_replacements
    case replacements.size
    when 0 then return 'empty'
    when 1..3 then #ok
    else
      replacements = replacements.first(3)
      suffix = '…'
    end
    parts = replacements.map do |(range, str)|
      if str.empty? # is this a deletion?
        "-#{range.to_range}"
      elsif range.size == 0 # is this an insertion?
        "+#{str.inspect}@#{range.begin_pos}"
      else # it is a replacement
        "^#{str.inspect}@#{range.to_range}"
      end
    end
    parts << suffix if suffix
    parts.join(', ')
  end

  ACTIONS = %i[accept warn raise].freeze
  def check_policy_validity
    invalid = @policy.values - ACTIONS
    raise ArgumentError, "Invalid policy: #{invalid.join(', ')}" unless invalid.empty?
  end

  def combine(range, attributes)
    range = check_range_validity(range)
    action = TreeRewriter::Action.new(range, @enforcer, **attributes)
    @action_root = @action_root.combine(action)
    self
  end

  def check_range_validity(range)
    if range.begin_pos < 0 || range.end_pos > @source_buffer.source.size
      raise IndexError, "The range #{range.to_range} is outside the bounds of the source"
    end
    range
  end

  def enforce_policy(event)
    return if @policy[event] == :accept
    return unless (values = yield)
    trigger_policy(event, **values)
  end

  POLICY_TO_LEVEL = {warn: :warning, raise: :error}.freeze
  def trigger_policy(event, range: raise, conflict: nil, **arguments)
    action = @policy[event] || :raise
    diag = Parser::Diagnostic.new(POLICY_TO_LEVEL[action], event, arguments, range)
    @diagnostics.process(diag)
    if conflict
      range, *highlights = conflict
      diag = Parser::Diagnostic.new(POLICY_TO_LEVEL[action], :"#{event}_conflict", arguments, range, highlights)
      @diagnostics.process(diag)
    end
    raise Parser::ClobberingError, "Parser::Source::TreeRewriter detected clobbering" if action == :raise
  end
end
Method: Parser::Source::TreeRewriter#diagnostics

#diagnostics ⇒ Diagnostic::Engine (readonly)

#diagnostics ⇒ `Diagnostic::Engine` (readonly)
