Class: TomDoc::SourceParser

Inherits:
Object
  • Object
show all
Defined in:
lib/tomdoc/source_parser.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ SourceParser

Each instance of SourceParser accumulates scopes with each parse, making it easy to parse an entire project in chunks but more difficult to parse disparate files in one go. Create separate instances for separate global scopes.

Returns an instance of TomDoc::SourceParser



21
22
23
24
25
 
# File 'lib/tomdoc/source_parser.rb', line 21

def initialize(options = {})
  @options = {}
  @parser  = RubyParser.new
  @scopes  = {}
end

Instance Attribute Details

#options ⇒ Object

Returns the value of attribute options.



13
14
15
 
# File 'lib/tomdoc/source_parser.rb', line 13

def options
  @options
end

#parser ⇒ Object

Returns the value of attribute parser.



13
14
15
 
# File 'lib/tomdoc/source_parser.rb', line 13

def parser
  @parser
end

#scopes ⇒ Object

Returns the value of attribute scopes.



13
14
15
 
# File 'lib/tomdoc/source_parser.rb', line 13

def scopes
  @scopes
end

Class Method Details

.parse(text) ⇒ Object

Converts Ruby code into a data structure.

text - A String of Ruby code.

Returns a Hash with each key a namespace and each value another

Hash or a TomDoc::Scope.



9
10
11
 
# File 'lib/tomdoc/source_parser.rb', line 9

def self.parse(text)
  new.parse(text)
end

Instance Method Details

#args_for_node(node) ⇒ Object

Given a method sexp, returns an array of the args.



141
142
143
 
# File 'lib/tomdoc/source_parser.rb', line 141

def args_for_node(node)
  Array(node)[1..-1].select { |arg| arg.is_a? Symbol }
end

#parse(text) ⇒ Object

Converts Ruby code into a data structure. Note that at the instance level scopes accumulate, which makes it easy to parse multiple files in a single project but harder to parse files that have no connection.

text - A String of Ruby code.

Examples

@parser = TomDoc::SourceParser.new
files.each do |file|
  @parser.parse(File.read(file))
end
pp @parser.scopes

Returns a Hash with each key a namespace and each value another

Hash or a TomDoc::Scope.



50
51
52
53
 
# File 'lib/tomdoc/source_parser.rb', line 50

def parse(text)
  process(tokenize(sexp(text)))
  @scopes
end

#process(ast, scope = nil) ⇒ Object

Converts a tokenized Array of classes, modules, and methods into Scopes and Methods, adding them to the @scopes instance variable as it works.

ast - Tokenized Array produced by calling ‘tokenize`. scope - An optional Scope object for nested classes or modules.

Returns nothing.



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/tomdoc/source_parser.rb', line 72

def process(ast, scope = nil)
  case Array(ast)[0]
  when :module, :class
    name = ast[1]
    new_scope = Scope.new(name, ast[2])

    if scope
      scope.scopes[name] = new_scope
    elsif @scopes[name]
      new_scope = @scopes[name]
    else
      @scopes[name] = new_scope
    end

    process(ast[3], new_scope)
  when :imethod
    ast.shift
    scope.instance_methods << Method.new(*ast)
  when :cmethod
    ast.shift
    scope.class_methods << Method.new(*ast)
  when Array
    ast.map { |a| process(a, scope) }
  end
end

#reset ⇒ Object

Resets the state of the parser to a pristine one. Maintains options.

Returns nothing.



30
31
32
 
# File 'lib/tomdoc/source_parser.rb', line 30

def reset
  initialize(@options)
end

#sexp(text) ⇒ Object

Converts Ruby sourcecode into an AST.

text - A String of Ruby source.

Returns a Sexp representing the AST.



60
61
62
 
# File 'lib/tomdoc/source_parser.rb', line 60

def sexp(text)
  @parser.parse(text)
end

#tokenize(node) ⇒ Object

Converts a Ruby AST-style Sexp into an Array of more useful tokens.

node - A Ruby AST Sexp or Array

Examples

[:module, :Math, "",
  [:class, :Multiplexer, "# Class Comment",
    [:cmethod,
      :multiplex, "# Class Method Comment", [:text]],
    [:imethod,
      :multiplex, "# Instance Method Comment", [:text, :count]]]]

# In others words:
# [ :type, :name, :comment, other ]

Returns an Array in the above format.



115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/tomdoc/source_parser.rb', line 115

def tokenize(node)
  case Array(node)[0]
  when :module
    name = node[1]
    [ :module, name, node.comments, tokenize(node[2]) ]
  when :class
    name = node[1]
    [ :class, name, node.comments, tokenize(node[3]) ]
  when :defn
    name = node[1]
    args = args_for_node(node[2])
    [ :imethod, name, node.comments, args ]
  when :defs
    name = node[2]
    args = args_for_node(node[3])
    [ :cmethod, name, node.comments, args ]
  when :block
    tokenize(node[1..-1])
  when :scope
    tokenize(node[1])
  when Array
    node.map { |n| tokenize(n) }.compact
  end
end