ffi-clang 0.1.1 → 0.1.2

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    Njk3ODJkZDU2YzlmODI2YTQ2ZmJiYzI5ZjE2OWY5MWEyZDAwNWM5Ng==
+    MDE1NGQxNDVlMTM4Mjk5YTMyOGM5MmI2MjY1YWI4ODQ0NTc1YjZmYw==
   data.tar.gz: !binary |-
-    NDEzNjk5MzM0NmJjY2M4NDVjMjBlNjc3Y2M5Y2QwOTdiZGRiMGRiOA==
+    NjYwNTIxYTcwYjc0M2I1NjE5NTU3YWRkYTAwMmQxMTg5N2NiZmE0Nw==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    NmViOGUxYWIwNDJmMWEyMTk1ZDkzODA3NmQwNTEyMmRkODI5YmM0ZmNhYWM2
-    OWI2NjdkMGMwMTU0MGNkOWJiYTA4YzVhZGEzNjZhMjExMjU3ZGE4Yjg0ZTI3
-    MWJiOWFiZWY4NWQ3NTE4NjQ3NTAyMThmOWFjNzFiZjI0NDk2OGQ=
+    MGVjMjcwMTg2NDU5MGRmYjgxMzNiYzU5MjY5NzY4OTI1ZDBkZTU0ZDBlNmEx
+    N2RjYzg5NjdjM2E1YWRhNTdiMzk1ZTAzNTAzOTU4MTc3YmRhYmM3YzUwMWFm
+    ZTA2OWQ4ODU3Y2JlMzdmNzQ1ZmM4NWRiNmIwNzIwNDE5Y2NkYjU=
   data.tar.gz: !binary |-
-    ZDQyZWRiYzhiYjcxYmYyYjc2OGNiNDM1MTMyNWVkMmRjMjgwMDgyNDNiNmNj
-    OTU2YWU5NWVkNzgzMjBmM2YzMDQ4ZjU4ZDkxOWIwMTI2ODNiNmI2MjY3ZTIw
-    YTI4MDM2MzZlNzUxNmQ4MTEyNmZlMzMxYzIzNTI0ZmNiOWE1YWE=
+    MzlhMDM1OGViZmZmOGRkNTMzODA5ZjM2OTdlZDBlMmMyNjQyOTg2NGE0MWRj
+    MjY1ZDQyMTBjMzM0YjA3OTg3Yjg5OTdmNzdiODg5YmFkMDExOWY0MGU1M2Vh
+    NGRiNGFhY2QwNTE3NDlmZjM1MDQ4MGU3NWM0MWQ4YzliNWIzMDc=

data/lib/ffi/clang/comment.rb

@@ -0,0 +1,135 @@
+# -*- coding: utf-8 -*-
+# Copyright, 2013, by Carlos Martín Nieto <cmn@dwim.me>
+# 
+# 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.
+
+require 'ffi/clang/lib/cursor'
+require 'ffi/clang/lib/comment'
+require 'ffi/clang/source_location'
+
+module FFI
+	module Clang
+
+		class Comment
+			include Enumerable
+
+			def self.build_from(comment)
+				kind = Lib.comment_get_kind(comment)
+				case kind
+				when :comment_full
+					FullComment.new comment
+				when :comment_paragraph
+					ParagraphComment.new comment
+				when :comment_text
+					TextComment.new comment
+				when :comment_block_command
+					BlockCommandComment.new comment
+				when :comment_param_command
+					ParamCommandComment.new comment
+				when :comment_null
+					Comment.new comment
+				else
+					raise NotImplementedError, kind
+				end
+			end
+
+			def initialize(comment)
+				@comment = comment
+			end
+
+			def kind
+				Lib.comment_get_kind(@comment)
+			end
+
+			def num_children
+				Lib.comment_get_num_children(@comment)
+			end
+
+			def child(n = 0)
+				Comment.build_from Lib.comment_get_child(@comment, n)
+			end
+
+			def each(&block)
+				(0..num_children-1).map do |i|
+					block.call(child(i))
+				end
+			end
+
+		end
+
+		class ParagraphComment < Comment
+			def text
+				self.map(&:text).join("\n")
+			end
+		end
+
+		class TextComment < Comment
+			def text
+				Lib.extract_string Lib.text_comment_get_text(@comment)
+			end
+		end
+
+		class BlockCommandComment < Comment
+			def name
+				Lib.extract_string Lib.block_command_comment_get_command_name(@comment)
+			end
+
+			def paragraph
+				Comment.build_from Lib.block_command_comment_get_paragraph(@comment)
+			end
+
+			def comment
+				self.paragraph.text
+			end
+
+			def num_args
+				Lib.block_command_comment_get_num_args(@comment)
+			end
+		end
+
+		class ParamCommandComment < Comment
+			def name
+				Lib.extract_string Lib.param_command_comment_get_param_name(@comment)
+			end
+
+			def comment
+				self.child.text
+			end
+
+			def valid_index?
+				Lib.param_command_comment_is_param_index_valid(@comment) != 0
+			end
+
+			def index
+				Lib.param_command_comment_get_param_index(@comment)
+			end
+		end
+
+		class FullComment < Comment
+			def to_html
+				Lib.extract_string Lib.full_comment_get_as_html(@comment)
+			end
+
+			def to_xml
+				Lib.extract_string Lib.full_comment_get_as_xml(@comment)
+			end
+		end
+
+	end
+end

