ffi-clang 0.2.0 → 0.2.1

data/lib/ffi/clang/version.rb

@@ -21,6 +21,6 @@
 
 module FFI
 	module Clang
-		VERSION = "0.2.0"
+		VERSION = "0.2.1"
 	end
 end

data/spec/clang/code_completion_spec.rb

@@ -0,0 +1,181 @@
+# Copyright, 2014, by Masahiro Sano.
+# 
+# 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 CodeCompletion do
+	let(:filename) { fixture_path("completion.cxx") }
+	let(:tu) { Index.new.parse_translation_unit(filename) }
+	let(:line) { 7 }
+	let(:column) { 6 }
+	let(:results) { tu.code_complete(filename, line, column) }
+
+	describe "self.default_code_completion_options" do
+		let(:options) { FFI::Clang::CodeCompletion.default_code_completion_options }
+		it "returns a default set of code-completion options" do
+			expect(options).to be_kind_of(Hash)
+			options.keys.each { |key|
+				expect(FFI::Clang::Lib::CodeCompleteFlags.symbols).to include(key)
+			}
+		end
+	end
+
+	describe CodeCompletion::Results do
+		it "can be obtained from a translation unit" do
+			expect(results).to be_kind_of(CodeCompletion::Results)
+			
+			# At least 40 results, depends on standard library implementation:
+			expect(results.size).to be >= 40
+			
+			expect(results.results).to be_kind_of(Array)
+			expect(results.results.first).to be_kind_of(CodeCompletion::Result)
+		end
+
+		it "calls dispose_code_complete_results on GC" do
+			expect(Lib).to receive(:dispose_code_complete_results).at_least(:once)
+			expect{results.free}.not_to raise_error
+		end
+
+		it "#each" do
+			spy = double(stub: nil)
+			expect(spy).to receive(:stub).exactly(results.size).times
+			results.each { spy.stub }
+		end
+
+		it "#num_diagnostics" do
+			expect(results.num_diagnostics).to eq(2)
+		end
+
+		it "#diagnostic" do
+			expect(results.diagnostic(0)).to be_kind_of(Diagnostic)
+		end
+
+		it "#diagnostics" do
+			expect(results.diagnostics).to be_kind_of(Array)
+			expect(results.diagnostics.first).to be_kind_of(Diagnostic)
+			expect(results.diagnostics.size).to eq(results.num_diagnostics)
+		end
+
+		it "#contexts" do
+			expect(results.contexts).to be_kind_of(Hash)
+			results.contexts.keys.each { |key|
+				expect(FFI::Clang::Lib::CompletionContext.symbols).to include(key)
+			}
+		end
+
+		it "#container_usr" do
+			expect(results.container_usr).to be_kind_of(String)
+			expect(results.container_usr).to match(/std.+vector/)
+		end
+
+		it "#container_kind" do
+			expect(results.container_kind).to be_kind_of(Symbol)
+			expect(results.container_kind).to eq(:cursor_class_decl)
+		end
+
+		it "#incomplete?" do
+			expect(results.incomplete?).to be false
+		end
+
+		it "#objc_selector" do
+			#TODO
+		end
+
+		it "#sort!" do
+			results.sort!
+			
+			# may be sorted with typed_text kind, first result will start with 'a'
+			expect(results.results.first.string.chunks.select{|x| x[:kind] == :typed_text}.first[:text]).to be =~ /^a/
+		end
+	end
+
+	describe CodeCompletion::Result do
+		let(:result) { results.results.first }
+		it "#string" do
+			expect(result.string).to be_kind_of(CodeCompletion::String)
+		end
+
+		it "#kind" do
+			expect(result.kind).to be_kind_of(Symbol)
+		end
+	end
+
+	describe CodeCompletion::String do
+		let(:str) { results.sort!; results.find{|x| x.string.chunk_text(1) == 'assign'}.string }
+
+		it "#num_chunks" do
+			expect(str.num_chunks).to be >= 5
+		end
+
+		it "#chunk_kind" do
+			expect(str.chunk_kind(0)).to eq(:result_type)
+			expect(str.chunk_kind(1)).to eq(:typed_text)
+		end
+
+		it "#chunk_text" do
+			expect(str.chunk_text(0)).to be =~ /void/
+			expect(str.chunk_text(1)).to eq('assign')
+		end
+
+		it "#chunk_completion" do
+			expect(str.chunk_completion(0)).to be_kind_of(CodeCompletion::String)
+		end
+
+		it "#chunks" do
+			expect(str.chunks).to be_kind_of(Array)
+			expect(str.chunks.first).to be_kind_of(Hash)
+			expect(str.chunks.size).to eq(str.num_chunks)
+		end
+
+		it "#priority" do
+			expect(str.priority).to be_kind_of(Integer)
+		end
+
+		it "#availability" do
+			expect(str.availability).to be_kind_of(Symbol)
+			expect(str.availability).to eq(:available)
+		end
+
+		it "#num_annotations" do
+			expect(str.num_annotations).to be_kind_of(Integer)
+			expect(str.num_annotations).to eq(0)
+		end
+
+		it "#annotation" do
+			expect(str.annotation(100)).to be_nil
+			# TODO: need tests for String which has annotation
+		end
+
+		it "#annotations" do
+			expect(str.annotations).to be_kind_of(Array)
+			# TODO: need tests for String which has annotation
+		end
+
+		it "#parent" do
+			expect(str.parent).to be_kind_of(String)
+			expect(str.parent).to be =~ /std.+vector/
+		end
+
+		it "#comment" do
+			expect(str.comment).to be_nil
+			# TODO: need tests for String which has real comment
+		end
+	end
+end

