123456789_123456789_123456789_123456789_123456789_

Class: Prism::Pattern

Relationships & Source Files
Namespace Children
Exceptions:
CompilationError
Inherits: Object
Defined in: lib/prism/pattern.rb

Overview

A pattern is an object that wraps a Ruby pattern matching expression. The expression would normally be passed to an in clause within a case expression or a rightward assignment expression. For example, in the following snippet:

case node
in ConstantPathNode[ConstantReadNode[name: :Prism], ConstantReadNode[name: :Pattern]]
end

the pattern is the ConstantPathNode[...] expression.

The pattern gets compiled into an object that responds to #call by running the #compile method. This method itself will run back through ::Prism to parse the expression into a tree, then walk the tree to generate the necessary callable objects. For example, if you wanted to compile the expression above into a callable, you would:

callable = Prism::Pattern.new("ConstantPathNode[ConstantReadNode[name: :Prism], ConstantReadNode[name: :Pattern]]").compile
callable.call(node)

The callable object returned by #compile is guaranteed to respond to #call with a single argument, which is the node to match against. It also is guaranteed to respond to #===, which means it itself can be used in a case expression, as in:

case node
when callable
end

If the query given to the initializer cannot be compiled into a valid matcher (either because of a syntax error or because it is using syntax we do not yet support) then a CompilationError will be raised.

Class Method Summary

Instance Attribute Summary

  • #query readonly

    The query that this pattern was initialized with.

Instance Method Summary

Constructor Details

.new(query) ⇒ Pattern

Create a new pattern with the given query. The query should be a string containing a Ruby pattern matching expression.

[ GitHub ] 

  


# File 'lib/prism/pattern.rb', line 71



def initialize(query)
  @query = query
  @compiled = nil
end


  







Instance Attribute Details



  

    #query   (readonly)
  



  

    

The query that this pattern was initialized with.


  



  [ GitHub ]


  

  


# File 'lib/prism/pattern.rb', line 64



attr_reader :query #: String


  







Instance Method Details



  

    #combine_and(left, right)   (private)
  

  

    This method is for internal use only.
  



  

    

Shortcut for combining two procs into one that returns true if both return true.


  



  [ GitHub ]


  

  


# File 'lib/prism/pattern.rb', line 117



def combine_and(left, right) # :nodoc:
  ->(other) { left.call(other) && right.call(other) }
end


  








  

    #combine_or(left, right)   (private)
  

  

    This method is for internal use only.
  



  

    

Shortcut for combining two procs into one that returns true if either returns true.


  



  [ GitHub ]


  

  


# File 'lib/prism/pattern.rb', line 125



def combine_or(left, right) # :nodoc:
  ->(other) { left.call(other) || right.call(other) }
end


  








  

    #compile  
  



  

    

Compile the query into a callable object that can be used to match against nodes.


  





  
Raises:





  [ GitHub ]


  

  


# File 'lib/prism/pattern.rb', line 80



def compile
  result = Prism.parse("case nil\nin #{query}\nend")

  case_match_node = result.value.statements.body.last
  raise CompilationError, case_match_node.inspect unless case_match_node.is_a?(CaseMatchNode)

  in_node = case_match_node.conditions.last
  raise CompilationError, in_node.inspect unless in_node.is_a?(InNode)

  compile_node(in_node.pattern)
end


  








  

    #compile_alternation_pattern_node(node)   (private)
  

  

    This method is for internal use only.
  



  

    

in foo | bar


  



  [ GitHub ]


  

  


# File 'lib/prism/pattern.rb', line 168



def compile_alternation_pattern_node(node) # :nodoc:
  combine_or(compile_node(node.left), compile_node(node.right))
end


  








  

    #compile_array_pattern_node(node)   (private)
  

  

    This method is for internal use only.
  



  

    

in [foo, bar, baz]


  



  [ GitHub ]


  

  


# File 'lib/prism/pattern.rb', line 141



def compile_array_pattern_node(node) # :nodoc:
  compile_error(node) if !node.rest.nil? || node.posts.any?

  constant = node.constant
  compiled_constant = compile_node(constant) if constant

  preprocessed = node.requireds.map { |required| compile_node(required) }

  compiled_requireds = ->(other) do
    deconstructed = other.deconstruct

    deconstructed.length == preprocessed.length &&
      preprocessed
        .zip(deconstructed)
        .all? { |(matcher, value)| matcher.call(value) }
  end

  if compiled_constant
    combine_and(compiled_constant, compiled_requireds)
  else
    compiled_requireds
  end
end


  








  

    #compile_constant_name(node, name)   (private)
  

  

    This method is for internal use only.
  



  

    

Compile a name associated with a constant.


  



  [ GitHub ]


  

  


# File 'lib/prism/pattern.rb', line 199



def compile_constant_name(node, name) # :nodoc:
  if Prism.const_defined?(name, false)
    clazz = Prism.const_get(name)

    ->(other) { clazz === other }
  elsif Object.const_defined?(name, false)
    clazz = Object.const_get(name)

    ->(other) { clazz === other }
  else
    compile_error(node)
  end
end


  








  

    #compile_constant_path_node(node)   (private)
  

  

    This method is for internal use only.
  



  

    

