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

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()
parse() returns a map of all new elements and their element info


getASTTranslationUnit

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