W3cubDocs

/Ruby 4.0

class Prism::Node

Parent:: Object

This represents a node in the tree. It is the parent class of all of the various node types.

Attributes

An bitset of flags for this node. There are certain flags that are common for all nodes, and then some nodes have specific flags.

node_id [R]

A unique identifier for this node. This is used in a very specific use case where you want to keep around a reference to a node without having to keep around the syntax tree in memory. This unique identifier will be consistent across multiple parses of the same source code.

source [R]

A pointer to the source that this node was created from.

Public Class Methods

# File lib/prism/node.rb, line 245
def self.fields
  # This method should only be called on subclasses of Node, not Node
  # itself.
  raise NoMethodError, "undefined method `fields' for #{inspect}" if self == Node

  Reflection.fields_for(self)
end

fields () Show source

Returns a list of the fields that exist for this node class. Fields describe the structure of the node. This kind of reflection is useful for things like recursively visiting each node and field in the tree.

Public Instance Methods

# File lib/prism/node.rb, line 231
def breadth_first_search(&block)
  queue = [self] #: Array[Prism::node]

  while (node = queue.shift)
    return node if yield node
    queue.concat(node.compact_child_nodes)
  end

  nil
end

breadth_first_search () { |node| ... } Show source

Returns the first node that matches the given block when visited in a depth-first search. This is useful for finding a node that matches a particular condition.

node.breadth_first_search { |node| node.node_id == node_id }

# File lib/prism/node.rb, line 118
def cached_end_code_units_column(cache)
  location.cached_end_code_units_column(cache)
end

cached_end_code_units_column (cache) Show source

Delegates to the cached_end_code_units_column of the associated location object.

# File lib/prism/node.rb, line 86
def cached_end_code_units_offset(cache)
  location.cached_end_code_units_offset(cache)
end

cached_end_code_units_offset (cache) Show source

Delegates to the cached_end_code_units_offset of the associated location object.

# File lib/prism/node.rb, line 112
def cached_start_code_units_column(cache)
  location.cached_start_code_units_column(cache)
end

cached_start_code_units_column (cache) Show source

Delegates to the cached_start_code_units_column of the associated location object.

# File lib/prism/node.rb, line 80
def cached_start_code_units_offset(cache)
  location.cached_start_code_units_offset(cache)
end

cached_start_code_units_offset (cache) Show source

Delegates to the cached_start_code_units_offset of the associated location object.

# File lib/prism/node.rb, line 133
def comments
  location.comments
end

comments () Show source

Delegates to the comments of the associated location object.

# File lib/prism/node.rb, line 106
def end_character_column
  location.end_character_column
end

end_character_column () Show source

Delegates to the end_character_column of the associated location object.

# File lib/prism/node.rb, line 74
def end_character_offset
  location.end_character_offset
end

end_character_offset () Show source

Delegates to the end_character_offset of the associated location object.

# File lib/prism/node.rb, line 96
def end_column
  location.end_column
end

end_column () Show source

Delegates to the end_column of the associated location object.

# File lib/prism/node.rb, line 50
def end_line
  location.end_line
end

end_line () Show source

Delegates to the end_line of the associated location object.

# File lib/prism/node.rb, line 63
def end_offset
  location = @location
  location.is_a?(Location) ? location.end_offset : ((location >> 32) + (location & 0xFFFFFFFF))
end

end_offset () Show source

The end offset of the node in the source. This method is effectively a delegate method to the location object.

# File lib/prism/node.rb, line 123
def leading_comments
  location.leading_comments
end

leading_comments () Show source

Delegates to the leading_comments of the associated location object.

# File lib/prism/node.rb, line 33
def location
  location = @location
  return location if location.is_a?(Location)
  @location = Location.new(source, location >> 32, location & 0xFFFFFFFF)
end

location () Show source

A Location instance that represents the location of this node in the source.

# File lib/prism/node.rb, line 164
def newline?
  flags.anybits?(NodeFlags::NEWLINE)
end

newline? () Show source

Returns true if the node has the newline flag set.

# File lib/prism/node.rb, line 175
def pretty_print(q)
  q.seplist(inspect.chomp.each_line, -> { q.breakable }) do |line|
    q.text(line.chomp)
  end
  q.current_group.break
end

pretty_print (q) Show source

Similar to inspect, but respects the current level of indentation given by the pretty print object.

# File lib/prism/node.rb, line 27
def save(repository)
  repository.enter(node_id, :itself)
end

save (repository) Show source

Save this node using a saved source so that it can be retrieved later.

# File lib/prism/node.rb, line 40
def save_location(repository)
  repository.enter(node_id, :location)
end

save_location (repository) Show source

Save the location using a saved source so that it can be retrieved later.

script_lines ()

An alias for source_lines, used to mimic the API from RubyVM::AbstractSyntaxTree to make it easier to migrate.

Alias for: source_lines

# File lib/prism/node.rb, line 147
def slice
  location.slice
end

slice () Show source

Slice the location of the node from the source.

# File lib/prism/node.rb, line 154
def slice_lines
  location.slice_lines
end

slice_lines () Show source

Slice the location of the node from the source, starting at the beginning of the line that the location starts on, ending at the end of the line that the location ends on.

