Class: Docurium::DocParser

Inherits:
Object
  • Object
show all
Defined in:
lib/docurium/docparser.rb

Instance Method Summary collapse

Instance Method Details

#children(cursor) ⇒ Object 



292
293
294
295
296
297
298
299
300
 
# File 'lib/docurium/docparser.rb', line 292

def children(cursor)
  list = []
  cursor.visit_children do |ccursor, cparent|
    list << ccursor
    :continue
  end

  list
end

#extract_callback_result(type) ⇒ Object 



132
133
134
 
# File 'lib/docurium/docparser.rb', line 132

def extract_callback_result(type)
  type[0..(type.index('(') - 1)].strip
end

#extract_enum(cursor) ⇒ Object 



246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
 
# File 'lib/docurium/docparser.rb', line 246

def extract_enum(cursor)
  subject, desc = extract_subject_desc(cursor.comment)

  decl = []
  cursor.visit_children do |cchild, cparent|
    decl << cchild.spelling
    :continue
  end

  block = decl.join("\n")
  #return the docurium object
  {
    :type => :enum,
    :name => cursor.spelling,
    :description => subject,
    :comments => desc,
    :fields => extract_fields(cursor),
    :block => block,
    :decl => decl,
  }
end

#extract_fields(cursor) ⇒ Object 



226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/docurium/docparser.rb', line 226

def extract_fields(cursor)
  fields = []
  cursor.visit_children do |cchild, cparent|
    field = {
      :type => cchild.type.spelling,
      :name => cchild.spelling,
      :comments => cchild.comment.find_all {|c| c.kind == :comment_paragraph }.map(&:text).join("\n\n")
    }

    if cursor.kind == :cursor_enum_decl
      field.merge!({:value => cchild.enum_value})
    end

    fields << field
    :continue
  end

    fields
end

#extract_function(cursor) ⇒ Object 



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/docurium/docparser.rb', line 156

def extract_function(cursor)
  comment = cursor.comment

  #puts "looking at function #{cursor.spelling}, #{cursor.display_name}"
  cmt = extract_function_comment(comment)
  args = extract_function_args(cursor, cmt)
  #args = args.reject { |arg| arg[:comment].nil? }

  ret = {
    :type => cursor.result_type.spelling,
    :comment => cmt[:return]
  }

  # generate function signature
  sig = args.map { |a| a[:type].to_s }.join('::')

  argline = args.map { |a|
    # pointers don't have a separation between '*' and the name
    if a[:type].end_with? "*"
      "#{a[:type]}#{a[:name]}"
    else
      "#{a[:type]} #{a[:name]}"
    end
  }.join(', ')

  decl = "#{ret[:type]} #{cursor.spelling}(#{argline})"
  body = "#{decl};"

  #puts cursor.display_name
  # Return the format that docurium expects
  {
    :type => :function,
    :name => cursor.spelling,
    :body => body,
    :description => cmt[:description],
    :comments => cmt[:comments],
    :sig => sig,
    :args => args,
    :return => ret,
    :decl => decl,
    :argline => argline
  }
end

#extract_function_args(cursor, cmt) ⇒ Object 



136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/docurium/docparser.rb', line 136

def extract_function_args(cursor, cmt)
  # We only want to look at parm_decl to avoid looking at a return
  # struct as a parameter
  children(cursor)
    .select {|c| c.kind == :cursor_parm_decl }
    .map do |arg|
    {
      :name => arg.display_name,
      :type => arg.type.spelling,
      :comment => cmt[:args][arg.display_name],
    }
  end
end

#extract_function_comment(comment) ⇒ Object 



200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
 
# File 'lib/docurium/docparser.rb', line 200

def extract_function_comment(comment)
  subject, desc = extract_subject_desc(comment)

  args = {}
  (comment.find_all { |cmt| cmt.kind == :comment_param_command }).each do |param|
    args[param.name] = param.comment.strip
  end

  ret = nil
  comment.each do |block|
    next unless block.kind == :comment_block_command
    next unless block.name == "return"

    ret = block.paragraph.text

    break
  end

  {
    :description => subject,
    :comments => desc,
    :args => args,
    :return => ret,
  }
end

#extract_struct(cursor) ⇒ Object 



268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/docurium/docparser.rb', line 268

