org.eclipse.cdt.managedbuilder.macros
Interface IBuildMacroProvider

All Known Implementing Classes:
BuildMacroProvider

public interface IBuildMacroProvider

Since:
3.0

Field Summary
static int CONTEXT_CONFIGURATION
           
static int CONTEXT_ECLIPSEENV
           
static int CONTEXT_FILE
           
static int CONTEXT_INSTALLATIONS
           
static int CONTEXT_OPTION
           
static int CONTEXT_PROJECT
           
static int CONTEXT_TOOL
           
static int CONTEXT_WORKSPACE
           
 
Method Summary
 void checkIntegrity(int contextType, java.lang.Object contextData)
          checks the integrity of the Macros If there are inconsistencies, such as when a macro value refers to a nonexistent macro or when two macros refer to each other, this method will throw the BuildMacroException exception The BuildMacroException will contain the human-readable string describing the inconsistency and the array of the IBuildMacro interfaces that will represent the macros that caused the inconsistency.
 java.lang.String convertStringListToString(java.lang.String[] value, java.lang.String listDelimiter)
          converts StringList value into String of the following format: "< listDelimiter >< listDelimiter > ...
 IBuildMacro getMacro(java.lang.String macroName, int contextType, java.lang.Object contextData, boolean includeParentContexts)
          Returns reference to the IBuildMacro interface representing Macro of the specified name or null if there is there is no such macro
 IBuildMacro[] getMacros(int contextType, java.lang.Object contextData, boolean includeParentContexts)
           
 IBuildMacroSupplier[] getSuppliers(int contextType, java.lang.Object contextData)
          This method is defined to be used primarily by the UI classes and should not be used by the tool-integrator
 ICdtVariable getVariable(java.lang.String macroName, int contextType, java.lang.Object contextData, boolean includeParentContexts)
           
 ICdtVariable[] getVariables(int contextType, java.lang.Object contextData, boolean includeParentContexts)
           
 boolean isStringListValue(java.lang.String value, int contextType, java.lang.Object contextData)
           
 java.lang.String[] resolveStringListValue(java.lang.String value, java.lang.String nonexistentMacrosValue, java.lang.String listDelimiter, int contextType, java.lang.Object contextData)
          if the string contains a value that can be treated as a StringList resolves it to arrays of strings otherwise throws the BuildMacroException exception
 java.lang.String[] resolveStringListValues(java.lang.String[] value, java.lang.String nonexistentMacrosValue, java.lang.String listDelimiter, int contextType, java.lang.Object contextData)
          resolves macros in the array of string-list values
 java.lang.String[] resolveStringListValuesToMakefileFormat(java.lang.String[] value, java.lang.String nonexistentMacrosValue, java.lang.String listDelimiter, int contextType, java.lang.Object contextData)
          resolves macros in the array of string-list values macros are resolved to the makefile format
 java.lang.String[] resolveStringListValueToMakefileFormat(java.lang.String value, java.lang.String nonexistentMacrosValue, java.lang.String listDelimiter, int contextType, java.lang.Object contextData)
          if the string contains a value that can be treated as a StringList resolves it to arrays of strings otherwise throws the BuildMacroException exception each string of the returned array will contain all macro references resolved in case of a user has specified to resolve the build macros, and will contain the string with the environment macro references unresolved and converted to the buildfile format otherwise
 java.lang.String resolveValue(java.lang.String value, java.lang.String nonexistentMacrosValue, java.lang.String listDelimiter, int contextType, java.lang.Object contextData)
          resolves all macros in the string.
 java.lang.String resolveValueToMakefileFormat(java.lang.String value, java.lang.String nonexistentMacrosValue, java.lang.String listDelimiter, int contextType, java.lang.Object contextData)
          resolves all macros in the string to the makefile format.
 

Field Detail

CONTEXT_FILE

static final int CONTEXT_FILE
See Also:
Constant Field Values

