Interface ITranslationUnit

    • Field Detail

      • AST_SKIP_INDEXED_HEADERS

        static final int AST_SKIP_INDEXED_HEADERS
        Style constant for getAST(IIndex, int). Meaning: Skip over headers that are found in the index, parse all others. Macro definitions and bindings are taken from index for skipped files.
        See Also:
        Constant Field Values
      • AST_SKIP_IF_NO_BUILD_INFO

        static final int AST_SKIP_IF_NO_BUILD_INFO
        Style constant for getAST(IIndex, int). Meaning: Don't parse the file if there is no build information for it.
        See Also:
        Constant Field Values
      • AST_CREATE_COMMENT_NODES

        @Deprecated
        static final int AST_CREATE_COMMENT_NODES
        Deprecated.
        The option has no effect.
        Since:
        4.0
        See Also:
        Constant Field Values
        Restriction:
        This field is not intended to be referenced by clients.
      • AST_CONFIGURE_USING_SOURCE_CONTEXT

        static final int AST_CONFIGURE_USING_SOURCE_CONTEXT
        Style constant for getAST(IIndex, int). Meaning: Configure the parser with language and build-information taken from a source file that directly or indirectly includes this file. If no suitable file is found in the index, the flag is ignored.
        Since:
        4.0
        See Also:
        Constant Field Values
      • AST_SKIP_TRIVIAL_EXPRESSIONS_IN_AGGREGATE_INITIALIZERS

        static final int AST_SKIP_TRIVIAL_EXPRESSIONS_IN_AGGREGATE_INITIALIZERS
        Style constant for getAST(IIndex, int). Instructs the parser not to create ast nodes for expressions within aggregate initializers when they do not contain names.
        Since:
        5.1
        See Also:
        Constant Field Values
    • Method Detail

      • createInclude

        IInclude createInclude​(String name,
                               boolean isStd,
                               ICElement sibling,
                               org.eclipse.core.runtime.IProgressMonitor monitor)
                        throws CModelException
        Creates and returns an include declaration in this translation unit with the given name.

        Optionally, the new element can be positioned before the specified sibling. If no sibling is specified, the element will be inserted as the last import declaration in this translation unit.

        If the translation unit already includes the specified include declaration, the import is not generated (it does not generate duplicates).

        Parameters:
        name - the name of the include declaration to add (For example: "stdio.h" or "sys/types.h")
        sibling - the existing element which the include declaration will be inserted immediately before (if null, then this include will be inserted as the last include declaration).
        monitor - the progress monitor to notify
        Returns:
        the newly inserted include declaration (or the previously existing one in case attempting to create a duplicate)
        Throws:
        CModelException - if the element could not be created. Reasons include:
        • This C element does not exist or the specified sibling does not exist (ELEMENT_DOES_NOT_EXIST)
        • A CoreException occurred while updating an underlying resource
        • The specified sibling is not a child of this translation unit (INVALID_SIBLING)
        • The name is not a valid import name (INVALID_NAME)
      • createUsing

        IUsing createUsing​(String name,
                           boolean isDirective,
                           ICElement sibling,
                           org.eclipse.core.runtime.IProgressMonitor monitor)
                    throws CModelException
        Creates and returns a using declaration/directive in this translation unit.
        Parameters:
        name - the name of the using
        monitor - the progress monitor to notify
        Returns:
        the newly inserted namespace declaration (or the previously existing one in case attempting to create a duplicate)
        Throws:
        CModelException - if the element could not be created. Reasons include:
        • This C element does not exist (ELEMENT_DOES_NOT_EXIST)
        • A CoreException occurred while updating an underlying resource
        • The name is not a valid package name (INVALID_NAME)
      • createNamespace

        INamespace createNamespace​(String namespace,
                                   ICElement sibling,
                                   org.eclipse.core.runtime.IProgressMonitor monitor)
                            throws CModelException
        Creates and returns a namespace in this translation unit
        Parameters:
        namespace - the name of the namespace
        monitor - the progress monitor to notify
        Returns:
        the newly inserted namespace declaration (or the previously existing one in case attempting to create a duplicate)
        Throws:
        CModelException - if the element could not be created. Reasons include:
        • This C element does not exist (ELEMENT_DOES_NOT_EXIST)
        • A CoreException occurred while updating an underlying resource
        • The name is not a valid package name (INVALID_NAME)
      • findSharedWorkingCopy

        IWorkingCopy findSharedWorkingCopy()
        Returns the shared working copy for this element, using the default IBuffer factory, or null, if no working copy has been created for this element.

        Users of this method must not destroy the resulting working copy.

        Returns:
        the found shared working copy for this element, or null if none
        Since:
        5.1
        See Also:
        IBufferFactory
      • getContents

        char[] getContents()
        Returns the contents of a translation unit as a char[]
        Returns:
        char[]
      • getElementAtLine

        ICElement getElementAtLine​(int line)
                            throws CModelException
        Returns the smallest element within this translation unit that includes the given source position (that is, a method, field, etc.), or null if there is no element other than the translation unit itself at the given position, or if the given position is not within the source range of this translation unit.
        Parameters:
        line - a position inside the translation unit
        Returns:
        the innermost C element enclosing a given source position or null if none (excluding the translation unit).
        Throws:
        CModelException - if the translation unit does not exist or if an exception occurs while accessing its corresponding resource
      • getElementAtOffset

        ICElement getElementAtOffset​(int offset)
                              throws CModelException
        Returns the smallest element within this translation unit that includes the given source position (that is, a method, field, etc.), or null if there is no element other than the translation unit itself at the given position, or if the given position is not within the source range of this translation unit.
        Parameters:
        offset - a source position inside the translation unit
        Returns:
        the innermost C element enclosing a given source position or null if none (excluding the translation unit).
        Throws:
        CModelException - if the translation unit does not exist or if an exception occurs while accessing its corresponding resource
      • getElementsAtOffset

        ICElement[] getElementsAtOffset​(int offset)
                                 throws CModelException
        Returns the elements within this translation unit that includes the given source position (that is, a method, field, etc.), or an empty array if there are no elements other than the translation unit itself at the given position, or if the given position is not within the source range of this translation unit. You have this behavior when at expansion of a macro.
        Parameters:
        offset - a source position inside the translation unit
        Returns:
        the innermost C element enclosing a given source position or null if none (excluding the translation unit).
        Throws:
        CModelException - if the translation unit does not exist or if an exception occurs while accessing its corresponding resource
      • getInclude

        IInclude getInclude​(String name)
        Returns the include declaration in this translation unit with the given name.
        Parameters:
        name - the name of the include to find (For example: "stdio.h" or "sys/types.h")
        Returns:
        a handle onto the corresponding include declaration. The include declaration may or may not exist.
      • getIncludes

        IInclude[] getIncludes()
                        throws CModelException
        Returns the include declarations in this translation unit in the order in which they appear in the source.
        Throws:
        CModelException - if this element does not exist or if an exception occurs while accessing its corresponding resource
      • getSharedWorkingCopy

        IWorkingCopy getSharedWorkingCopy​(org.eclipse.core.runtime.IProgressMonitor monitor,
                                          IProblemRequestor requestor)
                                   throws CModelException
        Returns a shared working copy on this element using the given factory to create the buffer, or this element if this element is already a working copy. This API can only answer an already existing working copy if it is based on the same original translation unit AND was using the same buffer factory (i.e. as defined by Object#equals).

        The life time of a shared working copy is as follows:

        • The first call to getSharedWorkingCopy(...) creates a new working copy for this element
        • Subsequent calls increment an internal counter.
        • A call to destroy() decrements the internal counter.
        • When this counter is 0, the working copy is destroyed.
        So users of this method must destroy exactly once the working copy.

        Note that the buffer factory will be used for the life time of this working copy, i.e. if the working copy is closed then reopened, this factory will be used. The buffer will be automatically initialized with the original's compilation unit content upon creation.

        When the shared working copy instance is created, an ADDED ICElementDelta is reported on this working copy.

        Parameters:
        monitor - a progress monitor used to report progress while opening this compilation unit or null if no progress should be reported
        requestor - a requestor which will get notified of problems detected during reconciling as they are discovered. The requestor can be set to null indicating that the client is not interested in problems.
        Returns:
        a shared working copy on this element using the given factory to create the buffer, or this element if this element is already a working copy
        Throws:
        CModelException - if the contents of this element can not be determined. Reasons include:
        • This C element does not exist (ELEMENT_DOES_NOT_EXIST)
        Since:
        5.1
        See Also:
        IBufferFactory, IProblemRequestor
      • getUsing

        IUsing getUsing​(String name)
        Returns the first using in this translation unit with the name This is a handle-only method. The namespace declaration may or may not exist.
        Parameters:
        name - the name of the namespace declaration (For example, "std")
      • getUsings

        IUsing[] getUsings()
                    throws CModelException
        Returns the usings in this translation unit in the order in which they appear in the source.
        Returns:
        an array of namespace declaration (normally of size one)
        Throws:
        CModelException - if this element does not exist or if an exception occurs while accessing its corresponding resource
      • getNamespace

        INamespace getNamespace​(String name)
        Returns the first namespace declaration in this translation unit with the given name This is a handle-only method. The namespace declaration may or may not exist.
        Parameters:
        name - the name of the namespace declaration (For example, "std")
      • getNamespaces

        INamespace[] getNamespaces()
                            throws CModelException
        Returns the namespace declarations in this translation unit in the order in which they appear in the source.
        Returns:
        an array of namespace declaration (normally of size one)
        Throws:
        CModelException - if this element does not exist or if an exception occurs while accessing its corresponding resource
      • isHeaderUnit

        boolean isHeaderUnit()
        True if its a header.
        Returns:
        boolean
      • isSourceUnit

        boolean isSourceUnit()
        True it is a source file.
        Returns:
        boolean
      • isCLanguage

        boolean isCLanguage()
        Returns true if the code is C
      • isCXXLanguage

        boolean isCXXLanguage()
        Returns true if the code is C++
      • isASMLanguage

        boolean isASMLanguage()
        Returns true if the code is assembly
      • getWorkingCopy

        IWorkingCopy getWorkingCopy​(org.eclipse.core.runtime.IProgressMonitor monitor)
                             throws CModelException
        Returns a new working copy for the Translation Unit.
        Throws:
        CModelException
        Since:
        5.1
      • getContentTypeId

        String getContentTypeId()
        Return the contentType id for this file.
        Returns:
        String - contentType id
      • isWorkingCopy

        boolean isWorkingCopy()
        Checks if this is a working copy.
        Returns:
        boolean
      • getLanguage

        ILanguage getLanguage()
                       throws org.eclipse.core.runtime.CoreException
        Return the language for this translation unit.
        Throws:
        org.eclipse.core.runtime.CoreException
      • setIsStructureKnown

        void setIsStructureKnown​(boolean wasSuccessful)
        Used by contributed languages' model builders to indicate whether or not the parse of a translation unit was successful.
        Parameters:
        wasSuccessful - TODO (DS) I'm not sure it's a good idea to put a setter in this interface. We should revisit this.
      • getLocation

        org.eclipse.core.runtime.IPath getLocation()
        Returns the absolute path of the location of the translation unit. May be null, in case the location does not exist.
        Returns:
        an absolute path to the location, or null
        Since:
        4.0
      • getFile

        org.eclipse.core.resources.IFile getFile()
        Returns the corresponding file for this translation unit, or null if this translation unit does not have a corresponding file.
        Returns:
        the corresponding file, or null if none
        Since:
        5.9
      • getScannerInfo

        IScannerInfo getScannerInfo​(boolean force)
        Returns the scanner info associated with this translation unit. May return null if no configuration is available.
        Parameters:
        force - if true a default info is returned, even if nothing is configured for this translation unit
        Returns:
        a scanner info for parsing the translation unit or null if none is configured
        Since:
        4.0
      • getAST

        IASTTranslationUnit getAST()
                            throws org.eclipse.core.runtime.CoreException
        Creates the full AST for this translation unit. May return null if the language of this translation unit does not support ASTs.
        Returns:
        the AST for the translation unit or null
        Throws:
        org.eclipse.core.runtime.CoreException
        Since:
        4.0
      • getAST

        IASTTranslationUnit getAST​(IIndex index,
                                   int style)
                            throws org.eclipse.core.runtime.CoreException
        Creates an AST based on the requested style. May return null if the language of this translation unit does not support ASTs. If the index was supplied, the caller has to hold a read lock on it. The returned AST is valid only while the index read lock is being held and should not be accessed after releasing the lock.
        Parameters:
        index - index to back up the parsing of the AST, may be null
        style - 0 or a combination of AST_SKIP_ALL_HEADERS, AST_SKIP_IF_NO_BUILD_INFO, AST_SKIP_INDEXED_HEADERS and AST_CONFIGURE_USING_SOURCE_CONTEXT.
        Returns:
        the AST requested or null
        Throws:
        org.eclipse.core.runtime.CoreException
        Since:
        4.0
      • getCompletionNode

        IASTCompletionNode getCompletionNode​(IIndex index,
                                             int style,
                                             int offset)
                                      throws org.eclipse.core.runtime.CoreException
        Returns the completion node using the given index and parsing style at the given offset.
        Throws:
        org.eclipse.core.runtime.CoreException
      • findSharedWorkingCopy

        @Deprecated
        IWorkingCopy findSharedWorkingCopy​(org.eclipse.cdt.internal.core.model.IBufferFactory bufferFactory)
        Deprecated.
        use findSharedWorkingCopy(), or CDTUITools.getWorkingCopyManager() instead.
        Restriction:
        This method is not intended to be referenced by clients.
      • parse

        @Deprecated
        Map<?,​?> parse()
        Deprecated.
        don't use this method.
        Restriction:
        This method is not intended to be referenced by clients.