Package org.eclipse.cdt.core.model

Interface ITranslationUnit

All Superinterfaces:
org.eclipse.core.runtime.IAdaptable, IBufferChangedListener, ICElement, IOpenable, IParent, ISourceManipulation, ISourceReference
All Known Subinterfaces:
IWorkingCopy
public interface ITranslationUnit extends ICElement, IParent, IOpenable, ISourceReference, ISourceManipulation
Represents an entire C translation unit (.c source file). The children are of type IStructureElement, IInclude, etc.. and appear in the order in which they are declared in the source. If a .c file cannot be parsed, its structure remains unknown. Use ICElement.isStructureKnown to determine whether this is the case.
Restriction:
This interface is not intended to be implemented by clients.
Restriction:
This interface is not intended to be extended by clients.

  • Field Details

    • AST_SKIP_FUNCTION_BODIES

      static final int AST_SKIP_FUNCTION_BODIES
      Style constant for getAST(IIndex, int). Meaning: Skip function and method bodies.
      Since:
      4.0
      See Also:

    • 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:

    • AST_SKIP_NONINDEXED_HEADERS

      static final int AST_SKIP_NONINDEXED_HEADERS
      Style constant for getAST(IIndex, int). Meaning: Skip headers even if they are not found in the index. Makes practically only sense in combination with AST_SKIP_INDEXED_HEADERS.
      See Also:

    • AST_SKIP_ALL_HEADERS

      static final int AST_SKIP_ALL_HEADERS
      Style constant for getAST(IIndex, int). A combination of AST_SKIP_INDEXED_HEADERS and AST_SKIP_NONINDEXED_HEADERS. Meaning: Don't parse header files at all, be they indexed or not. Macro definitions and bindings are taken from the index if available.
      See Also:

    • 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:

    • AST_CREATE_COMMENT_NODES

      @Deprecated static final int AST_CREATE_COMMENT_NODES
      Deprecated.
      The option has no effect.
      Since:
      4.0
      See Also:
      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:

    • 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:

    • AST_PARSE_INACTIVE_CODE

      static final int AST_PARSE_INACTIVE_CODE
      Style constant for getAST(IIndex, int). Instructs the parser to make an attempt to create ast nodes for inactive code branches. The parser makes its best effort to create ast for the inactive code branches but may decide to skip parts of the inactive code (e.g. function bodies, entire code branches, etc.).

      The inactive nodes can be accessed via IASTDeclarationListOwner.getDeclarations(boolean) or by using a visitor with ASTVisitor.includeInactiveNodes set to true.

      Since:
      5.1
      See Also:

  • Method Details

    • 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

    • getElement

      ICElement getElement(String name) throws CModelException
      Throws:
      CModelException

    • 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:

    • 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() throws CModelException
      Returns a new working copy for the Translation Unit.
      Returns:
      IWorkingCopy
      Throws:
      CModelException

    • 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

    • getSharedWorkingCopy

      @Deprecated IWorkingCopy getSharedWorkingCopy(org.eclipse.core.runtime.IProgressMonitor monitor, org.eclipse.cdt.internal.core.model.IBufferFactory factory) throws CModelException
      Deprecated.
      use getSharedWorkingCopy(IProgressMonitor, IProblemRequestor), or CDTUITools.getWorkingCopyManager() instead.
      Throws:
      CModelException
      Restriction:
      This method is not intended to be referenced by clients.

    • getSharedWorkingCopy

      @Deprecated IWorkingCopy getSharedWorkingCopy(org.eclipse.core.runtime.IProgressMonitor monitor, org.eclipse.cdt.internal.core.model.IBufferFactory factory, IProblemRequestor requestor) throws CModelException
      Deprecated.
      use getSharedWorkingCopy(IProgressMonitor, IProblemRequestor), or CDTUITools.getWorkingCopyManager() instead.
      Throws:
      CModelException
      Restriction:
      This method is not intended to be referenced by clients.

    • 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.

    • getWorkingCopy

      @Deprecated IWorkingCopy getWorkingCopy(org.eclipse.core.runtime.IProgressMonitor monitor, org.eclipse.cdt.internal.core.model.IBufferFactory factory) throws CModelException
      Deprecated.
      use getWorkingCopy(IProgressMonitor), or CDTUITools.getWorkingCopyManager() instead.
      Throws:
      CModelException
      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.

    • getCodeReader

      @Deprecated CodeReader getCodeReader()
      Deprecated.
      Use FileContent.create(ITranslationUnit), instead.
      Restriction:
      This method is not intended to be referenced by clients.