CONTEXT_OPTION

static final int CONTEXT_OPTION
See Also:
Constant Field Values

CONTEXT_CONFIGURATION

static final int CONTEXT_CONFIGURATION
See Also:
Constant Field Values

CONTEXT_PROJECT

static final int CONTEXT_PROJECT
See Also:
Constant Field Values

CONTEXT_WORKSPACE

static final int CONTEXT_WORKSPACE
See Also:
Constant Field Values

CONTEXT_INSTALLATIONS

static final int CONTEXT_INSTALLATIONS
See Also:
Constant Field Values

CONTEXT_ECLIPSEENV

static final int CONTEXT_ECLIPSEENV
See Also:
Constant Field Values

CONTEXT_TOOL

static final int CONTEXT_TOOL
See Also:
Constant Field Values
Method Detail

getMacro

IBuildMacro getMacro(java.lang.String macroName,
                     int contextType,
                     java.lang.Object contextData,
                     boolean includeParentContexts)
Returns reference to the IBuildMacro interface representing Macro of the specified name or null if there is there is no such macro

Parameters:
macroName - macro name
contextType - represents the context type. Should be set to one of the the IBuildMacroProvider. CONTEXT_xxx constants
contextData - represents the additional data needed by the Build Macro Provider and Macro Suppliers in order to obtain the macro value. The type of the context data differs depending on the context type and can be one of the following: 1. IFileContextData interface � used to represent currently selected file context the IFileContextData interface is defined as follows: pulic interface IFileContextData{ IFile getFile(); IOption getOption(); } NOTE: the IFileContextData is passed that represents the current file and the option for that file because Macro Value Provider needs to know what option should be used as a context in case macro is not found for �current file� context 2. IOptionContextData interface used to represent the currently selected option context 3. IConfiguration � used to represent the currently selected configuration context 4. IProject � used to represent current project context 5. IWorkspace � used to represent current workspace context 6. null � to represent the CDT and Eclipse installation context 7. null � to represent process environment context
includeParentContext - specifies whether lower-precedence context macros should be included

getMacros

IBuildMacro[] getMacros(int contextType,
                        java.lang.Object contextData,
                        boolean includeParentContexts)
Returns:
the array of the IBuildMacro representing all available macros

getVariable

ICdtVariable getVariable(java.lang.String macroName,
                         int contextType,
                         java.lang.Object contextData,
                         boolean includeParentContexts)

getVariables

ICdtVariable[] getVariables(int contextType,
                            java.lang.Object contextData,
                            boolean includeParentContexts)
Returns:
the array of the IBuildMacro representing all available macros

getSuppliers

IBuildMacroSupplier[] getSuppliers(int contextType,
                                   java.lang.Object contextData)
This method is defined to be used primarily by the UI classes and should not be used by the tool-integrator

Returns:
the array of the provider-internal suppliers for the given context

convertStringListToString

java.lang.String convertStringListToString(java.lang.String[] value,
                                           java.lang.String listDelimiter)
converts StringList value into String of the following format: "< listDelimiter >< listDelimiter > ... "


resolveValue

java.lang.String resolveValue(java.lang.String value,
                              java.lang.String nonexistentMacrosValue,
                              java.lang.String listDelimiter,
                              int contextType,
                              java.lang.Object contextData)
                              throws BuildMacroException
resolves all macros in the string.

Parameters:
value - the value to be resolved
nonexistentMacrosValue - specifies the value that inexistent macro references will be expanded to. If null the BuildMacroException is thrown in case the string to be resolved references inexistent macros
listDelimiter - if not null, StringList macros are expanded as �< listDelimiter >< listDelimiter > ... � otherwise the BuildMacroException is thrown in case the string to be resolved references string-list macros
contextType - context from which the macro search should be started
contextData - context data
Throws:
BuildMacroException

resolveStringListValue

