Eclipse CDT
7.0

org.eclipse.cdt.core.model
Interface ITranslationUnit

All Superinterfaces:
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.


Field Summary
static int AST_CONFIGURE_USING_SOURCE_CONTEXT
          Style constant for getAST(IIndex, int).
static int AST_CREATE_COMMENT_NODES
          Deprecated. The option has no effect.
static int AST_PARSE_INACTIVE_CODE
          Style constant for getAST(IIndex, int).
static int AST_SKIP_ALL_HEADERS
          Style constant for getAST(IIndex, int).
static int AST_SKIP_FUNCTION_BODIES
          Style constant for getAST(IIndex, int).
static int AST_SKIP_IF_NO_BUILD_INFO
          Style constant for getAST(IIndex, int).
static int AST_SKIP_INDEXED_HEADERS
          Style constant for getAST(IIndex, int).
static int AST_SKIP_NONINDEXED_HEADERS
          Style constant for getAST(IIndex, int).
static int AST_SKIP_TRIVIAL_EXPRESSIONS_IN_AGGREGATE_INITIALIZERS
          Style constant for getAST(IIndex, int).
 
Fields inherited from interface org.eclipse.cdt.core.model.ICElement
ASM_LABEL, C_ARCHIVE, C_BINARY, C_CCONTAINER, C_CLASS, C_CLASS_CTOR, C_CLASS_DECLARATION, C_CLASS_DTOR, C_ENUMERATION, C_ENUMERATOR, C_FIELD, C_FUNCTION, C_FUNCTION_DECLARATION, C_INCLUDE, C_MACRO, C_METHOD, C_METHOD_DECLARATION, C_MODEL, C_NAMESPACE, C_PROJECT, C_STORAGE_EXTERN, C_STORAGE_STATIC, C_STRUCT, C_STRUCT_DECLARATION, C_TEMPLATE_CLASS, C_TEMPLATE_CLASS_DECLARATION, C_TEMPLATE_FUNCTION, C_TEMPLATE_FUNCTION_DECLARATION, C_TEMPLATE_METHOD, C_TEMPLATE_METHOD_DECLARATION, C_TEMPLATE_STRUCT, C_TEMPLATE_STRUCT_DECLARATION, C_TEMPLATE_UNION, C_TEMPLATE_UNION_DECLARATION, C_TEMPLATE_VARIABLE, C_TYPEDEF, C_UNION, C_UNION_DECLARATION, C_UNIT, C_UNKNOWN_DECLARATION, C_USING, C_VARIABLE, C_VARIABLE_DECLARATION, C_VARIABLE_LOCAL, C_VCONTAINER, CPP_FRIEND, CPP_PRIVATE, CPP_PROTECTED, CPP_PUBLIC, EMPTY_ARRAY
 
Method Summary
 IInclude createInclude(java.lang.String name, boolean isStd, ICElement sibling, IProgressMonitor monitor)
          Creates and returns an include declaration in this translation unit with the given name.
 INamespace createNamespace(java.lang.String namespace, ICElement sibling, IProgressMonitor monitor)
          Creates and returns a namespace in this translation unit
 IUsing createUsing(java.lang.String name, boolean isDirective, ICElement sibling, IProgressMonitor monitor)
          Creates and returns a using declaration/directive in this translation unit.
 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.
 IWorkingCopy findSharedWorkingCopy(org.eclipse.cdt.internal.core.model.IBufferFactory bufferFactory)
          Deprecated. use findSharedWorkingCopy(), or CDTUITools.getWorkingCopyManager() instead.
 IASTTranslationUnit getAST()
          Creates the full AST for this translation unit.
 IASTTranslationUnit getAST(org.eclipse.cdt.core.index.IIndex index, int style)
          Creates an AST based on the requested style.
 org.eclipse.cdt.core.parser.CodeReader getCodeReader()
          Deprecated. 
 IASTCompletionNode getCompletionNode(org.eclipse.cdt.core.index.IIndex index, int style, int offset)
          Return the completion node using the given index and parsing style at the given offset.
 char[] getContents()
          Returns the contents of a translation unit as a char[]
 java.lang.String getContentTypeId()
          Return the contentType id for this file.
 ICElement getElement(java.lang.String name)
           
 ICElement getElementAtLine(int line)
          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.
 ICElement getElementAtOffset(int offset)
          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.
 ICElement[] getElementsAtOffset(int offset)
          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.
 IInclude getInclude(java.lang.String name)
          Returns the include declaration in this translation unit with the given name.
 IInclude[] getIncludes()
          Returns the include declarations in this translation unit in the order in which they appear in the source.
 ILanguage getLanguage()
          Return the language for this translation unit.
 IPath getLocation()
          Returns the absolute path of the location of the translation unit.
 INamespace getNamespace(java.lang.String name)
          Returns the first namespace declaration in this translation unit with the given name This is a handle-only method.
 INamespace[] getNamespaces()
          Returns the namespace declarations in this translation unit in the order in which they appear in the source.
 org.eclipse.cdt.core.parser.IScannerInfo getScannerInfo(boolean force)
          Returns the scanner info associated with this translation unit.
 IWorkingCopy getSharedWorkingCopy(IProgressMonitor monitor, org.eclipse.cdt.internal.core.model.IBufferFactory factory)
          Deprecated. use getSharedWorkingCopy(IProgressMonitor, IProblemRequestor), or CDTUITools.getWorkingCopyManager() instead.
 IWorkingCopy getSharedWorkingCopy(IProgressMonitor monitor, org.eclipse.cdt.internal.core.model.IBufferFactory factory, IProblemRequestor requestor)
          Deprecated. use getSharedWorkingCopy(IProgressMonitor, IProblemRequestor), or CDTUITools.getWorkingCopyManager() instead.
 IWorkingCopy getSharedWorkingCopy(IProgressMonitor monitor, IProblemRequestor requestor)
          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.
 IUsing getUsing(java.lang.String name)
          Returns the first using in this translation unit with the name This is a handle-only method.
 IUsing[] getUsings()
          Returns the usings in this translation unit in the order in which they appear in the source.
 IWorkingCopy getWorkingCopy()
          Returns a new working copy for the Translation Unit.
 IWorkingCopy getWorkingCopy(IProgressMonitor monitor)
          Returns a new working copy for the Translation Unit.
 IWorkingCopy getWorkingCopy(IProgressMonitor monitor, org.eclipse.cdt.internal.core.model.IBufferFactory factory)
          Deprecated. use getWorkingCopy(IProgressMonitor), or CDTUITools.getWorkingCopyManager() instead.
 boolean isASMLanguage()
          Returns true if the code is assembly
 boolean isCLanguage()
          Returns true if the code is C
 boolean isCXXLanguage()
          Returns true if the code is C++
 boolean isHeaderUnit()
          True if its a header.
 boolean isSourceUnit()
          True it is a source file.
 boolean isWorkingCopy()
          Checks if this is a working copy.
 java.util.Map<?,?> parse()
          Deprecated. don't use this method.
 void setIsStructureKnown(boolean wasSuccessful)
          Used by contributed languages' model builders to indicate whether or not the parse of a translation unit was successful.
 
