class Clangc::Index

An “index” consists of a set of translation units that would typically be linked together into an executable or library.

Public Class Methods

Clangc::Index.new(exclude_decl_from_pch, display_diagnostics) → click to toggle source
Clangc::Index

Provides a shared context for creating translation units.

It provides two options:

  • excludeDeclarationsFromPCH:

When true, allows enumeration of “local” declarations (when loading any new translation units). A “local” declaration is one that belongs in the translation unit itself and not in a precompiled header that was used by the translation unit. If false, all declarations will be enumerated. The process of creating the 'pch', loading it separately, and using it (via -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks (which gives the indexer the same performance benefit as the compiler).

  • displayDiagnostics:

When true, default diagnostics are displayed, when false, it is up to the user to display them.

VALUE
c_Index_initialize(VALUE self,
                   VALUE excl_decls_from_PCH,
                   VALUE display_diagnostics)
{
    Index_t *i;
    int c_excl_decls_from_PCH;
    int c_display_diagnostics;

    c_excl_decls_from_PCH = RBOOL_2_INT(excl_decls_from_PCH);
    c_display_diagnostics = RBOOL_2_INT(display_diagnostics);
    Data_Get_Struct(self, Index_t, i);

    i->data = clang_createIndex(c_excl_decls_from_PCH, c_display_diagnostics);
    return self;
}

Public Instance Methods

Clangc::Index#create_translation_unit(ast_file) → Clangc::TranslationUnit click to toggle source

Create a translation unit from an AST file name. If the creation fail, it returns nil. The AST file is created by clang with the option -emit-ast

VALUE
c_Index_create_TU(VALUE self, VALUE ast_file)
{
    Index_t *i;
    Data_Get_Struct(self, Index_t, i);
    VALUE tu;
    TranslationUnit_t *c_tu;
    R_GET_CLASS_DATA("Clangc", TranslationUnit, tu, c_tu);
    char *c_ast_file = NULL;
    c_ast_file = RSTRING_2_CHAR(ast_file);
    c_tu->data = clang_createTranslationUnit(i->data, c_ast_file);

    c_tu->parent = self;

    if (c_tu->data)
        return tu;
    else
        return Qnil;
}
Also aliased as: create_translation_unit_raw
Clangc::Index#create_translation_unit2(ast_file) → Clangc::TranslationUnit click to toggle source
or an error code

Create a translation unit from an AST file name. If the creation fail, it returns an error code Clangc::ErrorCode. With this implementation, Clangc::ErrorCode::Success is not used. The AST file is created by clang with the option -emit-ast

VALUE
c_Index_create_TU2(VALUE self, VALUE ast_file)
{
    Index_t *i;
    Data_Get_Struct(self, Index_t, i);
    VALUE tu;
    TranslationUnit_t *c_tu;
    R_GET_CLASS_DATA("Clangc", TranslationUnit, tu, c_tu);
    char *c_ast_file = NULL;
    c_ast_file = RSTRING_2_CHAR(ast_file);
    unsigned int er =
        clang_createTranslationUnit2(i->data, c_ast_file, &(c_tu->data));

    c_tu->parent = self;

    if (er != 0)
        return CUINT_2_NUM(er);
    else
        return tu;
}
Clangc::Index#create_translation_unit_from_source_file(source, args) → click to toggle source
Clangc::TranslationUnit

Return a TranslationUnit instance for a given source file and the provided command line arguments one would pass to the compiler.

  • source:

The source filename argument must be a string but is optional. If the caller provides a nil value, the name of the source file is expected to reside in the specified command line arguments.

  • args:

Must be an array of strings or empty. The command-line arguments that would be passed to the clang executable if it were being invoked out-of-process. These command-line options will be parsed and will affect how the translation unit is parsed. Note that the following options are ignored: '-c', '-emit-ast', '-fsyntax-only' (which is the default), and '-o <output file>'.

TODO : (not implemented yet)

  • num_unsaved_files

the number of unsaved file entries in unsaved_files.

  • unsaved_files

the files that have not yet been saved to disk but may be required for code completion, including the contents of those files. The contents and name of these files (as specified by CXUnsavedFile) are copied when necessary, so the client only needs to guarantee their validity until the call to this function returns.

VALUE
c_Index_create_TU_from_source_file(VALUE self, VALUE source_file, VALUE args)
{
    char *c_source_file = NULL;
    Index_t *i;
    VALUE tu;
    TranslationUnit_t *c_tu;

    c_source_file = RSTRING_2_CHAR(source_file);
    RARRAY_OF_STRINGS_2_C(args);
    Data_Get_Struct(self, Index_t, i);
    R_GET_CLASS_DATA("Clangc", TranslationUnit, tu, c_tu);

    c_tu->data = clang_createTranslationUnitFromSourceFile(
        i->data, c_source_file, len, c_args, 0, 0); // TODO manage unsaved files
    c_tu->parent = self;

    if (c_tu->data != NULL)
        return tu;
    else
        return Qnil;
}
create_translation_unit_raw(p1)

:call-seq:

Clangc::Index#translation_unit(options) => Clangc::TranslationUnit

Convenient method that easily allow to create a translation unit through different ways based on the options you use: :source => source file :args => command line arguments :error => true or false or nil :ast => String an ast file

Clangc::Index#global_options() → num click to toggle source

Gets the general options associated with an Index. A bitmask of options, a bitwise OR of the Clangc::GlobalOptFlags constants.

VALUE
c_Index_get_global_options(VALUE self)
{
    Index_t *i;
    Data_Get_Struct(self, Index_t, i);
    return CUINT_2_NUM(clang_CXIndex_getGlobalOptions(i->data));
}
Clangc::Index#global_options=(options) → nil click to toggle source

Sets general options associated with an Index instance.

  • options:

A bitmask of options, a bitwise OR of the Clangc::GlobalOptFlags constants.

VALUE
c_Index_set_global_options(VALUE self, VALUE options)
{
    Index_t *i;
    unsigned int c_options;

    Data_Get_Struct(self, Index_t, i);
    c_options = CLANGC_CONSTANT_TO_UINT("GlobalOptFlags", options);
    clang_CXIndex_setGlobalOptions(i->data, c_options);
    return Qnil;
}
Clangc::Index#parse_translation_unit(source_file, args, options) → click to toggle source
Clangc::TranslationUnit

Parse the given source file and generate the translation unit corresponding to that file.

This routine is the main entry point for the Clang C API, providing the ability to parse a source file into a translation unit that can then be queried by other functions in the API. This routine accepts a set of command-line arguments so that the compilation can be configured in the same way that the compiler is configured on the command line.

  • source_file:

The name of the source file to load, or nil if the source file is included in the command line arguments.

  • args:

The command-line arguments that would be passed to the clang executable if it were being invoked out-of-process. These command-line options will be parsed and will affect how the translation unit is parsed. Note that the following options are ignored: '-c', '-emit-ast', '-fsyntax-only' (which is the default), and '-o <output file>'.

  • options:

A bitmask of options that affects how the translation unit is managed but not its compilation. This should be a bitwise OR of the TranslationUnit_Flags constants.

TODO:

  • unsaved_files:

The files that have not yet been saved to disk but may be required for parsing, including the contents of those files. The contents and name of these files (as specified by CXUnsavedFile) are copied when necessary, so the client only needs to guarantee their validity until the call to this function returns.

  • num_unsaved_files:

The number of unsaved file entries in unsaved_files.

VALUE
c_Index_parse_TU(VALUE self, VALUE source_file, VALUE args, VALUE options)
{
    char *c_source_file = NULL;
    c_source_file = RSTRING_2_CHAR(source_file);

    unsigned int c_options = CLANGC_CONSTANT_TO_UINT("TranslationUnit_Flags",
                                                     options);

    RARRAY_OF_STRINGS_2_C(args);
    Index_t *i;
    Data_Get_Struct(self, Index_t, i);
    VALUE tu;
    TranslationUnit_t *c_tu;
    R_GET_CLASS_DATA("Clangc", TranslationUnit, tu, c_tu);

    c_tu->data =
        clang_parseTranslationUnit(i->data,
                                   c_source_file,
                                   c_args,
                                   len,
                                   0,
                                   0,
                                   c_options); // TODO manage unsaved files

    c_tu->parent = self;

    if (c_tu->data)
        return tu;
    else
        return Qnil;
}
Also aliased as: parse_translation_unit_raw
Clangc::Index#parse_translation_unit2(source_file, args, options) → click to toggle source
Clangc::TranslationUnit

Parse the given source file and generate the translation unit corresponding to that file. If its fails, it returns an Integer corresponding to the error code a Clangc::ErrorCode constant.

This routine is the main entry point for the Clang C API, providing the ability to parse a source file into a translation unit that can then be queried by other functions in the API. This routine accepts a set of command-line arguments so that the compilation can be configured in the same way that the compiler is configured on the command line.

  • source_file:

The name of the source file to load, or nil if the source file is included in the command line arguments.

  • args:

The command-line arguments that would be passed to the clang executable if it were being invoked out-of-process. These command-line options will be parsed and will affect how the translation unit is parsed. Note that the following options are ignored: '-c', '-emit-ast', '-fsyntax-only' (which is the default), and '-o <output file>'.

  • options:

A bitmask of options that affects how the translation unit is managed but not its compilation. This should be a bitwise OR of the TranslationUnit_Flags constants.

TODO:

  • unsaved_files:

The files that have not yet been saved to disk but may be required for parsing, including the contents of those files. The contents and name of these files (as specified by CXUnsavedFile) are copied when necessary, so the client only needs to guarantee their validity until the call to this function returns.

  • num_unsaved_files:

The number of unsaved file entries in unsaved_files.

VALUE
c_Index_parse_TU2(VALUE self, VALUE source_file, VALUE args, VALUE options)
{
    char *c_source_file = NULL;
    c_source_file = RSTRING_2_CHAR(source_file);

    unsigned int c_options = CLANGC_CONSTANT_TO_UINT("TranslationUnit_Flags",
                                                     options);

    RARRAY_OF_STRINGS_2_C(args);
    Index_t *i;
    Data_Get_Struct(self, Index_t, i);
    VALUE tu;
    TranslationUnit_t *c_tu;
    R_GET_CLASS_DATA("Clangc", TranslationUnit, tu, c_tu);

    unsigned int er =
        clang_parseTranslationUnit2(i->data,
                                    c_source_file,
                                    c_args,
                                    len,
                                    0,
                                    0,
                                    c_options, // TODO manage unsaved files
                                    &(c_tu->data));

    c_tu->parent = self;

    if (er != 0)
        return CUINT_2_NUM(er);
    else
        return tu;
}
parse_translation_unit_raw(p1, p2, p3)

:call-seq:

Clangc::Index#parse_translation_unit(options) => Clangc::TranslationUnit

Convenient method that easily allow to parse a file to a translation unit through different ways based on the options you use: :source => source file :args => command line arguments :error => true or false or nil :flags => bitwise OR of the TranslationUnit_Flags constants