java.lang.String[] resolveStringListValue(java.lang.String value,
                                          java.lang.String nonexistentMacrosValue,
                                          java.lang.String listDelimiter,
                                          int contextType,
                                          java.lang.Object contextData)
                                          throws BuildMacroException
if the string contains a value that can be treated as a StringList resolves it to arrays of strings otherwise throws the BuildMacroException exception

Throws:
BuildMacroException
See Also:
isStringListValue

resolveStringListValues

java.lang.String[] resolveStringListValues(java.lang.String[] value,
                                           java.lang.String nonexistentMacrosValue,
                                           java.lang.String listDelimiter,
                                           int contextType,
                                           java.lang.Object contextData)
                                           throws BuildMacroException
resolves macros in the array of string-list values

Throws:
BuildMacroException
See Also:
isStringListValue

resolveValueToMakefileFormat

java.lang.String resolveValueToMakefileFormat(java.lang.String value,
                                              java.lang.String nonexistentMacrosValue,
                                              java.lang.String listDelimiter,
                                              int contextType,
                                              java.lang.Object contextData)
                                              throws BuildMacroException
resolves all macros in the string to the makefile format. That is: 1. In case when a user has specified to resolve the environment build macros all macros get resolved in the string 2. In case when the a user has specified not to resolve the environment build macros all macros get resolved except the build environment macros (macros whose name conflicts with one of reserved macro names, or string-list macros always get resolved in the buildfile). Macro references that are kept unresolved are converted to the makefile format

Parameters:
value - the value to be resolved
nonexistentMacrosValue - specifies the value that inexistent macro references will be expanded to. If null the BuildMacroException is thrown in case the string to be resolved references inexistent macros
listDelimiter - if not null, StringList macros are expanded as �< listDelimiter >< listDelimiter > ... � otherwise the BuildMacroException is thrown in case the string to be resolved references string-list macros
contextType - context from which the macro search should be started
contextData - context data
Throws:
BuildMacroException

resolveStringListValueToMakefileFormat

java.lang.String[] resolveStringListValueToMakefileFormat(java.lang.String value,
                                                          java.lang.String nonexistentMacrosValue,
                                                          java.lang.String listDelimiter,
                                                          int contextType,
                                                          java.lang.Object contextData)
                                                          throws BuildMacroException
if the string contains a value that can be treated as a StringList resolves it to arrays of strings otherwise throws the BuildMacroException exception each string of the returned array will contain all macro references resolved in case of a user has specified to resolve the build macros, and will contain the string with the environment macro references unresolved and converted to the buildfile format otherwise

Throws:
BuildMacroException
See Also:
isStringListValue

resolveStringListValuesToMakefileFormat

java.lang.String[] resolveStringListValuesToMakefileFormat(java.lang.String[] value,
                                                           java.lang.String nonexistentMacrosValue,
                                                           java.lang.String listDelimiter,
                                                           int contextType,
                                                           java.lang.Object contextData)
                                                           throws BuildMacroException
resolves macros in the array of string-list values macros are resolved to the makefile format

Throws:
BuildMacroException
See Also:
isStringListValue

isStringListValue

boolean isStringListValue(java.lang.String value,
                          int contextType,
                          java.lang.Object contextData)
                          throws BuildMacroException
Returns:
true if the specified expression can be treated as StringList 1. The string value is �${}�
Throws:
BuildMacroException

checkIntegrity

void checkIntegrity(int contextType,
                    java.lang.Object contextData)
                    throws BuildMacroException
checks the integrity of the Macros If there are inconsistencies, such as when a macro value refers to a nonexistent macro or when two macros refer to each other, this method will throw the BuildMacroException exception The BuildMacroException will contain the human-readable string describing the inconsistency and the array of the IBuildMacro interfaces that will represent the macros that caused the inconsistency. This information will be used in the UI to notify the user about the macro inconsistencies (see also the �User interface for viewing and editing Build Macros� section of this design)

Throws:
BuildMacroException