Class: Prism::Node

Inherits:
Object
  • Object
show all
Defined in:
lib/prism/node.rb,
lib/prism/node_ext.rb,
lib/prism/parse_result/newlines.rb,
ext/prism/extension.c

Overview

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#node_id ⇒ Object (readonly)

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.



21
22
23
 
# File 'lib/prism/node.rb', line 21

def node_id
  @node_id
end

Class Method Details

.fields ⇒ Object

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.

Raises:

  • (NoMethodError) 


242
243
244
245
246
247
248
 
# File 'lib/prism/node.rb', line 242

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

.type ⇒ Object

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.

Raises:

  • (NoMethodError) 


307
308
309
 
# File 'lib/prism/node.rb', line 307

def self.type
  raise NoMethodError, "undefined method `type' for #{inspect}"
end

Instance Method Details

#accept(visitor) ⇒ Object

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

Raises:

  • (NoMethodError) 


258
259
260
 
# File 'lib/prism/node.rb', line 258

def accept(visitor)
  raise NoMethodError, "undefined method `accept' for #{inspect}"
end

#breadth_first_search(&block) ⇒ Object

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 }



228
229
230
231
232
233
234
235
236
237
 
# File 'lib/prism/node.rb', line 228

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

#cached_end_code_units_column(cache) ⇒ Object

Delegates to the cached_end_code_units_column of the associated location object.



115
116
117
 
# File 'lib/prism/node.rb', line 115

def cached_end_code_units_column(cache)
  location.cached_end_code_units_column(cache)
end

#cached_end_code_units_offset(cache) ⇒ Object

Delegates to the cached_end_code_units_offset of the associated location object.



83
84
85
 
# File 'lib/prism/node.rb', line 83

def cached_end_code_units_offset(cache)
  location.cached_end_code_units_offset(cache)
end

#cached_start_code_units_column(cache) ⇒ Object

Delegates to the cached_start_code_units_column of the associated location object.



109
110
111
 
# File 'lib/prism/node.rb', line 109

def cached_start_code_units_column(cache)
  location.cached_start_code_units_column(cache)
end

#cached_start_code_units_offset(cache) ⇒ Object

Delegates to the cached_start_code_units_offset of the associated location object.



77
78
79
 
# File 'lib/prism/node.rb', line 77

def cached_start_code_units_offset(cache)
  location.cached_start_code_units_offset(cache)
end

#child_nodes ⇒ Object Also known as: deconstruct

Returns an array of child nodes, including ‘nil`s in the place of optional nodes that were not present.

Raises:

  • (NoMethodError) 


264
265
266
 
# File 'lib/prism/node.rb', line 264

def child_nodes
  raise NoMethodError, "undefined method `child_nodes' for #{inspect}"
end

#comment_targets ⇒ Object

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

Raises:

  • (NoMethodError) 


278
279
280
 
# File 'lib/prism/node.rb', line 278

def comment_targets
  raise NoMethodError, "undefined method `comment_targets' for #{inspect}"
end

#comments ⇒ Object

Delegates to the comments of the associated location object.



130
131
132
 
# File 'lib/prism/node.rb', line 130

def comments
  location.comments
end

#compact_child_nodes ⇒ Object

Returns an array of child nodes, excluding any ‘nil`s in the place of optional nodes that were not present.

Raises:

  • (NoMethodError) 


272
273
274
 
# File 'lib/prism/node.rb', line 272

def compact_child_nodes
  raise NoMethodError, "undefined method `compact_child_nodes' for #{inspect}"
end

#deprecated(*replacements) ⇒ Object

:nodoc:



7
8
9
10
11
12
13
14
15
16
17
 
# File 'lib/prism/node_ext.rb', line 7

def deprecated(*replacements) # :nodoc:
  location = caller_locations(1, 1)
  location = location[0].label if location
  suggest = replacements.map { |replacement| "#{self.class}##{replacement}" }

  warn(<<~MSG, category: :deprecated)
    [deprecation]: #{self.class}##{location} is deprecated and will be \
    removed in the next major version. Use #{suggest.join("/")} instead.
    #{(caller(1, 3) || []).join("\n")}
  MSG
end

#end_character_column ⇒ Object

Delegates to the end_character_column of the associated location object.



103
104
105
 
# File 'lib/prism/node.rb', line 103

def end_character_column
  location.end_character_column
end

#end_character_offset ⇒ Object

Delegates to the end_character_offset of the associated location object.



71
72
73
 
# File 'lib/prism/node.rb', line 71

def end_character_offset
  location.end_character_offset
end

#end_column ⇒ Object

Delegates to the end_column of the associated location object.



93
94
95
 
# File 'lib/prism/node.rb', line 93

def end_column
  location.end_column
end

#end_line ⇒ Object

Delegates to the end_line of the associated location object.



47
48
49
 
# File 'lib/prism/node.rb', line 47

def end_line
  location.end_line
end

#end_offset ⇒ Object

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



60
61
62
63
 