data/lib/ffi/clang/cursor.rb

@@ -21,6 +21,7 @@
 
 require 'ffi/clang/lib/cursor'
 require 'ffi/clang/source_location'
+require 'ffi/clang/comment'
 
 module FFI
 	module Clang
@@ -37,6 +38,14 @@ module FFI
 				Lib.cursor_is_null(@cursor) != 0
 			end
 
+			def raw_comment_text
+				Lib.extract_string Lib.cursor_get_raw_comment_text(@cursor)
+			end
+
+			def comment
+				Comment.build_from Lib.cursor_get_parsed_comment(@cursor)
+			end
+
 			def declaration?
 				Lib.is_declaration(kind) != 0
 			end

data/lib/ffi/clang/lib/comment.rb

@@ -0,0 +1,56 @@
+# Copyright, 2010-2012 by Jari Bakken.
+# Copyright, 2013, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# 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.
+
+require 'ffi/clang/lib/index'
+
+module FFI
+	module Clang
+		module Lib
+			class CXComment < FFI::Struct
+				layout(
+				       :ast_node, :pointer,
+				       :translation_unit, :pointer
+				       )
+			end
+
+			enum :kind, [:comment_null, 0,
+				     :comment_text, 1,
+				     :comment_paragraph, 5,
+				     :comment_block_command,6 ,
+				     :comment_param_command, 7,
+				     :comment_full, 12]
+
+			attach_function :comment_get_kind, :clang_Comment_getKind, [CXComment.by_value], :kind
+			attach_function :comment_get_num_children, :clang_Comment_getNumChildren, [CXComment.by_value], :uint
+			attach_function :comment_get_child, :clang_Comment_getChild, [CXComment.by_value, :uint], CXComment.by_value
+			attach_function :text_comment_get_text, :clang_TextComment_getText, [CXComment.by_value], CXString.by_value
+			attach_function :block_command_comment_get_paragraph, :clang_BlockCommandComment_getParagraph, [CXComment.by_value], CXComment.by_value
+			attach_function :full_comment_get_as_html, :clang_FullComment_getAsHTML, [CXComment.by_value], CXString.by_value
+			attach_function :full_comment_get_as_xml, :clang_FullComment_getAsXML, [CXComment.by_value], CXString.by_value
+
+			attach_function :param_command_comment_get_param_name, :clang_ParamCommandComment_getParamName, [CXComment.by_value], CXString.by_value
+			attach_function :param_command_comment_is_param_index_valid, :clang_ParamCommandComment_isParamIndexValid, [CXComment.by_value], :uint
+			attach_function :param_command_comment_get_param_index, :clang_ParamCommandComment_getParamIndex, [CXComment.by_value], :uint
+			attach_function :block_command_comment_get_command_name, :clang_BlockCommandComment_getCommandName, [CXComment.by_value], CXString.by_value
+			attach_function :block_command_comment_get_num_args, :clang_BlockCommandComment_getNumArgs, [CXComment.by_value], :uint
+		end
+	end
+end

data/lib/ffi/clang/lib/cursor.rb

@@ -22,12 +22,17 @@
 
 require 'ffi/clang/lib/translation_unit'
 require 'ffi/clang/lib/diagnostic'
+require 'ffi/clang/lib/comment'
 
 module FFI
 	module Clang
 		module Lib
 			enum :kind, [:cursor_struct, 2,
+				:cursor_enum_decl, 5,
+				:cursor_enum_constant_decl, 7,
 				:cursor_function, 8,
+				:cursor_parm_decl, 10,
+				:cursor_typedef_decl, 20,
 				:cursor_invalid_file, 70,
 				:cursor_translation_unit, 300]
 
@@ -45,6 +50,9 @@ module FFI
 
 			attach_function :cursor_is_null, :clang_Cursor_isNull, [CXCursor.by_value], :int
 
+			attach_function :cursor_get_raw_comment_text, :clang_Cursor_getRawCommentText, [CXCursor.by_value], CXString.by_value
+			attach_function :cursor_get_parsed_comment, :clang_Cursor_getParsedComment, [CXCursor.by_value], CXComment.by_value
+
 			attach_function :get_cursor_location, :clang_getCursorLocation, [CXCursor.by_value], CXSourceLocation.by_value
 			attach_function :get_cursor_extent, :clang_getCursorExtent, [CXCursor.by_value], CXSourceRange.by_value
 			attach_function :get_cursor_display_name, :clang_getCursorDisplayName, [CXCursor.by_value], CXString.by_value

data/lib/ffi/clang/version.rb

@@ -21,6 +21,6 @@
 
 module FFI
 	module Clang
-		VERSION = "0.1.1"
+		VERSION = "0.1.2"
 	end
 end

