doxyparser 1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 529b48f43c4fd9b2bbc9acb11ab140d9e6150e09
+  data.tar.gz: df41fcf999c92693df3cf2f9dfee73f1b1b095ce
+SHA512:
+  metadata.gz: 9a22858cbfdfe61b3d7248736ccbdc7f8ca22f03c415e6f30905e10ea3a820ce1dbb2db4e51e6fb0f307463422aa154eb24194bf8458fa4ac8cd7d5da6bcbc94
+  data.tar.gz: 8bec965f048166cc90ac92dcd2fb7beede9ea6a9e1b0e5cee343d6c1753918d9305971ca2b3c8fcc6613199d51089faedb61f7497a14047befb4958804b6cf8d

data/MIT_LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2013 David Fuenmayor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,271 @@
+# Doxyparser
+
+Ruby Gem for parsing C++ header files.
+
+This library is based on Nokogiri (http://nokogiri.org) and takes as input the xml files generated by Doxygen (www.doxygen.org).
+
+Using Doxygen allows us to parse even a set of non-compilable include files. This is very useful in case you need to parse only a subset of a big library which won't normally compile because of being incomplete or needing further build configuration (e.g Makefiles, VS, SCons, etc).
+
+By using other tools which rely on a real C/C++ processor like gccxml or swig, you would normally get lots of compilation-related errors (which is undesired because we don't want to compile anything!!). Doxyparser is, in such cases, the lean alternative.
+
+
+Install
+--------
+
+```shell
+gem install doxyparser
+```
+or add the following line to Gemfile:
+
+```ruby
+gem 'doxyparser'
+```
+and run `bundle install` from your shell.
+
+In order to use Doxyparser you need to first install Doxygen (www.doxygen.org) in your computer and Nokogiri (http://nokogiri.org)
+
+Generating intermediate XML representation
+------------------------------------------
+
+Generate Doxygen documentation for a set of header files:
+
+```ruby
+Doxyparser::gen_xml_docs('/path/to/c++/files', '/desired/path/to/doxygen/docs')
+```
+
+The first argument is a directory where the target c++ files are (normally .h header files)
+The second argument is a directory where the doxygen generated documentation will be created. It will contain afterwards one or two subdirectories: 'xml' and 'html' (according to the value of the gen_html flag)
+
+There are other three optional arguments you can use. You have access to the console output too.
+
+```ruby
+output = Doxyparser::gen_xml_docs('/path/to/c++/files', '/desired/path/to/doxygen/docs', read_recursively?, ['path/to/system/include/dirs'], gen_html?)
+```
+
+If you already have the needed XMLs, you can skip this step. Keep in mind that the EXTRACT_ALL = true flag in the Doxyfile must be set in order to accurately parse the files.
+
+Parsing intermediate XMLs
+--------------------------
+
+Doxyparser uses Nokogiri under the hood to parse and query the Doxygen generated XMLs. Therefore we need the path to the directory containing those files, as generated with the former command. For instance: 
+
+```ruby
+xml_dir= '/desired/path/to/doxygen/docs/xml'
+```
+
+Doxygen generates a XML file for each namespace, class, struct and file in the given directory. Now we can parse them:
+
+```ruby
+namespace = Doxyparser::parse_namespace("MyNamespace", xml_dir) # Instance of Doxyparser::Namespace
+clazz = Doxyparser::parse_class("MyNamespace::MyClass", xml_dir) # Instance of Doxyparser::Class
+struct = Doxyparser::parse_struct("MyNamespace::MyClass::InnerStruct", xml_dir) # Instance of Doxyparser::Struct
+hfile = Doxyparser::parse_file("test.h", xml_dir) # Instance of Doxyparser::HFile
+```
+
+Each of them will have following attributes:
+
+```ruby
+struct.name # == 'MyNamespace::MyClass::InnerStruct'
+struct.basename # == 'InnerStruct'
+struct.dir # == xml_dir == '/desired/path/to/doxygen/docs/xml'
+struct.xml_path # == '/desired/path/to/doxygen/docs/xml/structMyNamespace_1_1MyClass_1_1InnerStruct.xml'
+```
+
+Querying Members
+-----------------
+
+Namespaces
+-----------
+
+namespace_classes = namespace.classes 		# List of Doxyparser::Class
+namespace_structs = namespace.structs 		# List of Doxyparser::Struct
+inner_namespaces = namespace.innernamespaces 	# List of Doxyparser::Namespace
+namepace_enums = namespace.enums 				# List of Doxyparser::Enum
+namespace_variables = namespace.variables 		# List of Doxyparser::Variable
+namespace_functions = namespace.functions 		# List of Doxyparser::Function
+namespace_typedefs = namespace.typedefs 		# List of Doxyparser::Typedef
+
+...and:
+
+```ruby
+namespace_classes[0].parent == namespace # true
+```
+
+This last also applies for every other member (functions, enums, etc)
+
+If you only want to query a subset of the namespace members, provide a list of strings or regexes as a parameter:
+
+```ruby
+expected_functions=['operator>', 'operator<=', 'intersect', 'advanceRawPointer', 'any_cast']
+ns_functions = @namespace.functions(expected_functions)
+```
+
+Files
+-----
+
+```ruby
+file_classes = file.classes 		# List of Doxyparser::Class
+file_structs = file.structs 		# List of Doxyparser::Struct
+namepace_enums = file.enums 			# List of Doxyparser::Enum
+file_variables = file.variables 		# List of Doxyparser::Variable
+file_functions = file.functions 		# List of Doxyparser::Function
+file_typedefs = file.typedefs 			# List of Doxyparser::Typedef
+```
+
+Information about other header files included by this:
+
+```ruby
+list_files_included =  file.list_included   #  e.g ['cstdlib', 'list', 'map', 'subdir/test1.h']
+files_included = file.files_included		# List of Doxyparser::HFile (only for local header files i.e with XML representation in xml_dir)
+```
+
+Information about other header files which include this one:
+
+```ruby
+list_files_including =  file.list_including   #  e.g ['test3.h', 'test2.h', 'test4.h', 'subdir/test2.h']
+files_including = file.files_including		  # List of Doxyparser::HFile (only for local header files i.e with XML representation in xml_dir)
+```
+
+Classes and Structs
+-------------------
+
+```ruby
+struct_def_file = struct.file							# Instance of Doxyparser::HFile
+struct_inner_classes = struct.innerclasses	:public		# List of Doxyparser::Class
+struct_inner_structs = struct.innerstructs :protected	# List of Doxyparser::Struct
+struct_enums = struct.innerenums :public				# List of Doxyparser::Enum
+struct_attributes = struct.attributes(:public, :static)	# List of Doxyparser::Variable
+struct_methods = struct.methods(:private, :static)		# List of Doxyparser::Function
+friend_members = struct.friends 						# List of Doxyparser::Friend
+type_parameters = struct.template_params				# List of Doxyparser::Param
+type_defs = struct.typedefs	:public						# List of Doxyparser::Typedef
+```
+
+...and as expected for every member:
+
+```ruby
+struct_methods[0].parent == struct # true
+```
+
+The access modifier parameters (:public, :protected, :private) are optional. When none provided then :public is used.
+For methods and attributes :static can also be specified. When none provided then nil is used.
+
+Like for namespaces, you can also specify an additional list parameter to query a subset of class/struct members.
+
+```ruby
+# Note that the first two params need to be explicitly provided and we use nil instead of false
+struct_attr = struct.attributes(:protected, nil, ['attribute1', 'attribute2'])
+```
+
+
+Functions/Methods, Variables/Attributes, Typedefs and Enums
+-------------------------------------------------------------
+
+
+* General Properties:
+
+```ruby
+puts myMethod.name 		    #  myMethod
+puts myMethod.parent.name 	#  MyNamespace::Class1
+puts myMethod.location 		#  /path/to/included/file/myIncludeFile.h:245
+puts myMethod.definition	#  virtual void MyNamespace::Class1::myMethod
+puts myMethod.args			#  (const Any &anything)
+```
+
+
+* Functions and Methods only:
+
+Consider for example the following definition:
+
+```shell
+const String & myFunction(int myInt, std:map<String &, std:list<unsigned char, int *>> myMap = null)
+```
+
+After parsing with doxyparser we obtain:
+
+```ruby
+function_params = myFunction.params				# List of Doxyparser::Param
+first_param_type = function_params[0].type		# Instance of Doxyparser::Type
+puts first_param_type.name						# int
+puts first_param_type.declname					# myInt
+second_param_type = function_params[1].type		# Instance of Doxyparser::Type
+puts second_param_type.name						# std:map<String &, std:list<unsigned char, int * > > (full templates support)
+puts second_param_type.declname					# myMap
+puts second_param_type.value					# null
+return_type = function.type						# Instance of Doxyparser::Type
+puts return_type.name							# const String &
+```
+
+
+* Methods only:
+
+```shell
+MyClass(char * xc);
+```
+
+```ruby
+puts myMethod.name 					# > MyClass	
+puts myMethod.constructor?			# > true
+puts myMethod.destructor?			# > false
+```
+
+```shell
+~MyClass();
+```
+
+```ruby
+puts myMethod.name 					# > ~MyClass	
+puts myMethod.constructor?			# > false
+puts myMethod.destructor?			# > true
+```
+
+```shell
+MyClass* getProp();
+MyClass* get_prop();
+MyClass* GetProp();
+```
+
+```ruby
+puts myMethod.name 					# > getProp/get_prop/GetProp	
+puts myMethod.getter_for			# > prop	
+puts myMethod.setter_for			# > nil
+```
+
+```shell
+void setProp(MyClass *obj);
+void set_prop(MyClass *obj);
+void isProp(MyClass *obj);
+```
+
+```ruby
+puts myMethod.name 					# > setProp/set_prop/isProp
+puts myMethod.setter_for			# > prop
+puts myMethod.getter_for			# > nil
+```
+
+* Enums only:
+
+```shell
+enum MyEnum{
+   	A, B, C
+};
+```
+
+```ruby	
+puts myEnum.name				# > MyEnum
+puts myEnum.values.join(", ")	# > A, B, C
+```
+
+...and anonymous enums:
+
+```shell
+enum {
+   	A, B, C
+};
+```
+
+```ruby
+puts myEnum.name				# > _Enum
+puts myEnum.values.join(", ")	# > A, B, C
+```
+	

data/lib/doxyparser.rb

@@ -0,0 +1,75 @@
+require "rubygems"
+require "bundler/setup"
+
+require 'nokogiri'
+require 'fileutils'
+
+require_relative 'util'
+require_relative 'nodes/node'
+require_relative 'nodes/compound'
+require_relative 'nodes/type'
+require_relative 'nodes/param'
+require_relative 'nodes/member'
+require_relative 'nodes/typedef'
+require_relative 'nodes/friend'
+require_relative 'nodes/struct'
+require_relative 'nodes/class'
+require_relative 'nodes/enum'
+require_relative 'nodes/hfile'
+require_relative 'nodes/function'
+require_relative 'nodes/group'
+require_relative 'nodes/namespace'
+require_relative 'nodes/variable'
+
+
+module Doxyparser
+
+  class << self
+    def parse_namespace basename, xml_dir
+      Doxyparser::Namespace.new :name => basename, :dir => xml_dir
+    end
+
+    def parse_group basename, xml_dir
+      Doxyparser::Group.new :name => basename, :dir => xml_dir
+    end
+
+    def parse_class basename, xml_dir
+      Doxyparser::Class.new :name => basename, :dir => xml_dir
+    end
+
+    def parse_struct basename, xml_dir
+      Doxyparser::Struct.new :name => basename, :dir => xml_dir
+    end
+
+    def parse_file basename, xml_dir
+      Doxyparser::HFile.new :name => basename, :dir => xml_dir
+    end
+    
+    def gen_xml_docs src_dir, xml_dir, recursive = nil, include_dirs = nil, generate_html = nil
+    	
+    	if include_dirs.nil? || include_dirs.empty?
+    		inc_dirs = ''
+    	else
+    		inc_dirs = include_dirs.join(', ')
+    	end
+    	recursive = recursive ? 'YES' : 'NO'
+    	
+    	home_dir = Doxyparser::Util.home_dir
+    	gen_html = generate_html ? 'YES' : 'NO'
+    	proj_name = File.basename src_dir
+      doxyfile =  "# Doxyfile 1.7.6.1\n\n"
+      doxyfile << "# Project related configuration options\n\n"
+      doxyfile << %Q{PROJECT_NAME\t\t= "#{proj_name}"\nINPUT\t\t\t\t= #{src_dir}\nGENERATE_HTML\t\t= #{gen_html}\n}
+      doxyfile << %Q{RECURSIVE\t\t\t= #{recursive}\nINCLUDE_PATH\t\t= #{inc_dirs}\n\n}
+      doxyfile << "# Default doxygen configuration options\n\n"
+      doxyfile << Doxyparser::Util.read_file(home_dir+'/resources/Doxyfile')
+      doxyfile_path = xml_dir+'/Doxyfile'
+      FileUtils.mkdir_p(xml_dir)
+      Doxyparser::Util.write_file(doxyfile_path, doxyfile)      
+      Dir.chdir(xml_dir)
+      command = %Q{doxygen < #{doxyfile_path}}
+      output = IO.popen(command)
+      output.readlines
+    end
+  end
+end

data/lib/nodes/class.rb

@@ -0,0 +1,13 @@
+module Doxyparser
+
+	class Class < Struct
+
+		private
+
+		def compute_path
+			aux = escape_class_name @name
+			@xml_path = %Q{#{@dir}/class#{aux}.xml}
+		end
+
+	end
+end

data/lib/nodes/compound.rb

@@ -0,0 +1,42 @@
+module Doxyparser
+
+	class Compound < Node
+
+		attr_reader :xml_path
+
+		def new_unnamed
+			@unnamed += 1
+		end
+		
+		private
+
+		def init_attributes
+			super
+			@unnamed = 0
+			if @node
+				@xml_path = %Q{#{@dir}/#{self.refid}.xml}
+			else
+				compute_path
+			end
+		end
+
+		def find_name
+			@node.child.content
+		end
+
+		def doc
+			if @doc.nil?
+				parse
+			end
+			@doc
+		end
+
+		def parse
+			raise "No file found at this location: #{@xml_path} for node #{self.class.name} #{@name}" unless File.exists? @xml_path
+			File.open(@xml_path) { |xml_doc|
+				@doc=Nokogiri::XML(xml_doc)
+			}
+			self
+		end
+	end
+end

data/lib/nodes/enum.rb

@@ -0,0 +1,20 @@
+module Doxyparser
+
+	class Enum < Member
+
+		def values
+			ret=[]
+			xpath("enumvalue/name").each { |v| ret << v.child.content }
+			ret
+		end
+
+		private
+
+		def find_name
+			super.gsub(/@\d*/) {
+				num = parent.new_unnamed
+				'_Enum' +  (num == 1 ? '' : num.to_s)
+			}
+		end
+	end
+end