Class: Mutineer::Isolation::PathAnchor Private

Inherits:
Prism::Visitor
  • Object
show all
Defined in:
lib/mutineer/isolation.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

Rewrites path anchors in one snippet (#339). A require_relative argument is rewritten on its own first, so a nested __dir__ or __FILE__ is not left pointing at the file load runs.

Constant Summary collapse

SKIPPED_ARGUMENTS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Argument nodes that are not a path expression. A keyword argument makes require_relative raise ArgumentError before it touches a file, so the call is left as written. A splat is a path and is kept.

[
  Prism::KeywordHashNode, Prism::BlockArgumentNode, Prism::ForwardingArgumentsNode
].freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(source, file_literal, dir_literal, bare_kernel) ⇒ PathAnchor

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of PathAnchor.

Parameters:

  • source (String) —

    the snippet or argument to rewrite.

  • file_literal (String) —

    a dumped Ruby string of the original __FILE__.

  • dir_literal (String) —

    a dumped Ruby string of the original __dir__.

  • bare_kernel (Boolean) —

    rewrite a bare Kernel receiver. False when the method's lexical scope defines a different Kernel.



553
554
555
556
557
558
559
# File 'lib/mutineer/isolation.rb', line 553

def initialize(source, file_literal, dir_literal, bare_kernel)
  @source = source
  @file_literal = file_literal
  @dir_literal = dir_literal
  @bare_kernel = bare_kernel
  @edits = []
end

Class Method Details

.rewrite(source, file_literal, dir_literal, bare_kernel: true) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parses source and applies the edits. A parse that still builds a tree is rewritten too: Prism 2 reports T += 1 inside a method while Ruby loads it (#392), and the anchors in that method must still move. With no tree, source comes back unchanged.

Parameters:

  • source (String) —

    snippet or argument source.

  • file_literal (String) —

    dumped original __FILE__.

  • dir_literal (String) —

    dumped original __dir__.

  • bare_kernel (Boolean) (defaults to: true) —

Returns:

  • (String)


571
572
573
574
575
576
577
578
# File 'lib/mutineer/isolation.rb', line 571

def self.rewrite(source, file_literal, dir_literal, bare_kernel: true)
  parsed = Prism.parse(source)
  return source unless parsed.value

  anchor = new(source, file_literal, dir_literal, bare_kernel)
  anchor.visit(parsed.value)
  anchor.apply
end

Instance Method Details

#apply ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Applies recorded edits from the end, so earlier byte offsets stay valid.

Returns:

  • (String) —

    the rewritten source.



612
613
614
615
616
617
# File 'lib/mutineer/isolation.rb', line 612

def apply
  @edits.sort_by! { |start_off,| -start_off }
  @edits.inject(@source) do |code, (start_off, end_off, text)|
    code.byteslice(0, start_off) + text + code.byteslice(end_off..)
  end
end

#dir_call?(node) ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True when node is the __dir__ keyword, including self.__dir__, Kernel.__dir__, and send / __send__ of the literal name.

Parameters:

  • node (Prism::CallNode)

Returns:

  • (Boolean)


626
627
628
629
630
631
632
633
634
635
636
637
# File 'lib/mutineer/isolation.rb', line 626

def dir_call?(node)
  args = positional(node)
  return false if args.nil?

  if node.name == :__dir__
    path_receiver?(node) && args.empty?
  elsif send_call?(node)
    args.size == 1 && literal_name(args.first) == "__dir__"
  else
    false
  end
end

#kernel_constant?(node) ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True when node is Kernel or ::Kernel.

Parameters:

  • node (Prism::Node)

Returns:

  • (Boolean)


672
673
674
675
# File 'lib/mutineer/isolation.rb', line 672

def kernel_constant?(node)
  (node.is_a?(Prism::ConstantPathNode) && node.parent.nil? && node.name == :Kernel) ||
    (@bare_kernel && node.is_a?(Prism::ConstantReadNode) && node.name == :Kernel)
end

#literal_name(node) ⇒ String? (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The text of a symbol or string literal, without quotes.

Parameters:

  • node (Prism::Node)

Returns:

  • (String, nil)


700
701
702
# File 'lib/mutineer/isolation.rb', line 700

def literal_name(node)
  node.unescaped if node.is_a?(Prism::SymbolNode) || node.is_a?(Prism::StringNode)
end

#path_receiver?(node) ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True for an implicit receiver, literal self, or Kernel / ::Kernel.

Parameters:

  • node (Prism::CallNode)

Returns:

  • (Boolean)


661
662
663
664
665
666
# File 'lib/mutineer/isolation.rb', line 661

def path_receiver?(node)
  receiver = node.receiver
  return true if receiver.nil? || receiver.is_a?(Prism::SelfNode)

  kernel_constant?(receiver)
end

#positional(node) ⇒ Array<Prism::Node>? (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Positional arguments, or nil when one of them is a splat or keywords.

Parameters:

  • node (Prism::CallNode)

Returns:

  • (Array<Prism::Node>, nil)


689
690
691
692
693
694
# File 'lib/mutineer/isolation.rb', line 689

def positional(node)
  args = node.arguments&.arguments || []
  return if args.any? { |arg| SKIPPED_ARGUMENTS.any? { |kind| arg.is_a?(kind) } }

  args
end

#relative_argument(node) ⇒ Prism::Node? (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The single path argument of a require_relative call, or nil when the call is not that anchor. send(:require_relative, expr) returns expr. A splat is included: require_relative(*paths) passes those paths on. A block does not matter: the method does not yield it.

Parameters:

  • node (Prism::CallNode)

Returns:

  • (Prism::Node, nil)


646
647
648
649
650
651
652
653
654
655
# File 'lib/mutineer/isolation.rb', line 646

def relative_argument(node)
  args = positional(node)
  return unless args

  if node.name == :require_relative && path_receiver?(node) && args.size == 1
    args.first
  elsif send_call?(node) && args.size == 2 && literal_name(args.first) == "require_relative"
    args.last
  end
end

#replace(node, text) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Records a replacement of node's source range.

Parameters:

  • node (Prism::Node)
  • text (String) —

    the Ruby source to write instead.



726
727
728
729
# File 'lib/mutineer/isolation.rb', line 726

def replace(node, text)
  location = node.location
  @edits << [location.start_offset, location.end_offset, text]
end

#rewrite_slice(node) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Rewrites anchors inside one argument, keeping the call's bare_kernel flag.

Parameters:

  • node (Prism::Node)

Returns:

  • (String)


717
718
719
# File 'lib/mutineer/isolation.rb', line 717

def rewrite_slice(node)
  self.class.rewrite(slice(node), @file_literal, @dir_literal, bare_kernel: @bare_kernel)
end

#send_call?(node) ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True for send or __send__ on a receiver #path_receiver? accepts.

Parameters:

  • node (Prism::CallNode)

Returns:

  • (Boolean)


681
682
683
# File 'lib/mutineer/isolation.rb', line 681

def send_call?(node)
  (node.name == :send || node.name == :__send__) && path_receiver?(node)
end

#slice(node) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The snippet bytes of node.

Parameters:

  • node (Prism::Node)

Returns:

  • (String)


708
709
710
711
# File 'lib/mutineer/isolation.rb', line 708

def slice(node)
  location = node.location
  @source.byteslice(location.start_offset, location.end_offset - location.start_offset)
end

#visit_call_node(node) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Replaces a path-anchor call, or walks into a call that is not one.

Parameters:

  • node (Prism::CallNode) —

    a call in the snippet.



592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
# File 'lib/mutineer/isolation.rb', line 592

def visit_call_node(node)
  return replace(node, @dir_literal) if dir_call?(node)

  if (argument = relative_argument(node))
    anchored = rewrite_slice(argument)
    # `::Kernel.require` and `::File` do not follow a nested constant or an
    # instance `require`. `absolute_path` leaves a leading `~` as a path
    # segment; `expand_path` would treat it as a home directory, which
    # `require_relative` does not. An ignored block is part of the call
    # location and is dropped: `require_relative` does not yield it.
    text = ["::Kernel.require(::File.absolute_path(", anchored, ", ", @dir_literal, "))"].join
    return replace(node, text)
  end

  super
end

#visit_source_file_node(node) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Replaces a __FILE__ keyword with the original path.

Parameters:

  • node (Prism::SourceFileNode) —

    the keyword.



584
585
586
# File 'lib/mutineer/isolation.rb', line 584

def visit_source_file_node(node)
  replace(node, @file_literal)
end