› FFI::Clang › Source › FFI › Clang › IndexAction

class IndexAction

Represents a reusable libclang indexing session.

Nested

Definitions

def initialize(index)

Initialize an index action for the given index.

Signature
parameter　index　Index

The owning index.

Implementation

 
def initialize(index)
	super Lib.create_index_action(index)
	@index = index
end

def self.release(pointer)

Release the underlying index action pointer.

Signature
parameter　pointer　FFI::Pointer

The pointer to release.

Implementation

 
def self.release(pointer)
	Lib.dispose_index_action(pointer)
end

def index_source_file(source_file, command_line_args = nil, unsaved = [], index_opts = [], translation_unit_opts = [], &block)

Index a source file and yield indexing events. Event payloads:

  • :diagnostic => Array(Diagnostic)
  • :entered_main_file => FFI::Clang::File
  • :included_file => IncludedFile
  • :imported_ast_file => ImportedASTFile
  • :started_translation_unit => nil
  • :declaration => Declaration
  • :reference => EntityReference If the block returns :abort, libclang stops the next time it polls abortQuery, so a few more callbacks may be delivered before control returns.

Signature
parameter　source_file　String

The source file to index.

parameter　command_line_args　Array(String) | String | Nil

Compiler arguments for parsing.

parameter　unsaved　Array(UnsavedFile)

Unsaved file buffers.

parameter　index_opts　Array(Symbol)

Indexing options.

parameter　translation_unit_opts　Array(Symbol)

Translation unit parsing options.

yields　{|event, payload| ...}

Each indexing event and its payload.

parameter　event　Symbol

The event type.

parameter　payload　Array(Diagnostic) | File | IncludedFile | ImportedASTFile | Declaration | EntityReference | NilClass

The event payload.

returns　Enumerator

If no block is given.

returns　TranslationUnit | Nil

The indexed translation unit, or nil if indexing was aborted.

raises　Error

If libclang fails to index the source file.

Implementation

 
def index_source_file(source_file, command_line_args = nil, unsaved = [], index_opts = [], translation_unit_opts = [], &block)
	return to_enum(__method__, source_file, command_line_args, unsaved, index_opts, translation_unit_opts) unless block_given?
	
	command_line_args = normalized_command_line_args(command_line_args)
	args_pointer, _strings = args_pointer_from(command_line_args)
	unsaved_files = UnsavedFile.unsaved_pointer_from(unsaved)
	translation_unit_pointer_out = MemoryPointer.new(:pointer)
	adapter = CallbackAdapter.new(nil, &block)
	
	error_code = Lib.index_source_file(
		self,
		nil,
		adapter.callbacks,
		adapter.callbacks.size,
		index_options_bitmask_from(index_opts),
		source_file,
		args_pointer,
		command_line_args.length,
		unsaved_files,
		unsaved.length,
		translation_unit_pointer_out,
		translation_unit_options_bitmask_from(translation_unit_opts)
	)
	
	return nil if adapter.aborted?
	
	translation_unit_from_indexing_result(error_code, source_file, translation_unit_pointer_out)
end

def index_source_file_with_invocation(source_file, command_line_args = nil, unsaved = [], index_opts = [], translation_unit_opts = [], &block)

Index a source file using a full compiler command line including argv[0]. Event payloads:

  • :diagnostic => Array(Diagnostic)
  • :entered_main_file => FFI::Clang::File
  • :included_file => IncludedFile
  • :imported_ast_file => ImportedASTFile
  • :started_translation_unit => nil
  • :declaration => Declaration
  • :reference => EntityReference If the block returns :abort, libclang stops the next time it polls abortQuery, so a few more callbacks may be delivered before control returns.

Signature
parameter　source_file　String

The source file to index.

parameter　command_line_args　Array(String) | String | Nil

Full compiler arguments including argv[0].

parameter　unsaved　Array(UnsavedFile)

Unsaved file buffers.

parameter　index_opts　Array(Symbol)

Indexing options.

parameter　translation_unit_opts　Array(Symbol)

Translation unit parsing options.

yields　{|event, payload| ...}

Each indexing event and its payload.

parameter　event　Symbol

The event type.

parameter　payload　Array(Diagnostic) | File | IncludedFile | ImportedASTFile | Declaration | EntityReference | NilClass

The event payload.

returns　Enumerator

If no block is given.

returns　TranslationUnit | Nil

The indexed translation unit, or nil if indexing was aborted.

raises　Error

If libclang fails to index the source file.

