1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.jxpath.ri;
19
20 /**
21 * The Compiler APIs are completely agnostic to the actual types of objects produced and consumed by the APIs. Arguments and return values are declared as
22 * java.lang.Object.
23 * <p>
24 * Since objects returned by Compiler methods are passed as arguments to other Compiler methods, the descriptions of these methods use virtual types. There are
25 * four virtual object types: EXPRESSION, QNAME, STEP and NODE_TEST.
26 * <p>
27 * The following example illustrates this notion. This sequence compiles the XPath "foo[round(1 div 2)]/text()": <blockquote>
28 *
29 * <pre>
30 * Object qname1 = compiler.qname(null, "foo")
31 * Object expr1 = compiler.number("1");
32 * Object expr2 = compiler.number("2");
33 * Object expr3 = compiler.div(expr1, expr2);
34 * Object expr4 = compiler.
35 * coreFunction(Compiler.FUNCTION_ROUND, new Object[]{expr3});
36 * Object test1 = compiler.nodeNameTest(qname1);
37 * Object step1 = compiler.
38 * step(Compiler.AXIS_CHILD, test1, new Object[]{expr4});
39 * Object test2 = compiler.nodeTypeTest(Compiler.NODE_TYPE_TEXT);
40 * Object step2 = compiler.nodeTypeTest(Compiler.AXIS_CHILD, test2, null);
41 * Object expr5 = compiler.locationPath(false, new Object[]{step1, step2});
42 * </pre>
43 *
44 * </blockquote>
45 */
46 public interface Compiler {
47
48 /** Constant {@value} */
49 int NODE_TYPE_NODE = 1;
50
51 /** Constant {@value} */
52 int NODE_TYPE_TEXT = 2;
53
54 /** Constant {@value} */
55 int NODE_TYPE_COMMENT = 3;
56
57 /** Constant {@value} */
58 int NODE_TYPE_PI = 4;
59
60 /** Constant {@value} */
61 int AXIS_SELF = 1;
62
63 /** Constant {@value} */
64 int AXIS_CHILD = 2;
65
66 /** Constant {@value} */
67 int AXIS_PARENT = 3;
68
69 /** Constant {@value} */
70 int AXIS_ANCESTOR = 4;
71
72 /** Constant {@value} */
73 int AXIS_ATTRIBUTE = 5;
74
75 /** Constant {@value} */
76 int AXIS_NAMESPACE = 6;
77
78 /** Constant {@value} */
79 int AXIS_PRECEDING = 7;
80
81 /** Constant {@value} */
82 int AXIS_FOLLOWING = 8;
83
84 /** Constant {@value} */
85 int AXIS_DESCENDANT = 9;
86
87 /** Constant {@value} */
88 int AXIS_ANCESTOR_OR_SELF = 10;
89
90 /** Constant {@value} */
91 int AXIS_FOLLOWING_SIBLING = 11;
92
93 /** Constant {@value} */
94 int AXIS_PRECEDING_SIBLING = 12;
95
96 /** Constant {@value} */
97 int AXIS_DESCENDANT_OR_SELF = 13;
98
99 /** Constant {@value} */
100 int FUNCTION_LAST = 1;
101
102 /** Constant {@value} */
103 int FUNCTION_POSITION = 2;
104
105 /** Constant {@value} */
106 int FUNCTION_COUNT = 3;
107
108 /** Constant {@value} */
109 int FUNCTION_ID = 4;
110
111 /** Constant {@value} */
112 int FUNCTION_LOCAL_NAME = 5;
113
114 /** Constant {@value} */
115 int FUNCTION_NAMESPACE_URI = 6;
116
117 /** Constant {@value} */
118 int FUNCTION_NAME = 7;
119
120 /** Constant {@value} */
121 int FUNCTION_STRING = 8;
122
123 /** Constant {@value} */
124 int FUNCTION_CONCAT = 9;
125
126 /** Constant {@value} */
127 int FUNCTION_STARTS_WITH = 10;
128
129 /** Constant {@value} */
130 int FUNCTION_CONTAINS = 11;
131
132 /** Constant {@value} */
133 int FUNCTION_SUBSTRING_BEFORE = 12;
134
135 /** Constant {@value} */
136 int FUNCTION_SUBSTRING_AFTER = 13;
137
138 /** Constant {@value} */
139 int FUNCTION_SUBSTRING = 14;
140
141 /** Constant {@value} */
142 int FUNCTION_STRING_LENGTH = 15;
143
144 /** Constant {@value} */
145 int FUNCTION_NORMALIZE_SPACE = 16;
146
147 /** Constant {@value} */
148 int FUNCTION_TRANSLATE = 17;
149
150 /** Constant {@value} */
151 int FUNCTION_BOOLEAN = 18;
152
153 /** Constant {@value} */
154 int FUNCTION_NOT = 19;
155
156 /** Constant {@value} */
157 int FUNCTION_TRUE = 20;
158
159 /** Constant {@value} */
160 int FUNCTION_FALSE = 21;
161
162 /** Constant {@value} */
163 int FUNCTION_LANG = 22;
164
165 /** Constant {@value} */
166 int FUNCTION_NUMBER = 23;
167
168 /** Constant {@value} */
169 int FUNCTION_SUM = 24;
170
171 /** Constant {@value} */
172 int FUNCTION_FLOOR = 25;
173
174 /** Constant {@value} */
175 int FUNCTION_CEILING = 26;
176
177 /** Constant {@value} */
178 int FUNCTION_ROUND = 27;
179
180 /** Constant {@value} */
181 int FUNCTION_NULL = 28;
182
183 /** Constant {@value} */
184 int FUNCTION_KEY = 29;
185
186 /** Constant {@value} */
187 int FUNCTION_FORMAT_NUMBER = 30;
188
189 /** Constant {@value} */
190 int FUNCTION_ENDS_WITH = 31;
191
192 /**
193 * Produces an EXPRESSION object representing logical conjunction of all arguments
194 *
195 * @param arguments are EXPRESSION objects
196 * @return Object
197 */
198 Object and(Object[] arguments);
199
200 /**
201 * Produces an EXPRESSION object representing <em>left</em> divided by <em>right</em>
202 *
203 * @param left is an EXPRESSION object
204 * @param right is an EXPRESSION object
205 * @return Object
206 */
207 Object divide(Object left, Object right);
208
209 /**
210 * Produces an EXPRESSION object representing the comparison: <em>left</em> equals to <em>right</em>
211 *
212 * @param left is an EXPRESSION object
213 * @param right is an EXPRESSION object
214 * @return Object
215 */
216 Object equal(Object left, Object right);
217
218 /**
219 * Produces an EXPRESSION object representing a filter expression
220 *
221 * @param expression is an EXPRESSION object
222 * @param predicates are EXPRESSION objects
223 * @param steps are STEP objects
224 * @return Object
225 */
226 Object expressionPath(Object expression, Object[] predicates, Object[] steps);
227
228 /**
229 * Produces an EXPRESSION object representing the computation of a core function with the supplied arguments.
230 *
231 * @param code is one of FUNCTION_... constants
232 * @param args are EXPRESSION objects
233 * @return Object
234 */
235 Object function(int code, Object[] args);
236
237 /**
238 * Produces an EXPRESSION object representing the computation of a library function with the supplied arguments.
239 *
240 * @param name is a QNAME object (function name)
241 * @param args are EXPRESSION objects
242 * @return Object
243 */
244 Object function(Object name, Object[] args);
245
246 /**
247 * Produces an EXPRESSION object representing the comparison: <em>left</em> greater than <em>right</em>
248 *
249 * @param left is an EXPRESSION object
250 * @param right is an EXPRESSION object
251 * @return Object
252 */
253 Object greaterThan(Object left, Object right);
254
255 /**
256 * Produces an EXPRESSION object representing the comparison: <em>left</em> greater than or equal to <em>right</em>
257 *
258 * @param left is an EXPRESSION object
259 * @param right is an EXPRESSION object
260 * @return Object
261 */
262 Object greaterThanOrEqual(Object left, Object right);
263
264 /**
265 * Produces an EXPRESSION object representing the comparison: <em>left</em> less than <em>right</em>
266 *
267 * @param left is an EXPRESSION object
268 * @param right is an EXPRESSION object
269 * @return Object
270 */
271 Object lessThan(Object left, Object right);
272
273 /**
274 * Produces an EXPRESSION object representing the comparison: <em>left</em> less than or equal to <em>right</em>
275 *
276 * @param left is an EXPRESSION object
277 * @param right is an EXPRESSION object
278 * @return Object
279 */
280 Object lessThanOrEqual(Object left, Object right);
281
282 /**
283 * Produces an EXPRESSION object that represents a string constant.
284 *
285 * @param value String literal
286 * @return Object
287 */
288 Object literal(String value);
289
290 /**
291 * Produces an EXPRESSION object representing a location path
292 *
293 * @param absolute indicates whether the path is absolute
294 * @param steps are STEP objects
295 * @return Object
296 */
297 Object locationPath(boolean absolute, Object[] steps);
298
299 /**
300 * Produces an EXPRESSION object representing unary negation of the argument
301 *
302 * @param argument is an EXPRESSION object
303 * @return Object
304 */
305 Object minus(Object argument);
306
307 /**
308 * Produces an EXPRESSION object representing <em>left</em> minus <em>right</em>
309 *
310 * @param left is an EXPRESSION object
311 * @param right is an EXPRESSION object
312 * @return Object
313 */
314 Object minus(Object left, Object right);
315
316 /**
317 * Produces an EXPRESSION object representing <em>left</em> modulo <em>right</em>
318 *
319 * @param left is an EXPRESSION object
320 * @param right is an EXPRESSION object
321 * @return Object
322 */
323 Object mod(Object left, Object right);
324
325 /**
326 * Produces an EXPRESSION object representing <em>left</em> multiplied by <em>right</em>
327 *
328 * @param left is an EXPRESSION object
329 * @param right is an EXPRESSION object
330 * @return Object
331 */
332 Object multiply(Object left, Object right);
333
334 /**
335 * Produces a NODE_TEST object that represents a node name test.
336 *
337 * @param qname is a QNAME object
338 * @return Object
339 */
340 Object nodeNameTest(Object qname);
341
342 /**
343 * Produces a NODE_TEST object that represents a node type test.
344 *
345 * @param nodeType is a NODE_TEST object
346 * @return Object
347 */
348 Object nodeTypeTest(int nodeType);
349
350 /**
351 * Produces an EXPRESSION object representing the comparison: <em>left</em> is not equal to <em>right</em>
352 *
353 * @param left is an EXPRESSION object
354 * @param right is an EXPRESSION object
355 * @return Object
356 */
357 Object notEqual(Object left, Object right);
358
359 /**
360 * Produces an EXPRESSION object that represents a numeric constant.
361 *
362 * @param value numeric String
363 * @return Object
364 */
365 Object number(String value);
366
367 /**
368 * Produces an EXPRESSION object representing logical disjunction of all arguments
369 *
370 * @param arguments are EXPRESSION objects
371 * @return Object
372 */
373 Object or(Object[] arguments);
374
375 /**
376 * Produces a NODE_TEST object that represents a processing instruction test.
377 *
378 * @param instruction is a NODE_TEST object
379 * @return Object
380 */
381 Object processingInstructionTest(String instruction);
382
383 /**
384 * Produces an QNAME that represents a name with an optional prefix.
385 *
386 * @param prefix String prefix
387 * @param name String name
388 * @return Object
389 */
390 Object qname(String prefix, String name);
391
392 /**
393 * Produces a STEP object that represents a node test.
394 *
395 * @param axis is one of the AXIS_... constants
396 * @param nodeTest is a NODE_TEST object
397 * @param predicates are EXPRESSION objects
398 * @return Object
399 */
400 Object step(int axis, Object nodeTest, Object[] predicates);
401
402 /**
403 * Produces an EXPRESSION object representing the sum of all argumens
404 *
405 * @param arguments are EXPRESSION objects
406 * @return Object
407 */
408 Object sum(Object[] arguments);
409
410 /**
411 * Produces an EXPRESSION object representing union of all node sets
412 *
413 * @param arguments are EXPRESSION objects
414 * @return Object
415 */
416 Object union(Object[] arguments);
417
418 /**
419 * Produces an EXPRESSION object representing variable reference
420 *
421 * @param qname is a QNAME object
422 * @return Object
423 */
424 Object variableReference(Object qname);
425 }