# File 'lib/prism/node.rb', line 60

def end_offset
  location = @location
  location.is_a?(Location) ? location.end_offset : ((location >> 32) + (location & 0xFFFFFFFF))
end

#inspect ⇒ Object

Returns a string representation of the node.

Raises:

  • (NoMethodError) 


283
284
285
 
# File 'lib/prism/node.rb', line 283

def inspect
  raise NoMethodError, "undefined method `inspect' for #{inspect}"
end

#leading_comments ⇒ Object

Delegates to the leading_comments of the associated location object.



120
121
122
 
# File 'lib/prism/node.rb', line 120

def leading_comments
  location.leading_comments
end

#location ⇒ Object

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



30
31
32
33
34
 
# File 'lib/prism/node.rb', line 30

def location
  location = @location
  return location if location.is_a?(Location)
  @location = Location.new(source, location >> 32, location & 0xFFFFFFFF)
end

#newline? ⇒ Boolean

Returns true if the node has the newline flag set.

Returns:

  • (Boolean) 


161
162
163
 
# File 'lib/prism/node.rb', line 161

def newline?
  flags.anybits?(NodeFlags::NEWLINE)
end

#newline_flag!(lines) ⇒ Object

:nodoc:



69
70
71
72
73
74
75
 
# File 'lib/prism/parse_result/newlines.rb', line 69

def newline_flag!(lines) # :nodoc:
  line = location.start_line
  unless lines[line]
    lines[line] = true
    @newline_flag = true
  end
end

#newline_flag? ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


65
66
67
 
# File 'lib/prism/parse_result/newlines.rb', line 65

def newline_flag? # :nodoc:
  @newline_flag ? true : false
end

#pretty_print(q) ⇒ Object

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



172
173
174
175
176
177
 
# File 'lib/prism/node.rb', line 172

def pretty_print(q)
  q.seplist(inspect.chomp.each_line, -> { q.breakable }) do |line|
    q.text(line.chomp)
  end
  q.current_group.break
end

#save(repository) ⇒ Object

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



24
25
26
 
# File 'lib/prism/node.rb', line 24

def save(repository)
  repository.enter(node_id, :itself)
end

#save_location(repository) ⇒ Object

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



37
38
39
 
# File 'lib/prism/node.rb', line 37

def save_location(repository)
  repository.enter(node_id, :location)
end

#slice ⇒ Object

Slice the location of the node from the source.



144
145
146
 
# File 'lib/prism/node.rb', line 144

def slice
  location.slice
end

#slice_lines ⇒ Object

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.



151
152
153
 
# File 'lib/prism/node.rb', line 151

def slice_lines
  location.slice_lines
end

#source_lines ⇒ Object Also known as: script_lines

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



135
136
137
 
# File 'lib/prism/node.rb', line 135

def source_lines
  location.source_lines
end

#start_character_column ⇒ Object

Delegates to the start_character_column of the associated location object.



98
99
100
 
# File 'lib/prism/node.rb', line 98

def start_character_column
  location.start_character_column
end

#start_character_offset ⇒ Object

Delegates to the start_character_offset of the associated location object.



66
67
68
 
# File 'lib/prism/node.rb', line 66

def start_character_offset
  location.start_character_offset
end

#start_column ⇒ Object

Delegates to the start_column of the associated location object.



88
89
90
 
# File 'lib/prism/node.rb', line 88

def start_column
  location.start_column
end

#start_line ⇒ Object

Delegates to the start_line of the associated location object.



42
43
44
 
# File 'lib/prism/node.rb', line 42

def start_line
  location.start_line
end

#start_offset ⇒ Object

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



53
54
55
56
 
# File 'lib/prism/node.rb', line 53

def start_offset
  location = @location
  location.is_a?(Location) ? location.start_offset : location >> 32
end

#static_literal? ⇒ Boolean

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

Returns:

  • (Boolean) 


166
167
168
 
# File 'lib/prism/node.rb', line 166

def static_literal?
  flags.anybits?(NodeFlags::STATIC_LITERAL)
end

#to_dot ⇒ Object

Convert this node into a graphviz dot graph string.



180
181
182
183
 
# File 'lib/prism/node.rb', line 180

def to_dot
  # @type self: node
  DotVisitor.new.tap { |visitor| accept(visitor) }.to_dot
end

#trailing_comments ⇒ Object

Delegates to the trailing_comments of the associated location object.



125
126
127
 
# File 'lib/prism/node.rb', line 125

def trailing_comments
  location.trailing_comments
end

#tunnel(line, column) ⇒ Object

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.



191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/prism/node.rb', line 191

def tunnel(line, column)
  queue = [self] #: Array[Prism::node]
  result = [] #: Array[Prism::node]

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

    node.compact_child_nodes.each 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

#type ⇒ Object

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.

Raises:

  • (NoMethodError) 


299
300
301
 
# File 'lib/prism/node.rb', line 299

def type
  raise NoMethodError, "undefined method `type' for #{inspect}"
end