data/spec/clang/comment_spec.rb

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+# Copyright, 2013, by Carlos Martín Nieto <cmn@dwim.me>
+# 
+# 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.
+
+require 'spec_helper'
+
+describe Comment do
+	let(:cursor) { Index.new.parse_translation_unit(fixture_path("docs.h")).cursor }
+	let (:comment) { find_first(cursor, :cursor_function).comment }
+
+	it "can be obtained from a cursor" do
+		comment.should be_kind_of(Comment)
+		comment.should be_kind_of(FullComment)
+		comment.kind.should equal(:comment_full)
+	end
+
+	it "can parse the brief description" do
+		para = comment.child
+		para.kind.should equal(:comment_paragraph)
+		para.should be_kind_of(ParagraphComment)
+		text = para.child
+		text.kind.should equal(:comment_text)
+		text.should be_kind_of(TextComment)
+		text.text.strip.should eq("Short explanation")
+	end
+
+	it "can parse the longer description" do
+		para = comment.child(1)
+		para.kind.should equal(:comment_paragraph)
+		para.num_children.should equal(2)
+		text = para.child
+
+		lines = (0..para.num_children-1).map do |i|
+			para.child(i).text
+		end
+
+		lines.should eq([" This is a longer explanation",
+				 " that spans multiple lines"])
+	end
+
+	it "has working helpers" do
+		comment.num_children.should equal(6)
+
+		para = comment.child(1)
+		para.text.should eq(" This is a longer explanation\n that spans multiple lines")
+	end
+
+	it "understands params" do
+		param = comment.child(3)
+		param.should be_kind_of(ParamCommandComment)
+
+		param.valid_index?.should == true
+		param.index.should equal(0)
+		param.name.should eq("input")
+		arg = " some input\n "
+		param.child.text.should eq(arg)
+		param.comment.should eq(arg)
+	end
+
+	it "understands blocks" do
+		block = comment.child(5)
+		block.should be_kind_of(BlockCommandComment)
+		block.name.should eq("return")
+		block.comment.should eq(" a random value\n ")
+	end
+
+end

data/spec/clang/cursor_spec.rb

@@ -22,21 +22,6 @@
 
 require 'spec_helper'
 
-def find_first(cursor, kind)
-	first = nil
-
-	cursor.visit_children do |cursor, parent|
-		if (cursor.kind == kind)
-			first = cursor
-			:break
-		else
-			:recurse
-		end
-	end
-
-	first
-end
-
 describe Cursor do
 	let(:cursor) { Index.new.parse_translation_unit(fixture_path("list.c")).cursor }
 

data/spec/fixtures/docs.h

@@ -0,0 +1,11 @@
+/**
+ * Short explanation
+ *
+ * This is a longer explanation
+ * that spans multiple lines
+ *
+ * @param input some input
+ * @param flags some flags
+ * @return a random value
+ */
+int a_function(char *input, int flags);

data/spec/spec_helper.rb

@@ -7,6 +7,21 @@ module ClangSpecHelper
 	def fixture_path(path)
 		File.join File.expand_path("../fixtures", __FILE__), path
 	end
+
+	def find_first(cursor, kind)
+		first = nil
+
+		cursor.visit_children do |cursor, parent|
+			if (cursor.kind == kind)
+				first = cursor
+				:break
+			else
+				:recurse
+			end
+		end
+
+		first
+	end
 end
 
 RSpec.configure do |c|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ffi-clang
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Jari Bakken
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-28 00:00:00.000000000 Z
+date: 2013-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -83,10 +83,12 @@ files:
 - Rakefile
 - ffi-clang.gemspec
 - lib/ffi/clang.rb
+- lib/ffi/clang/comment.rb
 - lib/ffi/clang/cursor.rb
 - lib/ffi/clang/diagnostic.rb
 - lib/ffi/clang/index.rb
 - lib/ffi/clang/lib.rb
+- lib/ffi/clang/lib/comment.rb
 - lib/ffi/clang/lib/cursor.rb
 - lib/ffi/clang/lib/diagnostic.rb
 - lib/ffi/clang/lib/file.rb
@@ -100,12 +102,14 @@ files:
 - lib/ffi/clang/translation_unit.rb
 - lib/ffi/clang/unsaved_file.rb
 - lib/ffi/clang/version.rb
+- spec/clang/comment_spec.rb
 - spec/clang/cursor_spec.rb
 - spec/clang/diagnostic_spec.rb
 - spec/clang/index_spec.rb
 - spec/clang/source_location_spec.rb
 - spec/clang/translation_unit_spec.rb
 - spec/fixtures/a.c
+- spec/fixtures/docs.h
 - spec/fixtures/list.c
 - spec/spec_helper.rb
 homepage: ''
@@ -133,11 +137,13 @@ signing_key:
 specification_version: 4
 summary: Ruby FFI bindings for libclang C interface.
 test_files:
+- spec/clang/comment_spec.rb
 - spec/clang/cursor_spec.rb
 - spec/clang/diagnostic_spec.rb
 - spec/clang/index_spec.rb
 - spec/clang/source_location_spec.rb
 - spec/clang/translation_unit_spec.rb
 - spec/fixtures/a.c
+- spec/fixtures/docs.h
 - spec/fixtures/list.c
 - spec/spec_helper.rb