1
/*******************************************************************************
2
* Copyright (c) 2005, 2007 Intel Corporation and others.
3
* All rights reserved. This program and the accompanying materials
4
* are made available under the terms of the Eclipse Public License v1.0
5
* which accompanies this distribution, and is available at
6
* http://www.eclipse.org/legal/epl-v10.html
9
* Intel Corporation - Initial API and implementation
10
*******************************************************************************/
11
package org.eclipse.cdt.managedbuilder.macros;
13
import org.eclipse.cdt.core.cdtvariables.ICdtVariable;
19
public interface IBuildMacroProvider{
20
public final static int CONTEXT_FILE = 1;
21
public final static int CONTEXT_OPTION = 2;
22
public final static int CONTEXT_CONFIGURATION = 3;
23
public final static int CONTEXT_PROJECT = 4;
24
public final static int CONTEXT_WORKSPACE = 5;
25
public final static int CONTEXT_INSTALLATIONS = 6;
26
public final static int CONTEXT_ECLIPSEENV = 7;
27
public final static int CONTEXT_TOOL = 8;
31
* Returns reference to the IBuildMacro interface representing Macro of the
32
* specified name or null if there is there is no such macro
33
* @param macroName macro name
34
* @param contextType represents the context type. Should be set to one of the the
35
* IBuildMacroProvider. CONTEXT_xxx constants
36
* @param contextData represents the additional data needed by the Build Macro Provider
37
* and Macro Suppliers in order to obtain the macro value. The type of the context data
38
* differs depending on the context type and can be one of the following:
39
* 1. IFileContextData interface � used to represent currently selected file context
40
* the IFileContextData interface is defined as follows:
41
* pulic interface IFileContextData{
43
* IOption getOption();
45
* NOTE: the IFileContextData is passed that represents the current file and the option
46
* for that file because Macro Value Provider needs to know what option should be used
47
* as a context in case macro is not found for �current file� context
48
* 2. IOptionContextData interface used to represent the currently selected option context
49
* 3. IConfiguration � used to represent the currently selected configuration context
50
* 4. IProject � used to represent current project context
51
* 5. IWorkspace � used to represent current workspace context
52
* 6. null � to represent the CDT and Eclipse installation context
53
* 7. null � to represent process environment context
54
* @param includeParentContext specifies whether lower-precedence context macros should
57
public IBuildMacro getMacro(String macroName,
60
boolean includeParentContexts);
64
* @return the array of the IBuildMacro representing all available macros
66
public IBuildMacro[] getMacros(int contextType,
68
boolean includeParentContexts);
71
public ICdtVariable getVariable(String macroName,
74
boolean includeParentContexts);
78
* @return the array of the IBuildMacro representing all available macros
80
public ICdtVariable[] getVariables(int contextType,
82
boolean includeParentContexts);
85
* This method is defined to be used primarily by the UI classes and should not be used by the
87
* @return the array of the provider-internal suppliers for the given context
89
public IBuildMacroSupplier[] getSuppliers(int contextType,
95
* converts StringList value into String of the following format:
96
* "<value_1>< listDelimiter ><value_2>< listDelimiter > ... <value_n>"
98
public String convertStringListToString (String value[], String listDelimiter);
102
* resolves all macros in the string.
103
* @param value the value to be resolved
104
* @param nonexistentMacrosValue specifies the value that inexistent macro references will be
105
* expanded to. If null the BuildMacroException is thrown in case the string to be resolved
106
* references inexistent macros
107
* @param listDelimiter if not null, StringList macros are expanded as
108
* �<value_1>< listDelimiter ><value_2>< listDelimiter > ... <value_n>�
109
* otherwise the BuildMacroException is thrown in case the string to be resolved references
111
* @param contextType context from which the macro search should be started
112
* @param contextData context data
114
public String resolveValue(String value,
115
String nonexistentMacrosValue,
116
String listDelimiter,
118
Object contextData) throws BuildMacroException;
122
* if the string contains a value that can be treated as a StringList resolves it to arrays of strings
123
* otherwise throws the BuildMacroException exception
124
* @see isStringListValue
126
public String[] resolveStringListValue(String value,
127
String nonexistentMacrosValue,
128
String listDelimiter,
130
Object contextData) throws BuildMacroException;
134
* resolves macros in the array of string-list values
136
* @see isStringListValue
138
public String[] resolveStringListValues(String value[],
139
String nonexistentMacrosValue,
140
String listDelimiter,
142
Object contextData) throws BuildMacroException;
146
* resolves all macros in the string to the makefile format. That is:
147
* 1. In case when a user has specified to resolve the environment build macros all macros
148
* get resolved in the string
149
* 2. In case when the a user has specified not to resolve the environment build macros all macros
150
* get resolved except the build environment macros (macros whose name conflicts with one
151
* of reserved macro names, or string-list macros always get resolved in the buildfile).
152
* Macro references that are kept unresolved are converted to the makefile format
153
* @param value the value to be resolved
154
* @param nonexistentMacrosValue specifies the value that inexistent macro references will be
155
* expanded to. If null the BuildMacroException is thrown in case the string to be resolved
156
* references inexistent macros
157
* @param listDelimiter if not null, StringList macros are expanded as
158
* �<value_1>< listDelimiter ><value_2>< listDelimiter > ... <value_n>�
159
* otherwise the BuildMacroException is thrown in case the string to be resolved references
161
* @param contextType context from which the macro search should be started
162
* @param contextData context data
164
public String resolveValueToMakefileFormat(String value,
165
String nonexistentMacrosValue,
166
String listDelimiter,
168
Object contextData) throws BuildMacroException;
172
* if the string contains a value that can be treated as a StringList resolves it to arrays of strings
173
* otherwise throws the BuildMacroException exception
174
* each string of the returned array will contain all macro references resolved in case of
175
* a user has specified to resolve the build macros, and will contain the string with the
176
* environment macro references unresolved and converted to the buildfile format otherwise
177
* @see isStringListValue
179
public String[] resolveStringListValueToMakefileFormat(String value,
180
String nonexistentMacrosValue,
181
String listDelimiter,
183
Object contextData) throws BuildMacroException;
186
* resolves macros in the array of string-list values
187
* macros are resolved to the makefile format
189
* @see isStringListValue
191
public String[] resolveStringListValuesToMakefileFormat(String value[],
192
String nonexistentMacrosValue,
193
String listDelimiter,
195
Object contextData) throws BuildMacroException;
200
* @return true if the specified expression can be treated as StringList
201
* 1. The string value is �${<some_StringList_Macro_name>}�
203
public boolean isStringListValue(String value, int contextType, Object contextData)
204
throws BuildMacroException;
208
* checks the integrity of the Macros
209
* If there are inconsistencies, such as when a macro value refers to a nonexistent macro
210
* or when two macros refer to each other, this method will throw the BuildMacroException exception
211
* The BuildMacroException will contain the human-readable string describing
212
* the inconsistency and the array of the IBuildMacro interfaces that will represent the macros that
213
* caused the inconsistency. This information will be used in the UI to notify the user about
214
* the macro inconsistencies (see also the �User interface for viewing and editing Build Macros�
215
* section of this design)
217
public void checkIntegrity(int contextType,
218
Object contextData) throws BuildMacroException;