Class: Docurium::DocParser

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

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(files, opts = {}) ⇒ DocParser

Returns a new instance of DocParser.



40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/docurium/docparser.rb', line 40

def initialize(files, opts = {})
  # 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.

  prefix = (opts[:prefix] ? opts[:prefix] + "-" : nil)
  @tmpdir = Dir.mktmpdir(prefix)
  @unsaved = files.map do |name, contents|
    full_path = File.join(@tmpdir, name)
    dirname = File.dirname(full_path)
    FileUtils.mkdir_p(dirname) unless Dir.exist? dirname
    File.new(full_path, File::CREAT).close()
    UnsavedFile.new(full_path, contents)
  end
end

Class Method Details

.with_files(files, opts = {}) {|parser| ... } ⇒ Object

Yields:

  • (parser) 


34
35
36
37
38
 
# File 'lib/docurium/docparser.rb', line 34

def self.with_files(files, opts = {})
  parser = self.new(files, opts)
  yield parser
  parser.cleanup!
end

Instance Method Details

#children(cursor) ⇒ Object 



361
362
363
364
365
366
367
368
369
 
# File 'lib/docurium/docparser.rb', line 361

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

  list
end

#cleanup! ⇒ Object 



56
57
58
 
# File 'lib/docurium/docparser.rb', line 56

def cleanup!
  FileUtils.remove_entry(@tmpdir)
end

#extract_callback_result(type) ⇒ Object 



186
187
188
 
# File 'lib/docurium/docparser.rb', line 186

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

#extract_enum(cursor) ⇒ Object 



315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
 
# File 'lib/docurium/docparser.rb', line 315

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 



295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
 
# File 'lib/docurium/docparser.rb', line 295

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 



213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
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 213

def extract_function(cursor)
  comment = cursor.comment

  $buggy_functions = %w()
  debug_set ($buggy_functions.include? cursor.spelling)
  if debug_enabled
    puts "\tlooking at function #{cursor.spelling}, #{cursor.display_name}"
    puts "\tcomment: #{comment}, #{comment.kind}"
    cursor.visit_children do |cur, parent|
      puts "\t\tchild: #{cur.spelling}, #{cur.kind}"
      :continue
    end
  end

  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};"

  debug_restore
  #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 



190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/docurium/docparser.rb', line 190

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 



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

def extract_function_comment(comment)
  subject, desc = extract_subject_desc(comment)
  debug "\t\textract_function_comment: #{comment}, #{comment.kind}, #{subject}, #{desc}"

  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 



337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
 
# File 'lib/docurium/docparser.rb', line 337

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

  debug "\tstruct 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 



204
205
206
207
208
209
210
211
 
# File 'lib/docurium/docparser.rb', line 204

def extract_subject_desc(comment)
  subject = comment.child.text
  debug "\t\tsubject: #{subject}"
  paras = comment.find_all { |cmt| cmt.kind == :comment_paragraph }.drop(1).map { |p| p.text }
  desc = paras.join("\n\n")
  debug "\t\tdesc: #{desc}"
  return subject, desc
end

#extract_typedef(cursor) ⇒ Object 



136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
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
 
# File 'lib/docurium/docparser.rb', line 136

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

#find_clang_includes ⇒ Object

The include directory where clang has its basic type definitions is not included in our default search path, so as a workaround we execute clang in verbose mode and grab its include paths from the output.



12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/docurium/docparser.rb', line 12

def find_clang_includes
  @includes ||=
    begin
      clang = if ENV["LLVM_CONFIG"]
        bindir = `#{ENV["LLVM_CONFIG"]} --bindir`.strip
        "#{bindir}/clang"
      else
        "clang"
      end

      output, _status = Open3.capture2e("#{clang} -v -x c -", :stdin_data => "")
      includes = []
      output.each_line do |line|
        if line =~ %r{^\s+/(.*usr|.*lib/clang.*)/include}
          includes << line.strip
        end
      end

      includes
    end
end

#parse_file(orig_filename, opts = {}) ⇒ Object

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



62
63
64
65
66
67
68
69
70
71
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
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
131
132
133
134
 
# File 'lib/docurium/docparser.rb', line 62

def parse_file(orig_filename, opts = {})

  includes = find_clang_includes + [@tmpdir]

  # Override the path we want to filter by
  filename = File.join(@tmpdir, orig_filename)
  debug_enable if opts[:debug]
  debug "parsing #{filename} #{@tmpdir}"
  args = includes.map { |path| "-I#{path}" }
  args << '-ferror-limit=1'

  tu = Index.new(true, true).parse_translation_unit(filename, args, @unsaved, {:detailed_preprocessing_record => 1})

  recs = []

  tu.cursor.visit_children do |cursor, parent|
    location = cursor.location
    next :continue if location.file == nil
    next :continue unless location.file == filename

    loc = "%d:%d-%d:%d" % [cursor.extent.start.line, cursor.extent.start.column, cursor.extent.end.line, cursor.extent.end.column]
    debug "#{cursor.location.file}:#{loc} - visiting #{cursor.kind}: #{cursor.spelling}, comment is #{cursor.comment.kind}"

    #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,
    }

    extract = case cursor.kind
    when :cursor_function
      debug "have function #{cursor.spelling}"
      rec.update extract_function(cursor)
    when :cursor_enum_decl
      debug "have enum #{cursor.spelling}"
      rec.update extract_enum(cursor)
    when :cursor_struct
      debug "have struct #{cursor.spelling}"
      rec.update extract_struct(cursor)
    when :cursor_typedef_decl
      debug "have typedef #{cursor.spelling} #{cursor.underlying_type.spelling}"
      rec.update extract_typedef(cursor)
    else
      raise "No idea how to deal with #{cursor.kind}"
    end

    rec.merge! extract

    recs << rec
    :continue
  end

  if debug_enabled
    puts "parse_file: parsed #{recs.size} records for #{filename}:"
    recs.each do |r|
      puts "\t#{r}"
    end
  end

  debug_restore

  recs
end