in ConstantReadNode


  



  [ GitHub ]


  

  


# File 'lib/prism/pattern.rb', line 175



def compile_constant_path_node(node) # :nodoc:
  parent = node.parent

  if parent.is_a?(ConstantReadNode) && parent.slice == "Prism"
    name = node.name
    raise CompilationError, node.inspect if name.nil?

    compile_constant_name(node, name)
  else
    compile_error(node)
  end
end


  








  

    #compile_constant_read_node(node)   (private)
  

  

    This method is for internal use only.
  



  

    

in ConstantReadNode in String


  



  [ GitHub ]


  

  


# File 'lib/prism/pattern.rb', line 192



def compile_constant_read_node(node) # :nodoc:
  compile_constant_name(node, node.name)
end


  








  

    #compile_error(node)   (private)
  

  

    This method is for internal use only.
  



  

    

Raise an error because the given node is not supported. Note purposefully not typing this method since it is a no return method that Steep does not understand.


  





  
Raises:





  [ GitHub ]


  

  


# File 'lib/prism/pattern.rb', line 134



def compile_error(node) # :nodoc:
  raise CompilationError, node.inspect
end


  








  

    #compile_hash_pattern_node(node)   (private)
  

  

    This method is for internal use only.
  



  

    

in InstanceVariableReadNode[name: Symbol] in { name: Symbol }


  



  [ GitHub ]


  

  


# File 'lib/prism/pattern.rb', line 217



def compile_hash_pattern_node(node) # :nodoc:
  compile_error(node) if node.rest

  if (constant = node.constant)
    compiled_constant = compile_node(constant)
  end

  preprocessed =
    node.elements.to_h do |element|
      key = element.key
      if key.is_a?(SymbolNode)
        [key.unescaped.to_sym, compile_node(element.value)]
      else
        raise CompilationError, element.inspect
      end
    end

  compiled_keywords = ->(other) do
    deconstructed = other.deconstruct_keys(preprocessed.keys)

    preprocessed.all? do |keyword, matcher|
      deconstructed.key?(keyword) && matcher.call(deconstructed[keyword])
    end
  end

  if compiled_constant
    combine_and(compiled_constant, compiled_keywords)
  else
    compiled_keywords
  end
end


  








  

    #compile_nil_node(node)   (private)
  

  

    This method is for internal use only.
  



  

    

in nil


  



  [ GitHub ]


  

  


# File 'lib/prism/pattern.rb', line 252



def compile_nil_node(node) # :nodoc:
  ->(attribute) { attribute.nil? }
end


  








  

    #compile_node(node)   (private)
  

  

    This method is for internal use only.
  



  

    

Compile any kind of node. Dispatch out to the individual compilation methods based on the type of node.


  



  [ GitHub ]


  

  


# File 'lib/prism/pattern.rb', line 289



def compile_node(node) # :nodoc:
  case node
  when AlternationPatternNode
    compile_alternation_pattern_node(node)
  when ArrayPatternNode
    compile_array_pattern_node(node)
  when ConstantPathNode
    compile_constant_path_node(node)
  when ConstantReadNode
    compile_constant_read_node(node)
  when HashPatternNode
    compile_hash_pattern_node(node)
  when NilNode
    compile_nil_node(node)
  when RegularExpressionNode
    compile_regular_expression_node(node)
  when StringNode
    compile_string_node(node)
  when SymbolNode
    compile_symbol_node(node)
  else
    compile_error(node)
  end
end


  








  

    #compile_regular_expression_node(node)   (private)
  

  

    This method is for internal use only.
  



  

    

in /foo/


  



  [ GitHub ]


  

  


# File 'lib/prism/pattern.rb', line 259



def compile_regular_expression_node(node) # :nodoc:
  regexp = Regexp.new(node.unescaped, node.closing[1..])

  ->(attribute) { regexp === attribute }
end


  








  

    #compile_string_node(node)   (private)
  

  

    This method is for internal use only.
  



  

    

in “” in “foo”


  



  [ GitHub ]


  

  


# File 'lib/prism/pattern.rb', line 269



def compile_string_node(node) # :nodoc:
  string = node.unescaped

  ->(attribute) { string === attribute }
end


  








  

    #compile_symbol_node(node)   (private)
  

  

    This method is for internal use only.
  



  

    

in :+ in :foo


  



  [ GitHub ]


  

  


# File 'lib/prism/pattern.rb', line 279



def compile_symbol_node(node) # :nodoc:
  symbol = node.unescaped.to_sym

  ->(attribute) { symbol === attribute }
end


  








  

    #scan(root, &blk)  
  



  

    

Scan the given node and all of its children for nodes that match the pattern. If a block is given, it will be called with each node that matches the pattern. If no block is given, an enumerator will be returned that will yield each node that matches the pattern.


  



  [ GitHub ]


  

  


# File 'lib/prism/pattern.rb', line 99



def scan(root, &blk)
  return to_enum(:scan, root) unless block_given?

  @compiled ||= compile
  queue = [root]

  while (node = queue.shift)
    yield node if @compiled.call(node) # steep:ignore
    queue.concat(node.compact_child_nodes)
  end
end