Implementation

 
def index_source_file_with_invocation(source_file, command_line_args = nil, unsaved = [], index_opts = [], translation_unit_opts = [], &block)
	return to_enum(__method__, source_file, command_line_args, unsaved, index_opts, translation_unit_opts) unless block_given?
	
	command_line_args = normalized_command_line_args(command_line_args)
	args_pointer, _strings = args_pointer_from(command_line_args)
	unsaved_files = UnsavedFile.unsaved_pointer_from(unsaved)
	translation_unit_pointer_out = MemoryPointer.new(:pointer)
	adapter = CallbackAdapter.new(nil, &block)
	
	error_code = Lib.index_source_file_full_argv(
		self,
		nil,
		adapter.callbacks,
		adapter.callbacks.size,
		index_options_bitmask_from(index_opts),
		source_file,
		args_pointer,
		command_line_args.length,
		unsaved_files,
		unsaved.length,
		translation_unit_pointer_out,
		translation_unit_options_bitmask_from(translation_unit_opts)
	)
	
	return nil if adapter.aborted?
	
	translation_unit_from_indexing_result(error_code, source_file, translation_unit_pointer_out)
end

def index_translation_unit(translation_unit, index_opts = [], &block)

Index an existing translation unit and yield indexing events. Event payloads:

  • :diagnostic => Array(Diagnostic)
  • :entered_main_file => FFI::Clang::File
  • :included_file => IncludedFile
  • :imported_ast_file => ImportedASTFile
  • :started_translation_unit => nil
  • :declaration => Declaration
  • :reference => EntityReference If the block returns :abort, libclang stops the next time it polls abortQuery, so a few more callbacks may be delivered before control returns.

Signature
parameter　translation_unit　TranslationUnit

The translation unit to index.

parameter　index_opts　Array(Symbol)

Indexing options.

yields　{|event, payload| ...}

Each indexing event and its payload.

parameter　event　Symbol

The event type.

parameter　payload　Array(Diagnostic) | File | IncludedFile | ImportedASTFile | Declaration | EntityReference | NilClass

The event payload.

returns　Enumerator

If no block is given.

returns　TranslationUnit | Nil

The translation unit, or nil if indexing was aborted.

raises　Error

If libclang fails to index the translation unit.

Implementation

 
def index_translation_unit(translation_unit, index_opts = [], &block)
	return to_enum(__method__, translation_unit, index_opts) unless block_given?
	
	adapter = CallbackAdapter.new(translation_unit, &block)
	error_code = Lib.index_translation_unit(
		self,
		nil,
		adapter.callbacks,
		adapter.callbacks.size,
		index_options_bitmask_from(index_opts),
		translation_unit
	)
	
	return nil if adapter.aborted?
	
	raise_indexing_error(error_code, translation_unit.spelling) unless error_code == :cx_error_success
	
	translation_unit
end

def index_options_bitmask_from(opts)

Convert indexing options to a bitmask.

Signature
parameter　opts　Array(Symbol)

The indexing options.

returns　Integer

The resulting bitmask.

Implementation

 
def index_options_bitmask_from(opts)
	Lib.bitmask_from(Lib::IndexOptFlags, opts)
end

def translation_unit_from_indexing_result(error_code, source_file, translation_unit_pointer_out)

Build a translation unit from the result of an indexing call.

Signature
parameter　error_code　Symbol | Integer

The libclang error code.

parameter　source_file　String

The indexed source file.

parameter　translation_unit_pointer_out　FFI::MemoryPointer

The output pointer for the translation unit.

returns　TranslationUnit

The resulting translation unit.

raises　Error

If indexing failed.

Implementation

 
def translation_unit_from_indexing_result(error_code, source_file, translation_unit_pointer_out)
	raise_indexing_error(error_code, source_file) unless error_code == :cx_error_success
	
	translation_unit_pointer = translation_unit_pointer_out.read_pointer
	raise Error, "error indexing #{source_file.inspect}" if translation_unit_pointer.null?
	
	TranslationUnit.new(translation_unit_pointer, @index)
end

def raise_indexing_error(error_code, source)

Raise a Ruby error for a libclang indexing failure.

Signature
parameter　error_code　Symbol | Integer

The libclang error code.

parameter　source　String

The source path or translation unit spelling.

raises　Error

Always raises.

Implementation

 
def raise_indexing_error(error_code, source)
	error_name = error_code.is_a?(Symbol) ? error_code : Lib::ErrorCodes.find(error_code)
	raise Error, "error indexing #{source.inspect}: #{error_name || error_code}"
end