TemplateVariable


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 IBM 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
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.jface.text.templates;
12  
13  import org.eclipse.core.runtime.Assert;
14  
15  import org.eclipse.jface.text.TextUtilities;
16  
17  /**
18   * A <code>TemplateVariable</code> represents a set of positions into a
19   * <code>TemplateBuffer</code> with identical content each. <code>TemplateVariableResolver</code>s
20   * can be used to resolve a template variable to a symbol available from the
21   * <code>TemplateContext</code>. A resolved variable may have one or more possible
22   * {@link #getValues() values} which may be presented to the user as choices. If there is no user
23   * interaction the {@link #getDefaultValue() default value} is chosen as textual representation of
24   * the variable.
25   * <p>
26   * Clients may instantiate and extend this class.
27   * </p>
28   * 
29   * @see TemplateVariableResolver
30   * @see TemplateBuffer
31   * @since 3.0
32   */
33  public class TemplateVariable {
34  
35      /** The type name of the variable */
36      private final TemplateVariableType fType;
37      /** The name of the variable. */
38      private final String   fName;
39      /** The initial length in the template pattern. */
40      private final int fInitialLength;
41      /** The offsets of the variable. */
42      private int[] fOffsets;
43      /** Flag indicating if the variable has been resolved unambiguously. */
44      private boolean fIsUnambiguous;
45      /** Flag indicating if the variable has been resolved by a resolver. */
46      private boolean fIsResolved;
47      /**
48       * The proposal strings available for this variable. The first string is
49       * the default value.
50       */
51      private String  [] fValues;
52  
53      /**
54       * Creates a template variable. The type is used as the name of the
55       * variable.
56       *
57       * @param type the type of the variable
58       * @param defaultValue the default value of the variable
59       * @param offsets the array of offsets of the variable
60       */
61      public TemplateVariable(String   type, String   defaultValue, int[] offsets) {
62          this(type, new String  [] { defaultValue }, offsets);
63      }
64  
65      /**
66       * Creates a template variable.
67       *
68       * @param type the type of the variable
69       * @param name the name of the variable
70       * @param defaultValue the default value of the variable
71       * @param offsets the array of offsets of the variable
72       */
73      public TemplateVariable(String   type, String   name, String   defaultValue, int[] offsets) {
74          this(type, name, new String  [] { defaultValue }, offsets);
75      }
76  
77      /**
78       * Creates a template variable.
79       *
80       * @param type the type of the variable
81       * @param name the name of the variable
82       * @param defaultValue the default value of the variable
83       * @param offsets the array of offsets of the variable
84       * @since 3.3
85       */
86      public TemplateVariable(TemplateVariableType type, String   name, String   defaultValue, int[] offsets) {
87          this(type, name, new String  [] { defaultValue }, offsets);
88      }
89      
90      /**
91       * Creates a template variable with multiple possible values. The type is
92       * used as the name of the template.
93       *
94       * @param type the type of the template variable
95       * @param values the values available at this variable, non-empty
96       * @param offsets the array of offsets of the variable
97       */
98      public TemplateVariable(String   type, String  [] values, int[] offsets) {
99          this(type, type, values, offsets);
100     }
101 
102     /**
103      * Creates a template variable with multiple possible values.
104      *
105      * @param type the type of the variable
106      * @param name the name of the variable
107      * @param values the values available at this variable, non-empty
108      * @param offsets the array of offsets of the variable
109      */
110     public TemplateVariable(String   type, String   name, String  [] values, int[] offsets) {
111         this(new TemplateVariableType(type), name, values, offsets);
112     }
113     
114     /**
115      * Creates a template variable with multiple possible values.
116      *
117      * @param type the type of the variable
118      * @param name the name of the variable
119      * @param values the values available at this variable, non-empty
120      * @param offsets the array of offsets of the variable
121      * @since 3.3
122      */
123     TemplateVariable(TemplateVariableType type, String   name, String  [] values, int[] offsets) {
124         Assert.isNotNull(type);
125         Assert.isNotNull(name);
126         fType= type;
127         fName= name;
128         setValues(values);
129         setOffsets(offsets);
130         setUnambiguous(false);
131         setResolved(false);
132         fInitialLength= values[0].length();
133     }
134 
135     /**
136      * Returns the type name of the variable.
137      *
138      * @return the type name of the variable
139      */
140     public String   getType() {
141         return fType.getName();
142     }
143 
144     /**
145      * Returns the type of the variable.
146      *
147      * @return the type of the variable
148      * @since 3.3
149      */
150     public TemplateVariableType getVariableType() {
151         return fType;
152     }
153     
154     /**
155      * Returns the name of the variable.
156      *
157      * @return the name of the variable
158      */
159     public String   getName() {
160         return fName;
161     }
162 
163     /**
164      * Returns the default value of the variable. Typically, this is the first of
165      * the possible values (see {@link #getValues()}.
166      *
167      * @return the default value of the variable
168      */
169     public String   getDefaultValue() {
170         return getValues()[0];
171     }
172 
173     /**
174      * Returns the possible values for this variable. The returned array is owned by this variable
175      * and must not be modified. The array is not empty.
176      * 
177      * @return the possible values for this variable
178      */
179     public String  [] getValues() {
180         return fValues;
181     }
182 
183     /**
184      * Returns the length of the variable's default value.
185      *
186      * @return the length of the variable
187      */
188     public int getLength() {
189         return getDefaultValue().length();
190     }
191     
192     /**
193      * Returns the initial length of the variable. The initial length is the lenght as it occurred
194      * in the template pattern and is used when resolving a template to update the pattern with the
195      * resolved values of the variable.
196      * 
197      * @return the initial length of the variable
198      * @since 3.3
199      */
200     final int getInitialLength() {
201         return fInitialLength;
202     }
203 
204     /**
205      * Sets the offsets of the variable.
206      *
207      * @param offsets the new offsets of the variable
208      */
209     public void setOffsets(int[] offsets) {
210         fOffsets= TextUtilities.copy(offsets);
211     }
212 
213     /**
214      * Returns the offsets of the variable. The returned array is
215      * owned by this variable and must not be modified.
216      *
217      * @return the length of the variable
218      */
219     public int[] getOffsets() {
220         return fOffsets;
221     }
222 
223     /**
224      * Resolves the variable to a single value. This is a shortcut for
225      * <code>setValues(new String[] { value })</code>.
226      * 
227      * @param value the new default value
228      */
229     public final void setValue(String   value) {
230         setValues(new String  [] { value });
231     }
232 
233     /**
234      * Resolves the variable to several possible values for this variable, with the first being the
235      * default value.
236      * 
237      * @param values a non-empty array of values
238      */
239     public void setValues(String  [] values) {
240         Assert.isTrue(values.length > 0);
241         fValues= TextUtilities.copy(values);
242         setResolved(true);
243     }
244 
245     /**
246      * Sets the <em>isUnambiguous</em> flag of the variable.
247      *
248      * @param unambiguous the new unambiguous state of the variable
249      */
250     public void setUnambiguous(boolean unambiguous) {
251         fIsUnambiguous= unambiguous;
252         if (unambiguous)
253             setResolved(true);
254     }
255 
256     /**
257      * Returns <code>true</code> if the variable is unambiguously resolved, <code>false</code> otherwise.
258      *
259      * @return <code>true</code> if the variable is unambiguously resolved, <code>false</code> otherwise
260      */
261     public boolean isUnambiguous() {
262         return fIsUnambiguous;
263     }
264     
265     /**
266      * Sets the <em>resolved</em> flag of the variable.
267      * 
268      * @param resolved the new <em>resolved</em> state
269      * @since 3.3
270      */
271     public void setResolved(boolean resolved) {
272         fIsResolved= resolved;
273     }
274 
275     /**
276      * Returns <code>true</code> if the variable has been resolved, <code>false</code>
277      * otherwise.
278      * 
279      * @return <code>true</code> if the variable has been resolved, <code>false</code> otherwise
280      * @since 3.3
281      */
282     public boolean isResolved() {
283         return fIsResolved;
284     }
285 }
286
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags