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
 
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 getASTTranslationUnit()
          Returns the root object of a DOM Abstract syntax tree.
 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.
 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.
 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()
          parse() returns a map of all new elements and their element info
 
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
 

Method Detail

createInclude

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

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

INamespace createNamespace(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(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

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(String name)
                     throws CModelException
Throws:
CModelException

getInclude

IInclude getInclude(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,
                                  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
problemRequestor - 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:
2.0
See Also:
IBufferFactory, IProblemRequestor

getSharedWorkingCopy

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
problemRequestor - 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:
2.0
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()
True if the code is C

Returns:

isCXXLanguage

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

Returns:

isASMLanguage

boolean isASMLanguage()
True if assembly

Returns:

getWorkingCopy

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

Returns:
IWorkingCopy
Throws:
CModelException

getWorkingCopy

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

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

parse

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


getASTTranslationUnit

IASTTranslationUnit getASTTranslationUnit()
Returns the root object of a DOM Abstract syntax tree.

Returns:

Eclipse CDT
Pre-release 3.0

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