/cmpi-bindings-0.5.2/swig/ruby/parse_swig.rb
Ruby | 667 lines | 551 code | 30 blank | 86 comment | 12 complexity | b31bd2b8efd88a71abf172dca9ae6290 MD5 | raw file
Possible License(s): BSD-3-Clause
- # parse_swig.rb
- #
- # A rdoc parser for SWIG .i files
- #
- # Based on parse_c.rb from the Ruby-1.8.7 distribution.
- #
- # Most of (my) SWIG binding descriptions have a toplevel .i file
- # describing the module (%module) and generic definitions. The various
- # classes are spread into separate .i files, all '%include'd by the main
- # file.
- #
- # parse_swig.rb depends on this (a single module, with classes below it)
- # layout and needs the main file (the one with %module) as first input
- # file. A second parse of this file is ignored.
- #
- # == Usage
- # rdoc module.i *.i
- #
- # !! ensure that the file containing the %module directive
- # !! is parsed first
- #
- #
- # == Installation:
- #
- # Getting this file into rdoc without changing rdoc itself is a bit tricky
- # but doable, thanks to the dynamic nature of Ruby.
- #
- # One just needs to load parse_swig.rb before the original rdoc. The tricky
- # part is that 'require' in Ruby either loads an .rb or .so file, but
- # /usr/bin/rdoc does not have an extension.
- # This is solved by a creating a temporary symlink ./rdoc.rb -> /usr/bin/rdoc
- # and wrapping this into a new 'rdoc' to be called on the command line:
- #
- # home = File.dirname __FILE__
- # $:.unshift(home)
- # new_rdoc = home+"/rdoc.rb"
- # File.symlink("/usr/bin/rdoc", new_rdoc) unless File.symlink?(new_rdoc)
- # begin
- # require 'parse_swig.rb'
- # require 'rdoc'
- # ensure
- # File.delete new_rdoc # Discard the symlink
- # end
- #
- require "rdoc/code_objects"
- require "rdoc/parsers/parserfactory"
- require "rdoc/options"
- require "rdoc/rdoc"
- module RDoc
- class Context
- attr_accessor :body
- end
-
- class NormalClass
- attr_accessor :extend_name
- end
- class NormalModule
- attr_accessor :extend_name
- end
- class AnyMethod
- attr_accessor :orig_name
- end
-
- class Swig_Parser
- attr_accessor :progress
- extend ParserFactory
- parse_files_matching(/\.i$/)
- @@known_bodies = {}
- @@files_seen = Array.new
- @@module_name = nil
-
- # prepare to parse a SWIG file
- # RHEL4 has Ruby 1.8.1 which does not provide stats
- def initialize(top_level, file_name, body, options, stats = nil)
- @known_classes = KNOWN_CLASSES.dup
- @body = handle_tab_width(handle_ifdefs_in(body))
- @options = options
- @stats = stats
- @top_level = top_level
- @classes = Hash.new
- @file_dir = File.dirname(file_name)
- @progress = $stderr unless options.quiet
- @file_name = file_name
- end
- # Extract the classes/modules and methods from a C file
- # and return the corresponding top-level object
- def scan
- unless @@files_seen.include? @file_name
- @@files_seen << @file_name
- remove_commented_out_lines
- if module_name = do_module
- @@module_name = module_name
- do_methods module_name
- else
- do_classes
- @classes.keys.each do |c|
- do_constants c
- do_methods c
- do_includes
- do_aliases c
- end
- end
- else
- puts "Seen #{@file_name} before" unless @options.quiet
- end
- @top_level
- end
- #######
- private
- #######
- def progress(char)
- unless @options.quiet
- @progress.print(char)
- @progress.flush
- end
- end
- def warn(msg)
- $stderr.puts
- $stderr.puts msg
- $stderr.flush
- end
- def remove_private_comments(comment)
- comment.gsub!(/\/?\*--(.*?)\/?\*\+\+/m, '')
- comment.sub!(/\/?\*--.*/m, '')
- end
- ##
- # removes lines that are commented out that might otherwise get picked up
- # when scanning for classes and methods
- def remove_commented_out_lines
- @body.gsub!(%r{//.*rb_define_}, '//')
- end
- ##
- # handle class or module
- #
- # return enclosure
- #
- def handle_class_module(class_mod, class_name, options = {})
- # puts "handle_class_module(#{class_mod}, #{class_name})"
- progress(class_mod[0, 1])
- parent = options[:parent]
- parent_name = @known_classes[parent] || parent
- if @@module_name
- enclosure = @top_level.find_module_named(@@module_name)
- else
- enclosure = @top_level
- end
- if RUBY_VERSION == "1.8.1"
- return nil unless enclosure # workaround for RHEL4
- end
- if class_mod == "class"
- cm = enclosure.add_class(NormalClass, class_name, parent_name)
- @stats.num_classes += 1 if @stats
- else
- cm = enclosure.add_module(NormalModule, class_name)
- @stats.num_modules += 1 if @stats
- end
- cm.record_location(enclosure.toplevel)
- cm.body = options[:content]
- cm.extend_name = options[:extend_name] || class_name
-
- find_class_comment(class_name, cm)
- @classes[class_name] = cm
- @known_classes[class_name] = cm.full_name
- end
- ##
- # Look for class or module documentation above %extend +class_name+
- # in a Document-class +class_name+ (or module) comment or above an
- # rb_define_class (or module). If a comment is supplied above a matching
- # Init_ and a rb_define_class the Init_ comment is used.
- #
- # /*
- # * This is a comment for Foo
- # */
- # %extend Foo {
- # ...
- # }
- #
- def find_class_comment(class_name, class_meth)
- # puts "find_class_comment(#{class_name}, #{class_meth.extend_name})"
- comment = nil
- if @body =~ %r{((?>/\*.*?\*/\s+))
- %extend\s+#{class_meth.extend_name}\s*\{}xm
- comment = $1
- elsif @body =~ %r{Document-(class|module):\s#{class_name}\s*?\n((?>.*?\*/))}m
- comment = $2
- end
- class_meth.comment = mangle_comment(comment) if comment
- end
-
- ############################################################
- #
- # Find module
- # return module_name (or nil)
- #
- def do_module
- module_name = nil
- @body.scan(/^%module\s*(\w+)/mx) do
- |name|
- module_name = name.to_s
- module_name.capitalize! unless module_name[0,1] =~ /[A-Z_]/
- handle_class_module("module", module_name)
- break
- end
- module_name
- end
- #
- # Find and handle classes within +module_name+
- #
- # return Array of classes
- #
- def do_classes
- # look for class renames like
- # %rename(Solvable) _Solvable;
- # typedef struct _Solvable {} XSolvable; /* expose XSolvable as 'Solvable' */
- extends = Hash.new
- @body.scan(/^%rename\s*\(([^\"\)]+)\)\s+([_\w]+);/) do |class_name, struct_name|
- # puts "rename #{class_name} -> #{struct_name}"
- extend_name = struct_name.to_s
- @body.scan(/typedef\s+struct\s+#{struct_name}\s*\{[^}]*\}\s*(\w+);/) do |ename|
- extend_name = ename.to_s
- end
-
- # puts "extend #{extend_name}, class #{class_name}, struct #{struct_name}"
- # find the corresponding '%extend' directive
- @body.scan(/^%extend\s+(#{extend_name}|#{struct_name})\s*\{(.*)\}/mx) do |name,content|
- # now check if we have multiple %extend, the regexp above is greedy and will match all of them
- while content.to_s =~ /^%extend/
- content = $` # discard %extend and everything behind
- end
- extends[name] = true
- cn = class_name.to_s
- cn.capitalize! unless cn[0,1] =~ /[A-Z_]/
- handle_class_module("class", cn, :parent => "rb_cObject", :content => content.to_s, :extend_name => name)
- end
- end
- @body.scan(/^%extend\s*(\w+)\s*\{(.*)\}/mx) do |class_name,content|
- cn = class_name.to_s
- unless extends[cn]
- # puts "Class #{cn}"
- cn.capitalize! unless cn[0,1] =~ /[A-Z_]/
- handle_class_module("class", cn, :parent => "rb_cObject", :content => content)
- extends[cn] = true
- end
- end
- end
- ###########################################################
- #
- # Find
- # %constant +type+ +name+ = +value+
- #
- def do_constants class_name
- c = find_class class_name
- c.body.scan(%r{%constant\s+(\w+)\s+(\w+)\s*=\s*(\w+)\s*;}xm) do
- |type, const_name, definition|
- # swig puts all constants under module
- handle_constants(type, @@module_name, const_name, definition)
- end
- end
-
- ############################################################
-
- #
- # Find and handle all methods for +module_name+::+class_name+
- #
- # Look for C-Function headers within the class content
- # const? +type+ +name+ ( +args+ ) {
- # and honor
- # %rename "+new_name+" +old_name+ ;
- #
- # Module level methods have 'static' prototypes of C functions.
- # e.g. static type name(args);
- #
- def do_methods class_name
- renames = Hash.new
- c = find_class class_name
- body = c.body || @body
- extend_name = c.extend_name
- body.scan(%r{%rename\s*\(\s*"([^"]+)"\s*\)\s*(\w+)}m) do #"
- |meth_name,orig_name|
- meth_name = meth_name.to_s
- orig_name = orig_name.to_s
- renames[orig_name] = meth_name
- end
- # Find function definitions of the format
- # <type> [*]? <name> ( <args> ) {
- #
- # puts "#{module_name}::#{class_name} methods ?"
- # Find class constructor as 'new'
- body.scan(%r{^\s+#{extend_name}\s*\(([^\)]*)\)\s*\{}m) do
- |args|
- handle_method(class_name, class_name, "initialize", nil, (args.to_s.split(",")||[]).size, nil)
- end if extend_name
-
- body.scan(%r{static\s+((const\s+)?\w+)([\s\*]+)(\w+)\s*\(([^\)]*)\)\s*;}) do
- |const,type,pointer,meth_name,args|
- # puts "-> const #{const}:type #{type}:pointer #{pointer}:name #{meth_name} (args #{args} )\n#{$&}\n\n"
- meth_name = orig_name = meth_name.to_s
- meth_name = renames[meth_name] || meth_name
- handle_method(type, class_name||@@module_name, meth_name, nil, (args.split(",")||[]).size, orig_name)
- end
- body.scan(%r{((const\s+)?\w+)([ \t\*]+)(\w+)\s*\(([^\)]*)\)\s*\{}m) do
- |const,type,pointer,meth_name,args|
- next unless meth_name
- next if meth_name =~ /~/
- type = "string" if type =~ /char/ && pointer =~ /\*/
- # puts "-> const #{const}:type #{type}:pointer #{pointer}:name #{meth_name} (args #{args} )\n#{$&}\n\n" if meth_name == "if"
- meth_name = orig_name = meth_name.to_s
- meth_name = renames[meth_name] || meth_name
- handle_method(type, class_name, meth_name, nil, (args.split(",")||[]).size, orig_name)
- end
- end
- ############################################################
-
- #
- # Find and handle method aliases
- #
- # %alias +old_name+ "+new_name+" ;
- #
- def do_aliases class_name
- c = find_class class_name
- c.body.scan(%r{%alias\s+(\w+)\s+"([^"]+)"\s*;}m) do #"
- |old_name, new_name|
- @stats.num_methods += 1 if @stats
- raise "Unknown class '#{class_name}'" unless @known_classes[class_name]
- class_obj = find_class(class_name)
- class_obj.add_alias(Alias.new("", old_name, new_name, ""))
- end
- end
- ##
- # Adds constant comments. By providing some_value: at the start ofthe
- # comment you can override the C value of the comment to give a friendly
- # definition.
- #
- # /* 300: The perfect score in bowling */
- # rb_define_const(cFoo, "PERFECT", INT2FIX(300);
- #
- # Will override +INT2FIX(300)+ with the value +300+ in the output RDoc.
- # Values may include quotes and escaped colons (\:).
- def handle_constants(type, class_name, const_name, definition)
- class_obj = find_class(class_name)
- unless class_obj
- warn("Enclosing class/module for '#{const_name}' not known")
- return
- end
-
- comment = find_const_comment(type, const_name)
- # In the case of rb_define_const, the definition and comment are in
- # "/* definition: comment */" form. The literal ':' and '\' characters
- # can be escaped with a backslash.
- if type.downcase == 'const' then
- elements = mangle_comment(comment).split(':')
- if elements.nil? or elements.empty? then
- con = Constant.new(const_name, definition, mangle_comment(comment))
- else
- new_definition = elements[0..-2].join(':')
- if new_definition.empty? then # Default to literal C definition
- new_definition = definition
- else
- new_definition.gsub!("\:", ":")
- new_definition.gsub!("\\", '\\')
- end
- new_definition.sub!(/\A(\s+)/, '')
- new_comment = $1.nil? ? elements.last : "#{$1}#{elements.last.lstrip}"
- con = Constant.new(const_name, new_definition,
- mangle_comment(new_comment))
- end
- else
- con = Constant.new(const_name, definition, mangle_comment(comment))
- end
- class_obj.add_constant(con)
- end
- ##
- # Finds a comment matching +type+ and +const_name+ either above the
- # comment or in the matching Document- section.
- def find_const_comment(type, const_name)
- if @body =~ %r{((?>^\s*/\*.*?\*/\s+))
- %constant\s+(\w+)\s+#{const_name}\s*=\s*(\w+)\s*;}xmi
- $1
- elsif @body =~ %r{Document-(?:const|global|variable):\s#{const_name}\s*?\n((?>.*?\*/))}m
- $1
- else
- ''
- end
- end
- ###########################################################
- def handle_attr(var_name, attr_name, reader, writer)
- rw = ''
- if reader
- #@stats.num_methods += 1
- rw << 'R'
- end
- if writer
- #@stats.num_methods += 1
- rw << 'W'
- end
- class_name = @known_classes[var_name]
- return unless class_name
-
- class_obj = find_class(class_name)
- if class_obj
- comment = find_attr_comment(attr_name)
- unless comment.empty?
- comment = mangle_comment(comment)
- end
- att = Attr.new('', attr_name, rw, comment)
- class_obj.add_attribute(att)
- end
- end
- ###########################################################
- def find_attr_comment(attr_name)
- if @body =~ %r{((?>/\*.*?\*/\s+))
- rb_define_attr\((?:\s*(\w+),)?\s*"#{attr_name}"\s*,.*?\)\s*;}xmi
- $1
- elsif @body =~ %r{Document-attr:\s#{attr_name}\s*?\n((?>.*?\*/))}m
- $1
- else
- ''
- end
- end
- ###########################################################
- def handle_method(type, class_name, meth_name,
- meth_body, param_count, orig_name)
- progress(".")
- class_obj = find_class(class_name)
- return nil unless class_obj
-
- seen_before = class_obj.method_list.find { |meth| meth.name == meth_name }
- return nil if seen_before
-
- @stats.num_methods += 1 if @stats
- if meth_name == "initialize"
- meth_name = "new"
- type = "singleton_method"
- end
- meth_obj = AnyMethod.new("", meth_name)
- meth_obj.singleton = %w{singleton_method module_function}.include?(type)
- meth_obj.orig_name = orig_name || meth_name
-
- p_count = (Integer(param_count) rescue -1)
-
- if p_count < 0
- meth_obj.params = "(...)"
- elsif p_count == 0
- meth_obj.params = "()"
- else
- meth_obj.params = "(" +
- (1..p_count).map{|i| "p#{i}"}.join(", ") +
- ")"
- end
-
- body = find_class(class_name).body || @body
-
- if find_body(class_name, meth_name, meth_obj, body) and meth_obj.document_self
- class_obj.add_method(meth_obj)
- end
- meth_obj
- end
-
- ############################################################
- # Find the C code corresponding to a Ruby method
- def find_body(class_name, meth_name, meth_obj, body, quiet = false)
- case body
- when %r{((?>/\*.*?\*/\s*))(?:static\s+)?(?:const\s+)?(\w+)[\s\*]+#{meth_obj.orig_name || meth_name}
- \s*(\(.*?\)).*?^}xm
- comment, params = $1, $2
- body_text = $&
- remove_private_comments(comment) if comment
- # see if we can find the whole body
-
- re = Regexp.escape(body_text) + '[^(]*^\{.*?^\}'
- if Regexp.new(re, Regexp::MULTILINE).match(body)
- body_text = $&
- end
- # The comment block may have been overridden with a
- # 'Document-method' block. This happens in the interpreter
- # when multiple methods are vectored through to the same
- # C method but those methods are logically distinct (for
- # example Kernel.hash and Kernel.object_id share the same
- # implementation
- override_comment = find_override_comment(meth_obj.name)
- comment = override_comment if override_comment
- find_modifiers(comment, meth_obj) if comment
-
- # meth_obj.params = params
- meth_obj.start_collecting_tokens
- meth_obj.add_token(RubyToken::Token.new(1,1).set_text(body_text))
- meth_obj.comment = mangle_comment(comment)
- when %r{((?>/\*.*?\*/\s*))^\s*\#\s*define\s+#{meth_name}\s+(\w+)}m
- comment = $1
- find_body(class_name, $2, meth_obj, body, true)
- find_modifiers(comment, meth_obj)
- meth_obj.comment = mangle_comment(comment) + meth_obj.comment
- when %r{^\s*\#\s*define\s+#{meth_name}\s+(\w+)}m
- unless find_body(class_name, $1, meth_obj, body, true)
- warn "No definition for #{meth_name}" unless quiet
- return false
- end
- else
- if (meth_name == "new")
- # find constructor definition
- extend_name = find_class(class_name).extend_name
- if body =~ %r{((?>/\*.*?\*/\s*))\s*#{extend_name}\s*(\([^)]*\))}xm
- comment = $1
- find_modifiers(comment, meth_obj)
- meth_obj.comment = mangle_comment(comment) + meth_obj.comment
- # No body, but might still have an override comment
- comment = find_override_comment(meth_obj.name)
- end
- end
- if comment
- find_modifiers(comment, meth_obj)
- meth_obj.comment = mangle_comment(comment)
- else
- # warn "Dummy definition for #{meth_name}" unless quiet
- # find_modifiers("unknown", meth_obj)
- # meth_obj.comment = mangle_comment("unknown") + meth_obj.comment
- end
- end
- true
- end
- ##
- # If the comment block contains a section that looks like:
- #
- # call-seq:
- # Array.new
- # Array.new(10)
- #
- # use it for the parameters.
- def find_modifiers(comment, meth_obj)
- if comment.sub!(/:nodoc:\s*^\s*\*?\s*$/m, '') or
- comment.sub!(/\A\/\*\s*:nodoc:\s*\*\/\Z/, '')
- meth_obj.document_self = false
- end
- if comment.sub!(/call-seq:(.*?)^\s*\*?\s*$/m, '') or
- comment.sub!(/\A\/\*\s*call-seq:(.*?)\*\/\Z/, '')
- seq = $1
- seq.gsub!(/^\s*\*\s*/, '')
- meth_obj.call_seq = seq
- end
- end
- ############################################################
- def find_override_comment(meth_name)
- name = Regexp.escape(meth_name)
- if @body =~ %r{Document-method:\s#{name}\s*?\n((?>.*?\*/))}m
- $1
- end
- end
- ##
- # Look for includes of the form:
- #
- # %mixin class "module";
- def do_includes
- @body.scan(/%mixin\s+(\w+)\s+"([^"]+)"s*;/) do |c,m| #"
- if cls = @classes[c]
- m = @known_classes[m] || m
- cls.add_include(Include.new(m, ""))
- end
- end
- end
- ##
- # Remove the /*'s and leading asterisks from C comments
-
- def mangle_comment(comment)
- comment.sub!(%r{/\*+}) { " " * $&.length }
- comment.sub!(%r{\*+/}) { " " * $&.length }
- comment.gsub!(/^[ \t]*\*/m) { " " * $&.length }
- comment
- end
- def find_class(name)
- @classes[name] || @top_level.find_module_named(name) || raise("No such class '#{name}'")
- end
- def handle_tab_width(body)
- if /\t/ =~ body
- tab_width = Options.instance.tab_width
- body.split(/\n/).map do |line|
- 1 while line.gsub!(/\t+/) { ' ' * (tab_width*$&.length - $`.length % tab_width)} && $~ #`
- line
- end .join("\n")
- else
- body
- end
- end
- ##
- # Removes #ifdefs that would otherwise confuse us
-
- def handle_ifdefs_in(body)
- # remove all %{...%}
- while body =~ /^%\{/
- before = $` # keep whats before %{
- $' =~ /^%\}/ # scan the rest for %} '
- body = before + $' # keep whats after %} '
- end
- body.gsub(/^#ifdef HAVE_PROTOTYPES.*?#else.*?\n(.*?)#endif.*?\n/m) { $1 }
- end
-
- end
- end