# File lib/prism/node.rb, line 138
def source_lines
  location.source_lines
end

source_lines () Show source

Returns all of the lines of the source code associated with this node.

Also aliased as: script_lines

# File lib/prism/node.rb, line 101
def start_character_column
  location.start_character_column
end

start_character_column () Show source

Delegates to the start_character_column of the associated location object.

# File lib/prism/node.rb, line 69
def start_character_offset
  location.start_character_offset
end

start_character_offset () Show source

Delegates to the start_character_offset of the associated location object.

# File lib/prism/node.rb, line 91
def start_column
  location.start_column
end

start_column () Show source

Delegates to the start_column of the associated location object.

# File lib/prism/node.rb, line 45
def start_line
  location.start_line
end

start_line () Show source

Delegates to the start_line of the associated location object.

# File lib/prism/node.rb, line 56
def start_offset
  location = @location
  location.is_a?(Location) ? location.start_offset : location >> 32
end

start_offset () Show source

The start offset of the node in the source. This method is effectively a delegate method to the location object.

# File lib/prism/node.rb, line 169
def static_literal?
  flags.anybits?(NodeFlags::STATIC_LITERAL)
end

static_literal? () Show source

Returns true if the node has the static literal flag set.

# File lib/prism/node.rb, line 183
def to_dot
  # @type self: node
  DotVisitor.new.tap { |visitor| accept(visitor) }.to_dot
end

to_dot () Show source

Convert this node into a graphviz dot graph string.

# File lib/prism/node.rb, line 128
def trailing_comments
  location.trailing_comments
end

trailing_comments () Show source

Delegates to the trailing_comments of the associated location object.

# File lib/prism/node.rb, line 194
def tunnel(line, column)
  queue = [self] #: Array[Prism::node]
  result = [] #: Array[Prism::node]

  while (node = queue.shift)
    result << node

    node.each_child_node do |child_node|
      child_location = child_node.location

      start_line = child_location.start_line
      end_line = child_location.end_line

      if start_line == end_line
        if line == start_line && column >= child_location.start_column && column < child_location.end_column
          queue << child_node
          break
        end
      elsif (line == start_line && column >= child_location.start_column) || (line == end_line && column < child_location.end_column)
        queue << child_node
        break
      elsif line > start_line && line < end_line
        queue << child_node
        break
      end
    end
  end

  result
end

tunnel (line, column) Show source

Returns a list of nodes that are descendants of this node that contain the given line and column. This is useful for locating a node that is selected based on the line and column of the source code.

Important to note is that the column given to this method should be in bytes, as opposed to characters or code units.

Node interface

Public Class Methods

# File lib/prism/node.rb, line 317
def self.type
  raise NoMethodError, "undefined method `type' for #{inspect}"
end

type () Show source

Similar to type, this method returns a symbol that you can use for splitting on the type of the node without having to do a long === chain. Note that like type, it will still be slower than using == for a single class, but should be faster in a case statement or an array comparison.

Public Instance Methods

# File lib/prism/node.rb, line 261
def accept(visitor)
  raise NoMethodError, "undefined method `accept' for #{inspect}"
end

accept (visitor) Show source

Accepts a visitor and calls back into the specialized visit function.

# File lib/prism/node.rb, line 267
def child_nodes
  raise NoMethodError, "undefined method `child_nodes' for #{inspect}"
end

child_nodes () Show source

Returns an array of child nodes, including nils in the place of optional nodes that were not present.

Also aliased as: deconstruct

# File lib/prism/node.rb, line 288
def comment_targets
  raise NoMethodError, "undefined method `comment_targets' for #{inspect}"
end

comment_targets () Show source

Returns an array of child nodes and locations that could potentially have comments attached to them.

# File lib/prism/node.rb, line 282
def compact_child_nodes
  raise NoMethodError, "undefined method `compact_child_nodes' for #{inspect}"
end

compact_child_nodes () Show source

Returns an array of child nodes, excluding any nils in the place of optional nodes that were not present.

deconstruct ()

Alias for: child_nodes

# File lib/prism/node.rb, line 276
def each_child_node
  raise NoMethodError, "undefined method `each_child_node' for #{inspect}"
end

each_child_node () Show source

With a block given, yields each child node. Without a block, returns an enumerator that contains each child node. Excludes any nils in the place of optional nodes that were not present.

# File lib/prism/node.rb, line 293
def inspect
  raise NoMethodError, "undefined method `inspect' for #{inspect}"
end

inspect () Show source

Returns a string representation of the node.

# File lib/prism/node.rb, line 309
def type
  raise NoMethodError, "undefined method `type' for #{inspect}"
end

type () Show source

Sometimes you want to check an instance of a node against a list of classes to see what kind of behavior to perform. Usually this is done by calling [cls1, cls2].include?(node.class) or putting the node into a case statement and doing case node; when cls1; when cls2; end. Both of these approaches are relatively slow because of the constant lookups, method calls, and/or array allocations.

Instead, you can call type, which will return to you a symbol that you can use for comparison. This is faster than the other approaches because it uses a single integer comparison, but also because if you’re on CRuby you can take advantage of the fact that case statements with all symbol keys will use a jump table.

Ruby Core © 1993–2025 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.