data/spec/clang/comment_spec.rb

@@ -22,7 +22,7 @@
 require 'spec_helper'
 
 describe Comment do
-	let(:cursor) { Index.new.parse_translation_unit(fixture_path("docs.h")).cursor }
+	let(:cursor) { Index.new.parse_translation_unit(fixture_path("docs.cc")).cursor }
 	let (:comment) { find_first(cursor, :cursor_function).comment }
 
 	it "can be obtained from a cursor" do
@@ -56,7 +56,7 @@ describe Comment do
 	end
 
 	it "has working helpers" do
-		comment.num_children.should equal(6)
+		comment.num_children.should equal(8)
 
 		para = comment.child(1)
 		para.text.should eq(" This is a longer explanation\n that spans multiple lines")
@@ -75,23 +75,396 @@ describe Comment do
 		end
 	end
 
-	describe "understands blocks" do
-		let (:block) { comment.child(5) }
+	describe "#whitespace?" do
+		it "checks the comment is whitespace" do
+			expect(comment.child.whitespace?).to be false
+		end
+	end
+
+	describe "#has_trailing_newline?" do
+		it "checks the content has a traling newline" do
+			expect(comment.child.has_trailing_newline?).to be false
+		end
+	end
+
+	context 'comment_null' do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function and child.spelling == 'no_comment_function' } }
+		let(:comment) { comment_cursor.comment }
+
+		it "is null comment" do
+			expect(comment).to be_kind_of(Comment)
+			expect(comment.kind).to eq(:comment_null)
+			expect(comment.text).to eq('')
+		end
+	end
+
+	context 'unknown comment type' do
+		let(:comment) { 'foobar' }
+		it "raises NotImplementedError" do
+			expect(Lib).to receive(:comment_get_kind).with(comment).and_return(:xxx_yyy_zzzz)
+			expect{Comment.build_from(comment)}.to raise_error(NotImplementedError)
+		end
+	end
+
+	describe HTMLStartTagComment do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function and child.spelling == 'b_function' } }
+		let(:comment) { comment_cursor.comment }
+		let(:paragraph) { comment_cursor.comment.child }
+		let(:html_start_tag_comments) { paragraph.children.select{|c| c.kind == :comment_html_start_tag} }
+
+		it "can be obtained from cursor" do
+			expect(comment).to be_kind_of(FullComment)
+			expect(comment.kind).to equal(:comment_full)
+			expect(paragraph).to be_kind_of(ParagraphComment)
+			expect(html_start_tag_comments.first).to be_kind_of(HTMLStartTagComment)
+			expect(html_start_tag_comments.size).to eq(2)
+		end
+
+		describe "#tag" do
+			it "returns HTML tag name" do
+				expect(html_start_tag_comments[0].tag).to eq('br')
+				expect(html_start_tag_comments[1].tag).to eq('a')
+			end
+
+			it "is alias method of #name" do
+				expect(html_start_tag_comments[0].name).to eq('br')
+				expect(html_start_tag_comments[1].name).to eq('a')
+			end
+		end
+
+		describe "#text" do
+			it "returns HTML tag as string", from_3_4: true do
+				expect(html_start_tag_comments[0].text.strip).to eq('<br/>')
+				expect(html_start_tag_comments[1].text.strip).to eq('<a href="http://example.org/">')
+			end
+
+			it "returuns empty string", upto_3_3: true do
+				expect(html_start_tag_comments[0].text.strip).to eq('')
+				expect(html_start_tag_comments[1].text.strip).to eq('')
+			end
+		end
+
+		describe "#self_closing?" do
+			it "checks the tag is self-closing" do
+				expect(html_start_tag_comments[0].self_closing?).to be true
+				expect(html_start_tag_comments[1].self_closing?).to be false
+			end
+		end
+
+		describe "#num_attrs" do
+			it "returns the number of attributes" do
+				expect(html_start_tag_comments[0].num_attrs).to eq(0)
+				expect(html_start_tag_comments[1].num_attrs).to eq(1)
+			end
+		end
+
+		describe "#attrs" do
+			it "returns attributes as Array of Hash" do
+				expect(html_start_tag_comments[0].attrs).to eq([])
+                expect(html_start_tag_comments[1].attrs).to eq([{name: 'href', value: 'http://example.org/'}])
+			end
+		end
+	end
+
+	describe HTMLEndTagComment do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function and child.spelling == 'b_function' } }
+		let(:comment) { comment_cursor.comment }
+		let(:paragraph) { comment_cursor.comment.child }
+		let(:html_end_tag_comment) { paragraph.children.select{|c| c.kind == :comment_html_end_tag}.first }
+
+		it "can be obtained from cursor" do
+			expect(comment).to be_kind_of(FullComment)
+			expect(comment.kind).to equal(:comment_full)
+			expect(paragraph).to be_kind_of(ParagraphComment)
+			expect(html_end_tag_comment).to be_kind_of(HTMLEndTagComment)
+		end
+
+		describe "#tag" do
+			it "returns HTML tag name" do
+				expect(html_end_tag_comment.tag).to eq('a')
+			end
+
+			it "is alias method of #name" do
+				expect(html_end_tag_comment.name).to eq('a')
+			end
+		end
+
+		describe "#text" do
+			it "returns HTML tag as string", from_3_4: true do
+				expect(html_end_tag_comment.text.strip).to eq('</a>')
+			end
+
+			it "returuns empty string", upto_3_3: true do
+				expect(html_end_tag_comment.text.strip).to eq('')
+			end
+		end
+	end
+
+	describe FullComment do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function and child.spelling == 'f_function' } }
+		let(:comment) { comment_cursor.comment }
+
+		it "can be obtained from cursor" do
+			expect(comment).to be_kind_of(FullComment)
+			expect(comment.kind).to equal(:comment_full)
+		end
+
+		describe "#to_html" do
+			it "converts a given full parsed comment to an HTML fragment", from_3_4: true do
+				expect(comment.to_html).to be_kind_of(String)
+				expect(comment.to_html).to eq('<p class="para-brief"> this is a function.</p>')
+			end
+
+			it "converts a given full parsed comment to an HTML fragment", upto_3_3: true do
+				expect(comment.to_html).to be_kind_of(String)
+				expect(comment.to_html).to eq('<p class="para-brief"> this is a function. </p>')
+			end
+		end
+
+		describe "#to_xml" do
+			it "converts a given full parsed comment to an XML document" do
+				expect(comment.to_xml).to be_kind_of(String)
+			end
+		end
+	end
+
+	describe BlockCommandComment do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function and child.spelling == 'f_function' } }
+		let(:comment) { comment_cursor.comment }
+		let(:block_cmd_comment) { comment.children.select{|c| c.kind == :comment_block_command}.first }
+
+		it "can be obtained from cursor" do
+			expect(comment).to be_kind_of(FullComment)
+			expect(comment.kind).to equal(:comment_full)
+			expect(block_cmd_comment).to be_kind_of(BlockCommandComment)
+			expect(block_cmd_comment.child).to be_kind_of(ParagraphComment)
+		end
+
+		describe "#name" do
+			it "returns the name of the block command" do
+				expect(block_cmd_comment.name).to eq("brief")
+			end
+		end
+
+		describe "#paragraph" do
+			it "returns the paragraph" do
+				expect(block_cmd_comment.paragraph).to be_kind_of(ParagraphComment)
+			end
+		end
+
+		describe "#num_args" do
+			it "returns the number of word-like arguments" do
+				expect(block_cmd_comment.num_args).to eq(0)
+			end
+		end
+
+		describe "#args" do
+			it "returns word-like arguments" do
+				expect(block_cmd_comment.args).to be_kind_of(Array)
+				expect(block_cmd_comment.args).to eq([])
+			end
+
+			#TODO: needs tests with comments which have arguments
+		end
+
+		describe "#text" do
+			it "returns readble text that includes children's comments" do
+				expect(block_cmd_comment.text).to be_kind_of(String)
+				expect(block_cmd_comment.text.strip).to eq('this is a function.')
+			end
+
+			it "is a alias method of #comment" do
+				expect(block_cmd_comment.comment).to eq(block_cmd_comment.text)
+			end
+		end
+	end
+
+	describe InlineCommandComment do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function and child.spelling == 'd_function' } }
+		let(:comment) { comment_cursor.comment }
+		let(:inline_command_comments) { comment.child.children.select{|c| c.kind == :comment_inline_command} }
+
+		it "can be obtained from cursor" do
+			expect(comment).to be_kind_of(FullComment)
+			expect(comment.kind).to equal(:comment_full)
+			expect(comment.child).to be_kind_of(ParagraphComment)
+			expect(inline_command_comments.size).to eq(2)
+		end
+
+		describe "#name" do
+			it "returns the name of the inline command" do
+				expect(inline_command_comments[0].name).to eq("em")
+				expect(inline_command_comments[1].name).to eq("b")
+			end
+		end
+
+		describe "#render_kind" do
+			it "returns the most appropriate rendering mode" do
+				expect(inline_command_comments[0].render_kind).to eq(:emphasized)
+				expect(inline_command_comments[1].render_kind).to eq(:bold)
+			end
+		end
+
+		describe "#num_args" do
+			it "returns number of command arguments" do
+				expect(inline_command_comments[0].num_args).to eq(1)
+				expect(inline_command_comments[1].num_args).to eq(1)
+			end
+		end
+
+		describe "#args" do
+			it "returns arguments as Array" do
+				expect(inline_command_comments[0].args).to eq(["foo"])
+				expect(inline_command_comments[1].args).to eq(["bar"])
+			end
+		end
+
+		describe "#text" do
+			it "returns readble text" do
+				expect(inline_command_comments[0].text.strip).to eq("foo")
+				expect(inline_command_comments[1].text.strip).to eq("bar")
+			end
+		end
+	end
+
+	describe VerbatimBlockCommandComment do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function and child.spelling == 'e_function' } }
+		let(:comment) { comment_cursor.comment }
+		let(:verb_block_cmd_comment) { comment.children.select{|c| c.kind == :comment_verbatim_block_command}.first }
+
+		it "can be obtained from cursor" do
+			expect(comment).to be_kind_of(FullComment)
+			expect(comment.kind).to equal(:comment_full)
+			expect(verb_block_cmd_comment).to be_kind_of(VerbatimBlockCommandComment)
+		end
+
+		describe "#text" do
+			it "returns readble text" do
+				expect(verb_block_cmd_comment.text).to eq("  foo bar\n  baz")
+			end
+		end
+	end
+
+	describe VerbatimBlockLineComment do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function and child.spelling == 'e_function' } }
+		let(:comment) { comment_cursor.comment }
+		let(:verb_block_cmd_comment) { comment.children.select{|c| c.kind == :comment_verbatim_block_command}.first }
+		let(:verb_block_line_comments) { verb_block_cmd_comment.children }
+
+		it "can be obtained from cursor" do
+			expect(comment).to be_kind_of(FullComment)
+			expect(comment.kind).to equal(:comment_full)
+			expect(verb_block_cmd_comment).to be_kind_of(VerbatimBlockCommandComment)
+			expect(verb_block_line_comments.first).to be_kind_of(VerbatimBlockLineComment)
+			expect(verb_block_line_comments.size).to eq(2)
+		end
+
+		describe "#text" do
+			it "returns readble text" do
+				expect(verb_block_line_comments[0].text.strip).to eq("foo bar")
+				expect(verb_block_line_comments[1].text.strip).to eq("baz")
+			end
+		end
+	end
+
+	describe VerbatimLine do
+	# TODO: how to generate this comment?
+	end
+
+	describe ParamCommandComment do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function and child.spelling == 'a_function' } }
+		let(:comment) { comment_cursor.comment }
+		let(:param_cmd_comments) { comment.children.select{|c| c.kind == :comment_param_command} }
+
+		it "can be obtained from cursor" do
+			expect(comment).to be_kind_of(FullComment)
+			expect(comment.kind).to equal(:comment_full)
+			expect(param_cmd_comments.first).to be_kind_of(ParamCommandComment)
+			expect(param_cmd_comments.size).to eq(4)
+		end
+
+		describe "#text" do
+			it "returns readble text" do
+				expect(param_cmd_comments[0].text.strip).to eq("some input")
+				expect(param_cmd_comments[1].text.strip).to eq("some flags")
+			end
+		end
+
+		describe "#direction_explicit?" do
+			it "checks the direction is specified explicitly" do
+				expect(param_cmd_comments[0].direction_explicit?).to be true
+				expect(param_cmd_comments[3].direction_explicit?).to be false
+			end
+		end
+
+		describe "#direction" do
+			it "returns parameter passing direction" do
+				expect(param_cmd_comments[0].direction).to eq(:pass_direction_in)
+				expect(param_cmd_comments[1].direction).to eq(:pass_direction_out)
+				expect(param_cmd_comments[2].direction).to eq(:pass_direction_inout)
+				expect(param_cmd_comments[3].direction).to eq(:pass_direction_in)
+			end
+		end
+	end
+
+	describe TParamCommandComment do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function_template and child.spelling == 'c_function' } }
+		let(:comment) { comment_cursor.comment }
+		let(:tparam_cmd_comments) { comment.children.select{|c| c.kind == :comment_tparam_command} }
+
+		it "can be obtained from cursor" do
+			expect(comment).to be_kind_of(FullComment)
+			expect(comment.kind).to equal(:comment_full)
+			expect(tparam_cmd_comments.first).to be_kind_of(TParamCommandComment)
+			expect(tparam_cmd_comments.size).to eq(3)
+		end
+
+		describe "#text" do
+			it "returns readble text" do
+				expect(tparam_cmd_comments[0].text.strip).to eq("some type of foo")
+				expect(tparam_cmd_comments[1].text.strip).to eq("some type of bar")
+			end
+		end
 