Methods inherited from interface org.eclipse.cdt.core.model.ICElement
accept, exists, getAncestor, getCModel, getCProject, getElementName, getElementType, getHandleIdentifier, getLocationURI, getParent, getPath, getResource, getUnderlyingResource, isReadOnly, isStructureKnown
 
Methods inherited from interface org.eclipse.cdt.core.model.IParent
getChildren, getChildrenOfType, hasChildren
 
Methods inherited from interface org.eclipse.cdt.core.model.IOpenable
close, getBuffer, hasUnsavedChanges, isConsistent, isOpen, makeConsistent, makeConsistent, open, save
 
Methods inherited from interface org.eclipse.cdt.core.model.IBufferChangedListener
bufferChanged
 
Methods inherited from interface org.eclipse.cdt.core.model.ISourceReference
getIndex, getSource, getSourceRange, getTranslationUnit, isActive
 
Methods inherited from interface org.eclipse.cdt.core.model.ISourceManipulation
copy, delete, move, rename
 

Field Detail

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:
Constant Field Values

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_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:
Constant Field Values

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

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

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:
Constant Field Values
Method Detail

createInclude

IInclude createInclude(java.lang.String name,
                       boolean isStd,
                       ICElement sibling,
                       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(java.lang.String name,
                   boolean isDirective,
                   ICElement sibling,
                   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(java.lang.String namespace,
                           ICElement sibling,
                           IProgressMonitor monitor)
                           throws CModelException
Creates and returns a namespace in this translation unit

Parameters:
name - 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.

Parameters:
bufferFactory - the given IBuffer factory
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:
position - 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:
position - 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(java.lang.String name)
                     throws CModelException
Throws:
CModelException

getInclude

IInclude getInclude(java.lang.String name)
Returns the include declaration in this translation unit with the given name.

Parameters:
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(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:

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(java.lang.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(java.lang.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(IProgressMonitor monitor)
                            throws CModelException
Returns a new working copy for the Translation Unit.

Throws:
CModelException
Since:
5.1

getContentTypeId

java.lang.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 CoreException
Return the language for this translation unit.

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

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

getScannerInfo

org.eclipse.cdt.core.parser.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 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:
CoreException
Since:
4.0

getAST

IASTTranslationUnit getAST(org.eclipse.cdt.core.index.IIndex index,
                           int style)
                           throws 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:
CoreException
Since:
4.0

getCompletionNode

IASTCompletionNode getCompletionNode(org.eclipse.cdt.core.index.IIndex index,
                                     int style,
                                     int offset)
                                     throws CoreException
Return the completion node using the given index and parsing style at the given offset.

Throws:
CoreException

getSharedWorkingCopy

@Deprecated
IWorkingCopy getSharedWorkingCopy(IProgressMonitor monitor,
                                             org.eclipse.cdt.internal.core.model.IBufferFactory factory)
                                  throws CModelException
Deprecated. use getSharedWorkingCopy(IProgressMonitor, IProblemRequestor), or CDTUITools.getWorkingCopyManager() instead.

Throws:
CModelException

getSharedWorkingCopy

@Deprecated
IWorkingCopy getSharedWorkingCopy(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

findSharedWorkingCopy

@Deprecated
IWorkingCopy findSharedWorkingCopy(org.eclipse.cdt.internal.core.model.IBufferFactory bufferFactory)
Deprecated. use findSharedWorkingCopy(), or CDTUITools.getWorkingCopyManager() instead.


getWorkingCopy

@Deprecated
IWorkingCopy getWorkingCopy(IProgressMonitor monitor,
                                       org.eclipse.cdt.internal.core.model.IBufferFactory factory)
                            throws CModelException
Deprecated. use getWorkingCopy(IProgressMonitor), or CDTUITools.getWorkingCopyManager() instead.

Throws:
CModelException

parse

@Deprecated
java.util.Map<?,?> parse()
Deprecated. don't use this method.


getCodeReader

@Deprecated
org.eclipse.cdt.core.parser.CodeReader getCodeReader()
Deprecated. 


Eclipse CDT
7.0

Copyright (c) IBM Corp. and others 2004, 2012. All Rights Reserved.