Eclipse CDT
Pre-release 3.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
          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).
 
Fields inherited from interface org.eclipse.cdt.core.model.ICElement
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
 
Method Summary
 IInclude createInclude(String name, boolean isStd, ICElement sibling, IProgressMonitor monitor)
          Creates and returns an include declaration in this translation unit with the given name.
 INamespace createNamespace(String namespace, ICElement sibling, IProgressMonitor monitor)
          Creates and returns a namespace in this translation unit
 IUsing createUsing(String name, boolean isDirective, ICElement sibling, IProgressMonitor monitor)
          Creates and returns a using declaration/directive in this translation unit
 IWorkingCopy findSharedWorkingCopy(org.eclipse.cdt.internal.core.model.IBufferFactory bufferFactory)
          Finds the shared working copy for this element, given a IBuffer factory.
 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()
          Returns the code reader that can be used to parse the translation unit.
 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[]
 String getContentTypeId()
          Return the contentType id for this file.
 ICElement getElement(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(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(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)
          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.
 IWorkingCopy getSharedWorkingCopy(IProgressMonitor monitor, org.eclipse.cdt.internal.core.model.IBufferFactory factory, 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(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, org.eclipse.cdt.internal.core.model.IBufferFactory factory)
          Returns a new working copy for the Translation Unit.
 boolean isASMLanguage()
          True if assembly
 boolean isCLanguage()
          True if the code is C
 boolean isCXXLanguage()
          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.
 Map parse()
          Deprecated. this is currently only used by the core tests. It should be removed from the interface.
 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, 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
getSource, getSourceRange, getTranslationUnit
 
Methods inherited from interface org.eclipse.cdt.core.model.ISourceManipulation
copy, delete, move, rename
 

Field Detail

AST_SKIP_FUNCTION_BODIES

public 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

public 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

public 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

public 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

public 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

public static final int AST_CREATE_COMMENT_NODES
Style constant for getAST(IIndex, int). Meaning: Add nodes for comments to the ast.

Since:
4.0
See Also:
Constant Field Values

AST_CONFIGURE_USING_SOURCE_CONTEXT

public 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
Method Detail

createInclude

public IInclude createInclude(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

public IUsing createUsing(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

public INamespace createNamespace(String namespace,
                                  ICElement sibling,
                                  IProgressMonitor monitor)
                           throws CModelException
Creates and returns a namespace in this translation unit

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

public IWorkingCopy findSharedWorkingCopy(org.eclipse.cdt.internal.core.model.IBufferFactory bufferFactory)
Finds the shared working copy for this element, given a IBuffer factory. If no working copy has been created for this element associated with this buffer factory, returns null.

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, null if none
Since:
2.0
See Also:
IBufferFactory

getContents

public char[] getContents()
Returns the contents of a translation unit as a char[]

Returns:
char[]

getElementAtLine

public 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

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

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

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

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

public ICElement getElement(String name)
                     throws CModelException
Throws:
CModelException

getInclude

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

Returns:
a handle onto the corresponding include declaration. The include declaration may or may not exist.

getIncludes

public 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

public IWorkingCopy getSharedWorkingCopy(IProgressMonitor monitor,
                                         org.eclipse.cdt.internal.core.model.IBufferFactory factory)
                                  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
factory - the factory that creates a buffer that is used to get the content of the working copy or null if the internal factory should be used
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:
2.0
See Also:
IBufferFactory, IProblemRequestor

getSharedWorkingCopy

public IWorkingCopy getSharedWorkingCopy(IProgressMonitor monitor,
                                         org.eclipse.cdt.internal.core.model.IBufferFactory factory,
                                         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
factory - the factory that creates a buffer that is used to get the content of the working copy or null if the internal factory should be used
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:
2.0
See Also:
IBufferFactory, IProblemRequestor

getUsing

public 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

public 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

public 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

public 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

public boolean isHeaderUnit()
True if its a header.

Returns:
boolean

isSourceUnit

public boolean isSourceUnit()
True it is a source file.

Returns:
boolean

isCLanguage

public boolean isCLanguage()
True if the code is C

Returns:

isCXXLanguage

public boolean isCXXLanguage()
True if the code is C++

Returns:

isASMLanguage

public boolean isASMLanguage()
True if assembly

Returns:

getWorkingCopy

public IWorkingCopy getWorkingCopy()
                            throws CModelException
Returns a new working copy for the Translation Unit.

Returns:
IWorkingCopy
Throws:
CModelException

getWorkingCopy

public IWorkingCopy getWorkingCopy(IProgressMonitor monitor,
                                   org.eclipse.cdt.internal.core.model.IBufferFactory factory)
                            throws CModelException
Returns a new working copy for the Translation Unit.

Returns:
IWorkingCopy
Throws:
CModelException

getContentTypeId

public String getContentTypeId()
Return the contentType id for this file.

Returns:
String - contentType id

isWorkingCopy

public boolean isWorkingCopy()
Checks if this is a working copy.

Returns:
boolean

parse

public Map parse()
Deprecated. this is currently only used by the core tests. It should be removed from the interface.

parse() returns a map of all new elements and their element info


getLanguage

public ILanguage getLanguage()
                      throws CoreException
Return the language for this translation unit.

Returns:
Throws:
CoreException

setIsStructureKnown

public 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

public 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

getCodeReader

public org.eclipse.cdt.core.parser.CodeReader getCodeReader()
Returns the code reader that can be used to parse the translation unit. If the translation unit is a working copy the reader will read from the buffer.

Returns:
a code reader for parsing the translation unit
Since:
4.0

getScannerInfo

public 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

public 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

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

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, AST_CREATE_COMMENT_NODES and AST_CONFIGURE_USING_SOURCE_CONTEXT.
Returns:
the AST requested or null
Throws:
CoreException
Since:
4.0

getCompletionNode

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

Parameters:
index -
style -
offset -
Returns:
Throws:
CoreException

Eclipse CDT
Pre-release 3.0

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