def extract_struct(cursor)
  subject, desc = extract_subject_desc(cursor.comment)

  values = []
  cursor.visit_children do |cchild, cparent|
    values << "#{cchild.type.spelling} #{cchild.spelling}"
    :continue
  end

  #puts "struct value #{values}"

  rec = {
    :type => :struct,
    :name => cursor.spelling,
    :description => subject,
    :comments => desc,
    :fields => extract_fields(cursor),
    :decl => values,
  }

  rec[:block] = values.join("\n") unless values.empty?
  rec
end

#extract_subject_desc(comment) ⇒ Object 



150
151
152
153
154
 
# File 'lib/docurium/docparser.rb', line 150

def extract_subject_desc(comment)
  subject = comment.child.text
  desc = (comment.find_all { |cmt| cmt.kind == :comment_paragraph }).drop(1).map(&:text).join("\n\n")
  return subject, desc
end

#extract_typedef(cursor) ⇒ Object 



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/docurium/docparser.rb', line 82

def extract_typedef(cursor)
  child = nil
  cursor.visit_children { |c| child = c; :break }
  rec = {
    :name => cursor.spelling,
    :underlying_type => cursor.underlying_type.spelling,
    :tdef => :typedef,
  }

  if not child
    return rec
  end

  #puts "have typedef #{child.kind}, #{cursor.extent.start.line}"
  case child.kind
  when :cursor_type_ref
    #puts "pure typedef, #{cursor.spelling}"
    if child.type.kind == :type_record
      rec[:type] = :struct
      subject, desc = extract_subject_desc(cursor.comment)
      rec[:decl] = cursor.spelling
      rec[:description] = subject
      rec[:comments] = desc
    else
      rec[:name] = cursor.spelling
    end
  when :cursor_enum_decl
    rec.merge! extract_enum(child)
  when :cursor_struct
    #puts "typed struct, #{cursor.spelling}"
    rec.merge! extract_struct(child)
  when :cursor_parm_decl
    rec.merge! extract_function(cursor)
    rec[:type] = :callback
    # this is wasteful, but we don't get the array from outside
    cmt = extract_function_comment(cursor.comment)
    ret = {
           :type => extract_callback_result(rec[:underlying_type]),
           :comment => cmt[:return]
          }
    rec[:return] = ret
  else
    raise "No idea how to handle #{child.kind}"
  end
  # let's make sure we override the empty name the extract
  # functions stored
  rec[:name] = cursor.spelling
  rec
end

#parse_file(orig_filename, files) ⇒ Object

Entry point for this parser Parse ‘filename` out of the hash `files`



10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/docurium/docparser.rb', line 10

def parse_file(orig_filename, files)

  # unfortunately Clang wants unsaved files to exist on disk, so
  # we need to create at least empty files for each unsaved file
  # we're given.

  tmpdir = Dir.mktmpdir()

  unsaved = files.map do |name, contents|
    full_path = File.join(tmpdir, name)
    dirname = File.dirname(full_path)
    FileUtils.mkdir_p(dirname) unless Dir.exists? dirname
    File.new(full_path, File::CREAT).close()

    UnsavedFile.new(full_path, contents)
  end

  # Override the path we want to filter by
  filename = File.join(tmpdir, orig_filename)
  tu = Index.new.parse_translation_unit(filename, [], unsaved, {:detailed_preprocessing_record => 1})

  FileUtils.remove_entry(tmpdir)

  cursor = tu.cursor

  recs = []

  cursor.visit_children do |cursor, parent|
    #puts "visiting #{cursor.kind} - #{cursor.spelling}"
    location = cursor.location
    next :continue if location.file == nil
    next :continue unless location.file == filename

    #puts "for file #{location.file} #{cursor.kind} #{cursor.spelling} #{cursor.comment.kind} #{location.line}"
    #cursor.visit_children do |c|
    #  puts "  child #{c.kind}, #{c.spelling}, #{c.comment.kind}"
    #  :continue
    #end

    next :continue if cursor.comment.kind == :comment_null
    next :continue if cursor.spelling == ""

    extent = cursor.extent
    rec = {
      :file => orig_filename,
      :line => extent.start.line,
      :lineto => extent.end.line,
      :tdef => nil,
    }

    case cursor.kind
    when :cursor_function
      #puts "have function"
      rec.merge! extract_function(cursor)
    when :cursor_enum_decl
      rec.merge! extract_enum(cursor)
    when :cursor_struct
      #puts "raw struct"
      rec.merge! extract_struct(cursor)
    when :cursor_typedef_decl
      rec.merge! extract_typedef(cursor)
    else
      raise "No idea how to deal with #{cursor.kind}"
    end

    recs << rec
    :continue
  end

  recs
end