-		it 'is BlockCommandComment' do
-			expect(block).to be_kind_of(BlockCommandComment)
+		describe "#name" do
+			it "returns template parameter name" do
+				expect(tparam_cmd_comments[0].name).to eq("T1")
+				expect(tparam_cmd_comments[1].name).to eq("T2")
+				expect(tparam_cmd_comments[2].name).to eq("T3")
+			end
 		end
 
-		it 'has name' do
-			expect(block.name).to eq("return")
+		describe "#valid_position?" do
+			it "checks this parameter has valid position" do
+				expect(tparam_cmd_comments[0].valid_position?).to be true
+			end
 		end
 
-		it 'has comment', from_3_4: true do
-			expect(block.comment).to eq(" a random value")
+		describe "#depth" do
+			it "returns nesting depth of this parameter" do
+				expect(tparam_cmd_comments[0].depth).to eq(1)
+				expect(tparam_cmd_comments[1].depth).to eq(2)
+				expect(tparam_cmd_comments[2].depth).to eq(1)
+			end
 		end
 
-		it 'has comment', upto_3_3: true do
-			expect(block.comment).to eq(" a random value\n ")
+		describe "#index" do
+			it "returns index of the parameter at the given nesting depth" do
+				expect(tparam_cmd_comments[0].index(0)).to eq(0)
+				expect(tparam_cmd_comments[1].index(0)).to eq(1)
+				expect(tparam_cmd_comments[1].index(1)).to eq(0)
+				expect(tparam_cmd_comments[2].index(0)).to eq(1)
+			end
 		end
 	end
 end