Class: YARD::Parser::Ruby::AstNode

Inherits:
Array
  • Object
show all
Defined in:
lib/yard/parser/ruby/ast_node.rb

Overview

An AST node is characterized by a type and a list of children. It is most easily represented by the s-expression #s such as:

# AST for "if true; 5 end":
s(s(:if, s(:var_ref, s(:kw, "true")), s(s(:int, "5")), nil))

The node type is not considered part of the list, only its children. So ast[0] does not refer to the type, but rather the first child (or object). Items that are not AstNode objects can be part of the list, like Strings or Symbols representing names. To return only the AstNode children of the node, use #children.

Constant Summary collapse

KEYWORDS =

List of all known keywords

{ class: true, alias: true, lambda: true, do_block: true,
def: true, defs: true, begin: true, rescue: true, rescue_mod: true,
if: true, if_mod: true, else: true, elsif: true, case: true,
when: true, next: true, break: true, retry: true, redo: true,
return: true, throw: true, catch: true, until: true, until_mod: true,
while: true, while_mod: true, yield: true, yield0: true, zsuper: true,
unless: true, unless_mod: true, for: true, super: true, return0: true }

Instance Attribute Summary collapse

Creating an AstNode collapse

Traversing a Node collapse

Node Meta Types collapse

Getting Line Information collapse

Printing a Node collapse

Instance Method Summary collapse

Methods inherited from Array

#place

Constructor Details

#initialize(type, arr, opts = {}) ⇒ AstNode

Creates a new AST node

Options Hash (opts):

  • :line (Fixnum) — default: nil —

    the line the node starts on in source

  • :char (String) — default: nil —

    the character number the node starts on in source

  • :listline (Fixnum) — default: nil —

    a special key like :line but for list nodes

  • :listchar (Fixnum) — default: nil —

    a special key like :char but for list nodes

  • :token (Boolean) — default: nil —

    whether the node represents a token



131
132
133
134
135
136
137
138
139
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 131

def initialize(type, arr, opts = {})
  super(arr)
  self.type = type
  self.line_range = opts[:line]
  self.source_range = opts[:char]
  @fallback_line = opts[:listline]
  @fallback_source = opts[:listchar]
  @token = true if opts[:token]
end

Instance Attribute Details

#docstring ⇒ Object Also known as: comments

Returns the value of attribute docstring.



41
42
43
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 41

def docstring
  @docstring
end

#docstring_range ⇒ Object Also known as: comments_range

Returns the value of attribute docstring_range.



41
42
43
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 41

def docstring_range
  @docstring_range
end

#file ⇒ String 



68
69
70
71
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 68

def file
  return parent.file if parent
  @file
end

#full_source ⇒ String 



74
75
76
77
78
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 74

def full_source
  return parent.full_source if parent
  return @full_source if @full_source
  return IO.read(@file) if file && File.exist?(file)
end

#group ⇒ Object

Returns the value of attribute group.



41
42
43
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 41

def group
  @group
end

#line_range ⇒ Range 



62
63
64
65
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 62

def line_range
  reset_line_info unless @line_range
  @line_range
end

#parent ⇒ AstNode? 



51
52
53
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 51

def parent
  @parent
end

#source ⇒ String 



81
82
83
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 81

def source
  @source
end

#source_range ⇒ Range 



55
56
57
58
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 55

def source_range
  reset_line_info unless @source_range
  @source_range
end

#type ⇒ Symbol 



48
49
50
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 48

def type
  @type
end

Class Method Details

.node_class_for(type) ⇒ Class

Finds the node subclass that should be instantiated for a specific node type



103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 103

def self.node_class_for(type)
  case type
  when :params
    ParameterNode
  when :call, :fcall, :command, :command_call
    MethodCallNode
  when :if, :elsif, :if_mod, :unless, :unless_mod
    ConditionalNode
  when /_ref\Z/
    ReferenceNode
  else
    AstNode
  end
end

Instance Method Details

#call? ⇒ Boolean 



217
218
219
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 217

def call?
  false
end

#children ⇒ Array<AstNode> 



176
177
178
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 176

def children
  @children ||= select {|e| AstNode === e }
end

#condition? ⇒ Boolean 



222
223
224
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 222

def condition?
  false
end

#first_line ⇒ String 



239
240
241
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 239

def first_line
  full_source.split(/\r?\n/)[line - 1].strip
end

#has_line? ⇒ Boolean 



229
230
231
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 229

def has_line?
  @line_range ? true : false
end

#inspect ⇒ String 



285
286
287
288
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 285

def inspect 
  typeinfo = type && type != :list ? ':' + type.to_s + ', ' : ''
  's(' + typeinfo + map(&:inspect).join(", ") + ')'
end

#jump(*node_types) ⇒ AstNode, self

Searches through the node and all descendents and returns the first node with a type matching any of node_types, otherwise returns the original node (self).

Examples:

Returns the first method definition in a block of code

ast = YARD.parse_string("if true; def x; end end").ast
ast.jump(:def)
# => s(:def, s(:ident, "x"), s(:params, nil, nil, nil, nil, 
#      nil), s(s(:void_stmt, )))

Returns first ‘def’ or ‘class’ statement

ast = YARD.parse_string("class X; def y; end end")
ast.jump(:def, :class).first
# =>

If the node types are not present in the AST

ast = YARD.parse("def x; end")
ast.jump(:def)



170
171
172
173
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 170

def jump(*node_types)
  traverse {|child| return(child) if node_types.include?(child.type) }
  self
end

#kw? ⇒ Boolean 



212
213
214
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 212

def kw?
  @kw ||= KEYWORDS.has_key?(type)
end

#line ⇒ Fixnum 



234
235
236
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 234

def line
  line_range && line_range.first
end

#literal? ⇒ Boolean 



207
208
209
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 207

def literal?
  @literal ||= type =~ /_literal$/ ? true : false
end

#pretty_print(q) ⇒ nil 



251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 251

def pretty_print(q)
  objs = [*self.dup, :__last__]
  objs.unshift(type) if type && type != :list

  options = {}
  if @docstring
    options[:docstring] = docstring
  end
  if @source_range || @line_range
    options[:line] = line_range
    options[:source] = source_range
  end
  objs.pop if options.size == 0

  q.group(3, 's(', ')') do
    q.seplist(objs, nil, :each) do |v| 
      if v == :__last__
        q.seplist(options, nil, :each) do |k, v2| 
          q.group(3) do 
            q.text k
            q.group(3) do 
              q.text ': '
              q.pp v2 
            end
          end
        end
      else
        q.pp v 
      end
    end
  end
end

#ref? ⇒ Boolean 



202
203
204
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 202

def ref?
  false
end

#show ⇒ String 



246
247
248
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 246

def show
  "\t#{line}: #{first_line}"
end

#to_s ⇒ Object

Returns the value of attribute source.



45
46
47
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 45

def source
  @source
end

#token? ⇒ Boolean 



196
197
198
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 196

def token?
  @token
end

#traverse {|self,| ... } ⇒ void

This method returns an undefined value.

Traverses the object and yields each node (including descendents) in order.

Yields:

  • each descendent node in order

Yield Parameters:

  • self, (AstNode) —

    or a child/descendent node



185
186
187
188
189
190
191
 
# File 'lib/yard/parser/ruby/ast_node.rb', line 185

def traverse
  nodes = [self]
  nodes.each.with_index do |node, index|
    yield node
    nodes.insert index+1, *node.children
  end
end