Debian Codegraph @

closure-library/closure/goog/datasource/expr.js

raw
1 // Copyright 2006 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview
17 * Expression evaluation utilities. Expression format is very similar to XPath.
18 *
19 * Expression details:
20 * - Of format A/B/C, which will evaluate getChildNode('A').getChildNode('B').
21 * getChildNodes('C')|getChildNodeValue('C')|getChildNode('C') depending on
22 * call
23 * - If expression ends with '/name()', will get the name() of the node
24 * referenced by the preceding path.
25 * - If expression ends with '/count()', will get the count() of the nodes that
26 * match the expression referenced by the preceding path.
27 * - If expression ends with '?', the value is OK to evaluate to null. This is
28 * not enforced by the expression evaluation functions, instead it is
29 * provided as a flag for client code which may ignore depending on usage
30 * - If expression has [INDEX], will use getChildNodes().getByIndex(INDEX)
31 *
32 */
33
34
35 goog.provide('goog.ds.Expr');
36
37 goog.require('goog.ds.BasicNodeList');
38 goog.require('goog.ds.EmptyNodeList');
39 goog.require('goog.string');
40
41
42
43 /**
44 * Create a new expression. An expression uses a string expression language, and
45 * from this string and a passed in DataNode can evaluate to a value, DataNode,
46 * or a DataNodeList.
47 *
48 * @param {string=} opt_expr The string expression.
49 * @constructor
50 * @final
51 */
52 goog.ds.Expr = function(opt_expr) {
53 if (opt_expr) {
54 this.setSource_(opt_expr);
55 }
56 };
57
58
59 /**
60 * Set the source expression text & parse
61 *
62 * @param {string} expr The string expression source.
63 * @param {Array=} opt_parts Array of the parts of an expression.
64 * @param {goog.ds.Expr=} opt_childExpr Optional child of this expression,
65 * passed in as a hint for processing.
66 * @param {goog.ds.Expr=} opt_prevExpr Optional preceding expression
67 * (i.e. $A/B/C is previous expression to B/C) passed in as a hint for
68 * processing.
69 * @private
70 */
71 goog.ds.Expr.prototype.setSource_ = function(
72 expr, opt_parts, opt_childExpr, opt_prevExpr) {
73 this.src_ = expr;
74
75 if (!opt_childExpr && !opt_prevExpr) {
76 // Check whether it can be empty
77 if (goog.string.endsWith(expr, goog.ds.Expr.String_.CAN_BE_EMPTY)) {
78 this.canBeEmpty_ = true;
79 expr = expr.substring(0, expr.length - 1);
80 }
81
82 // Check whether this is an node function
83 if (goog.string.endsWith(expr, '()')) {
84 if (goog.string.endsWith(expr, goog.ds.Expr.String_.NAME_EXPR) ||
85 goog.string.endsWith(expr, goog.ds.Expr.String_.COUNT_EXPR) ||
86 goog.string.endsWith(expr, goog.ds.Expr.String_.POSITION_EXPR)) {
87 var lastPos = expr.lastIndexOf(goog.ds.Expr.String_.SEPARATOR);
88 if (lastPos != -1) {
89 this.exprFn_ = expr.substring(lastPos + 1);
90 expr = expr.substring(0, lastPos);
91 } else {
92 this.exprFn_ = expr;
93 expr = goog.ds.Expr.String_.CURRENT_NODE_EXPR;
94 }
95 if (this.exprFn_ == goog.ds.Expr.String_.COUNT_EXPR) {
96 this.isCount_ = true;
97 }
98 }
99 }
100 }
101
102 // Split into component parts
103 this.parts_ = opt_parts || expr.split('/');
104 this.size_ = this.parts_.length;
105 this.last_ = this.parts_[this.size_ - 1];
106 this.root_ = this.parts_[0];
107
108 if (this.size_ == 1) {
109 this.rootExpr_ = this;
110 this.isAbsolute_ = goog.string.startsWith(expr, '$');
111 } else {
112 this.rootExpr_ = goog.ds.Expr.createInternal_(this.root_, null, this, null);
113 this.isAbsolute_ = this.rootExpr_.isAbsolute_;
114 this.root_ = this.rootExpr_.root_;
115 }
116
117 if (this.size_ == 1 && !this.isAbsolute_) {
118 // Check whether expression maps to current node, for convenience
119 this.isCurrent_ =
120 (expr == goog.ds.Expr.String_.CURRENT_NODE_EXPR ||
121 expr == goog.ds.Expr.String_.EMPTY_EXPR);
122
123 // Whether this expression is just an attribute (i.e. '@foo')
124 this.isJustAttribute_ =
125 goog.string.startsWith(expr, goog.ds.Expr.String_.ATTRIBUTE_START);
126
127 // Check whether this is a common node expression
128 this.isAllChildNodes_ = expr == goog.ds.Expr.String_.ALL_CHILD_NODES_EXPR;
129 this.isAllAttributes_ = expr == goog.ds.Expr.String_.ALL_ATTRIBUTES_EXPR;
130 this.isAllElements_ = expr == goog.ds.Expr.String_.ALL_ELEMENTS_EXPR;
131 }
132 };
133
134
135 /**
136 * Get the source data path for the expression
137 * @return {string} The path.
138 */
139 goog.ds.Expr.prototype.getSource = function() {
140 return this.src_;
141 };
142
143
144 /**
145 * Gets the last part of the expression.
146 * @return {?string} Last part of the expression.
147 */
148 goog.ds.Expr.prototype.getLast = function() {
149 return this.last_;
150 };
151
152
153 /**
154 * Gets the parent expression of this expression, or null if this is top level
155 * @return {goog.ds.Expr} The parent.
156 */
157 goog.ds.Expr.prototype.getParent = function() {
158 if (!this.parentExprSet_) {
159 if (this.size_ > 1) {
160 this.parentExpr_ = goog.ds.Expr.createInternal_(
161 null, this.parts_.slice(0, this.parts_.length - 1), this, null);
162 }
163 this.parentExprSet_ = true;
164 }
165 return this.parentExpr_;
166 };
167
168
169 /**
170 * Gets the parent expression of this expression, or null if this is top level
171 * @return {goog.ds.Expr} The parent.
172 */
173 goog.ds.Expr.prototype.getNext = function() {
174 if (!this.nextExprSet_) {
175 if (this.size_ > 1) {
176 this.nextExpr_ =
177 goog.ds.Expr.createInternal_(null, this.parts_.slice(1), null, this);
178 }
179 this.nextExprSet_ = true;
180 }
181 return this.nextExpr_;
182 };
183
184
185 /**
186 * Evaluate an expression on a data node, and return a value
187 * Recursively walks through child nodes to evaluate
188 * TODO(user) Support other expression functions
189 *
190 * @param {goog.ds.DataNode=} opt_ds Optional datasource to evaluate against.
191 * If not provided, evaluates against DataManager global root.
192 * @return {*} Value of the node, or null if doesn't exist.
193 * @suppress {missingRequire} Cannot depend on goog.ds.DataManager because
194 * it creates a circular dependency.
195 */
196 goog.ds.Expr.prototype.getValue = function(opt_ds) {
197 if (opt_ds == null) {
198 opt_ds = goog.ds.DataManager.getInstance();
199 } else if (this.isAbsolute_) {
200 opt_ds = opt_ds.getDataRoot ? opt_ds.getDataRoot() :
201 goog.ds.DataManager.getInstance();
202 }
203
204 if (this.isCount_) {
205 var nodes = this.getNodes(opt_ds);
206 return nodes.getCount();
207 }
208
209 if (this.size_ == 1) {
210 return opt_ds.getChildNodeValue(this.root_);
211 } else if (this.size_ == 0) {
212 return opt_ds.get();
213 }
214
215 var nextDs = opt_ds.getChildNode(this.root_);
216
217 if (nextDs == null) {
218 return null;
219 } else {
220 return this.getNext().getValue(nextDs);
221 }
222 };
223
224
225 /**
226 * Evaluate an expression on a data node, and return matching nodes
227 * Recursively walks through child nodes to evaluate
228 *
229 * @param {goog.ds.DataNode=} opt_ds Optional datasource to evaluate against.
230 * If not provided, evaluates against data root.
231 * @param {boolean=} opt_canCreate If true, will try to create new nodes.
232 * @return {goog.ds.DataNodeList} Matching nodes.
233 */
234 goog.ds.Expr.prototype.getNodes = function(opt_ds, opt_canCreate) {
235 return /** @type {goog.ds.DataNodeList} */ (
236 this.getNodes_(opt_ds, false, opt_canCreate));
237 };
238
239
240 /**
241 * Evaluate an expression on a data node, and return the first matching node
242 * Recursively walks through child nodes to evaluate
243 *
244 * @param {goog.ds.DataNode=} opt_ds Optional datasource to evaluate against.
245 * If not provided, evaluates against DataManager global root.
246 * @param {boolean=} opt_canCreate If true, will try to create new nodes.
247 * @return {goog.ds.DataNode} Matching nodes, or null if doesn't exist.
248 */
249 goog.ds.Expr.prototype.getNode = function(opt_ds, opt_canCreate) {
250 return /** @type {goog.ds.DataNode} */ (
251 this.getNodes_(opt_ds, true, opt_canCreate));
252 };
253
254
255 /**
256 * Evaluate an expression on a data node, and return the first matching node
257 * Recursively walks through child nodes to evaluate
258 *
259 * @param {goog.ds.DataNode=} opt_ds Optional datasource to evaluate against.
260 * If not provided, evaluates against DataManager global root.
261 * @param {boolean=} opt_selectOne Whether to return single matching DataNode
262 * or matching nodes in DataNodeList.
263 * @param {boolean=} opt_canCreate If true, will try to create new nodes.
264 * @return {goog.ds.DataNode|goog.ds.DataNodeList} Matching node or nodes,
265 * depending on value of opt_selectOne.
266 * @private
267 * @suppress {missingRequire} Cannot depend on goog.ds.DataManager because
268 * it creates a circular dependency.
269 */
270 goog.ds.Expr.prototype.getNodes_ = function(
271 opt_ds, opt_selectOne, opt_canCreate) {
272 if (opt_ds == null) {
273 opt_ds = goog.ds.DataManager.getInstance();
274 } else if (this.isAbsolute_) {
275 opt_ds = opt_ds.getDataRoot ? opt_ds.getDataRoot() :
276 goog.ds.DataManager.getInstance();
277 }
278
279 if (this.size_ == 0 && opt_selectOne) {
280 return opt_ds;
281 } else if (this.size_ == 0 && !opt_selectOne) {
282 return new goog.ds.BasicNodeList([opt_ds]);
283 } else if (this.size_ == 1) {
284 if (opt_selectOne) {
285 return opt_ds.getChildNode(this.root_, opt_canCreate);
286 } else {
287 var possibleListChild = opt_ds.getChildNode(this.root_);
288 if (possibleListChild && possibleListChild.isList()) {
289 return possibleListChild.getChildNodes();
290 } else {
291 return opt_ds.getChildNodes(this.root_);
292 }
293 }
294 } else {
295 var nextDs = opt_ds.getChildNode(this.root_, opt_canCreate);
296 if (nextDs == null && opt_selectOne) {
297 return null;
298 } else if (nextDs == null && !opt_selectOne) {
299 return new goog.ds.EmptyNodeList();
300 }
301 return this.getNext().getNodes_(nextDs, opt_selectOne, opt_canCreate);
302 }
303 };
304
305
306 /**
307 * Whether the expression can be null.
308 *
309 * @type {boolean}
310 * @private
311 */
312 goog.ds.Expr.prototype.canBeEmpty_ = false;
313
314
315 /**
316 * The parsed paths in the expression
317 *
318 * @type {Array<string>}
319 * @private
320 */
321 goog.ds.Expr.prototype.parts_ = [];
322
323
324 /**
325 * Number of paths in the expression
326 *
327 * @type {?number}
328 * @private
329 */
330 goog.ds.Expr.prototype.size_ = null;
331
332
333 /**
334 * The root node path in the expression
335 *
336 * @type {string}
337 * @private
338 */
339 goog.ds.Expr.prototype.root_;
340
341
342 /**
343 * The last path in the expression
344 *
345 * @type {?string}
346 * @private
347 */
348 goog.ds.Expr.prototype.last_ = null;
349
350
351 /**
352 * Whether the expression evaluates to current node
353 *
354 * @type {boolean}
355 * @private
356 */
357 goog.ds.Expr.prototype.isCurrent_ = false;
358
359
360 /**
361 * Whether the expression is just an attribute
362 *
363 * @type {boolean}
364 * @private
365 */
366 goog.ds.Expr.prototype.isJustAttribute_ = false;
367
368
369 /**
370 * Does this expression select all DOM-style child nodes (element and text)
371 *
372 * @type {boolean}
373 * @private
374 */
375 goog.ds.Expr.prototype.isAllChildNodes_ = false;
376
377
378 /**
379 * Does this expression select all DOM-style attribute nodes (starts with '@')
380 *
381 * @type {boolean}
382 * @private
383 */
384 goog.ds.Expr.prototype.isAllAttributes_ = false;
385
386
387 /**
388 * Does this expression select all DOM-style element child nodes
389 *
390 * @type {boolean}
391 * @private
392 */
393 goog.ds.Expr.prototype.isAllElements_ = false;
394
395
396 /**
397 * The function used by this expression
398 *
399 * @type {?string}
400 * @private
401 */
402 goog.ds.Expr.prototype.exprFn_ = null;
403
404
405 /**
406 * Cached value for the parent expression.
407 * @type {goog.ds.Expr?}
408 * @private
409 */
410 goog.ds.Expr.prototype.parentExpr_ = null;
411
412
413 /**
414 * Cached value for the next expression.
415 * @type {goog.ds.Expr?}
416 * @private
417 */
418 goog.ds.Expr.prototype.nextExpr_ = null;
419
420
421 /**
422 * Create an expression from a string, can use cached values
423 *
424 * @param {string} expr The expression string.
425 * @return {goog.ds.Expr} The expression object.
426 */
427 goog.ds.Expr.create = function(expr) {
428 var result = goog.ds.Expr.cache_[expr];
429
430 if (result == null) {
431 result = new goog.ds.Expr(expr);
432 goog.ds.Expr.cache_[expr] = result;
433 }
434 return result;
435 };
436
437
438 /**
439 * Create an expression from a string, can use cached values
440 * Uses hints from related expressions to help in creation
441 *
442 * @param {?string=} opt_expr The string expression source.
443 * @param {Array=} opt_parts Array of the parts of an expression.
444 * @param {goog.ds.Expr=} opt_childExpr Optional child of this expression,
445 * passed in as a hint for processing.
446 * @param {goog.ds.Expr=} opt_prevExpr Optional preceding expression
447 * (i.e. $A/B/C is previous expression to B/C) passed in as a hint for
448 * processing.
449 * @return {goog.ds.Expr} The expression object.
450 * @private
451 */
452 goog.ds.Expr.createInternal_ = function(
453 opt_expr, opt_parts, opt_childExpr, opt_prevExpr) {
454 var expr = opt_expr || opt_parts.join('/');
455 var result = goog.ds.Expr.cache_[expr];
456
457 if (result == null) {
458 result = new goog.ds.Expr();
459 result.setSource_(expr, opt_parts, opt_childExpr, opt_prevExpr);
460 goog.ds.Expr.cache_[expr] = result;
461 }
462 return result;
463 };
464
465
466 /**
467 * Cache of pre-parsed expressions
468 * @private
469 */
470 goog.ds.Expr.cache_ = {};
471
472
473 /**
474 * Commonly used strings in expressions.
475 * @enum {string}
476 * @private
477 */
478 goog.ds.Expr.String_ = {
479 SEPARATOR: '/',
480 CURRENT_NODE_EXPR: '.',
481 EMPTY_EXPR: '',
482 ATTRIBUTE_START: '@',
483 ALL_CHILD_NODES_EXPR: '*|text()',
484 ALL_ATTRIBUTES_EXPR: '@*',
485 ALL_ELEMENTS_EXPR: '*',
486 NAME_EXPR: 'name()',
487 COUNT_EXPR: 'count()',
488 POSITION_EXPR: 'position()',
489 INDEX_START: '[',
490 INDEX_END: ']',
491 CAN_BE_EMPTY: '?'
492 };
493
494
495 /**
496 * Standard expressions
497 */
498
499
500 /**
501 * The current node
502 */
503 goog.ds.Expr.CURRENT =
504 goog.ds.Expr.create(goog.ds.Expr.String_.CURRENT_NODE_EXPR);
505
506
507 /**
508 * For DOM interop - all DOM child nodes (text + element).
509 * Text nodes have dataName #text
510 */
511 goog.ds.Expr.ALL_CHILD_NODES =
512 goog.ds.Expr.create(goog.ds.Expr.String_.ALL_CHILD_NODES_EXPR);
513
514
515 /**
516 * For DOM interop - all DOM element child nodes
517 */
518 goog.ds.Expr.ALL_ELEMENTS =
519 goog.ds.Expr.create(goog.ds.Expr.String_.ALL_ELEMENTS_EXPR);
520
521
522 /**
523 * For DOM interop - all DOM attribute nodes
524 * Attribute nodes have dataName starting with "@"
525 */
526 goog.ds.Expr.ALL_ATTRIBUTES =
527 goog.ds.Expr.create(goog.ds.Expr.String_.ALL_ATTRIBUTES_EXPR);
528
529
530 /**
531 * Get the dataName of a node
532 */
533 goog.ds.Expr.NAME = goog.ds.Expr.create(goog.ds.Expr.String_.NAME_EXPR);
534
535
536 /**
537 * Get the count of nodes matching an expression
538 */
539 goog.ds.Expr.COUNT = goog.ds.Expr.create(goog.ds.Expr.String_.COUNT_EXPR);
540
541
542 /**
543 * Get the position of the "current" node in the current node list
544 * This will only apply for datasources that support the concept of a current
545 * node (none exist yet). This is similar to XPath position() and concept of
546 * current node
547 */
548 goog.ds.Expr.POSITION = goog.ds.Expr.create(goog.ds.Expr.String_.POSITION_EXPR);