Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Updated version

Fixes and documentation update
  • Loading branch information...
commit 3f0c428694a677c12bd154dcc4e8fc27ae139668 1 parent 0986717
Simon Tsvilik authored
Showing with 162 additions and 95 deletions.
  1. +83 −30 README.md
  2. +78 −64 lib/node-jpath.js
  3. +1 −1  package.json
113 README.md
View
@@ -3,21 +3,21 @@ node-jPath
Utility library to help you traverse and filter out data from complex JSON and or Arrays of objects.
The strength of this library lies in ability to use XPath-like expressions to retrieve data you need.
-How is it different from XPath?
----
+#### How is it different from XPath?
+
Because we're dealing with javascript, I felt that syntax should inherit some of that syntactical sugar that we're all used to when coding JavaScript
and that is why the pattern syntax uses dots(.) instead of slashes. One thing that jPath lacks in comparisson with XPath is ability to look for conditions "anywhere" within a structure (i.e. //foo), this operation is just too expensive.
-How does it work?
----
+#### How does it work?
+
jPath is a recursive scanner that processes each token of your pattern at a time passing the results of the findings back to itself. As it runs conditions to match the values, it tries to match value types on the left and right sides of the equasion (apples to apples, oranges to oranges). Results of the traversal are merged into a single Array.
-Install
----
+#### Install
+
npm install node-jpath
-Examples
----
+#### Examples
+
var jsonData = {
people: [
{name: "John", age:26, gender:"male"},
@@ -49,28 +49,52 @@ Output:
var match = jpath.filter(jsonData, "people[name != undefined]");
-Supported Operators
----
-* "==" or "=" - compares data member for equality
-* "!=" - compares data member inequality
-* "<" - less than
-* ">" - greater than
-* "<=" - less or equal
-* ">=" - greater or equal
-* "~=" - equal ignoring case
-* "^=" - starts with
-* "$=" - ends with
-* "*=" - contains a string anywhere inside
-* "!*" - does NOT contain a string anywhere in the value
-* "?" - allows you to pass a custom evaluation function
-
-You can also reverse condition for any of the operations by wrapping them in "!(...)".
+#### Does it support conditions?
-#### Example:
- var match = jpath.filter(jsonData, "people[!(name ^= A)]"); //This will find all names that do NOT start with "A"
+Just like XPATH, it does support conditional filtering, where you basically specify what nodes you want to retrieve
+based on certain condition. Conditional queries work by comparing data members to value you provide inside your
+expression (it does not do comparing between data members). So for example if you have an array of objects and you want
+to get only those objects where member foo = 1, you would write "obj[foo == 1]", more examples later. It supports a
+wide range of evaluations.
+
+- "==" | "=" - compares data member for equality
+- "!=" - compares data member inequality
+- "<" - less than
+- ">" - greater than
+- "<=" - less or equal
+- ">=" - greater or equal
+- "~=" - equal ignoring case
+- "^=" - starts with
+- "$=" - ends with
+- "*=" - contains a string anywhere inside (case insensitive)
+- "?" - allows you to pass a custom evaluation function (runs in the scope of evaluated object so you can compare against other object members).
+
+During the comparing stage, all values are type matched (coerced) to the types of values you're comparing against.
+What this means is that you always compare numbers against numbers and not strings, and same goes for every other data
+type.
+
+If your value contains a space, you can enclose your value in single or double quotes. (i.e. [foo == 'hello world']) Normally you
+don't have to do that. If your value contains quotes, you can escape them using double slashes (i.e [foo == 'Bob\\\'s']).
+
+#### What else can it do?
+
+One thing to note is that there is a special "*" selector that references an object itself, so you may use it lets say
+against an array of objects (i.e. *[ foo == bah] - will return rows where member foo has value bah). You can also have
+"deep" value comparing (i.e. obj[ foo.bah == "wow"] ). Now that you can do deep value comparing, you can also check for
+native properties such as "length" (i.e. obj( [ name.length > 3 ]) ). You can also reverse condition for any of the operations by wrapping them in "!(...)".
+
+#### Using reserved words to compare
+
+JPath supports the use of 'null' and 'undefined' in conditions.
+So if you're traversing an array of objects where your object may NOT contain a member you can always write *[foo == undefined].
+
+#### What is not here
+
+- JPath does not support "select-all" syntax of XPATH that allowed you to find something anywhere in the XML document. This is too expensive in JavaScript.
+- JPath does not natively supports conditions that compare one data memeber against another, but this can be achieved using "a ? b" and the use of "this" in the custom comparator.
+
+#### Working with Arrays
-Working with Arrays
----
Working with Arrays requires a special character to reference Array itself in the expression, for this we'll use "\*".
#### Example:
var people = [
@@ -104,6 +128,35 @@ jPath exposes two methods: filter() and select(). select method returns an insta
### Methods
-* select( json, expression ) - performs a traversal and returns you an instance of JPath object
-* filter( json, expression ) - performs a traversal and returns a value
+* select( json, expression [,cust_compare_fn] ) - performs a traversal and returns you an instance of JPath object
+* filter( json, expression [,cust_compare_fn] ) - performs a traversal and returns a value
+
+#### More Examples
+
+1. Using Custom compare logic
+
+ jPath.filter( JSON, "foo[bar ? test]", function(left, right) {
+ //left - is the value of the data member bar inside foo
+ //right - would be equal to "test"
+ return left + "blah" == right; //Cusom validation
+ });
+
+2. Joining multiple filtering results
+
+ jPath.select( JSON, "foo[bar == 1]").and( "foo2[bar == 2]").val(); //This example adds to the selection a different pattern evaluation
+
+ //Example above could also be written like so:
+
+ jPath.select( JSON, "foo[bar == 1 || bar == 2]").val();
+
+3. If we want to combine results from different JSON objects, than we would do something like so:
+
+ jPath.select( JSON, "foo[bar == 1]").from(JSON2).and( "foo2[bar == 2]").val(); //from() sets a different source of data
+
+4. Accessing array elements by index
+
+ jPath.select({myArray:[1,2,3,4,5]}, "myArray(0)");
+
+5. Using parenteces to group logic
+ jPath.filter(obj, "*[(a==b || a == c) && c == d]");
142 lib/node-jpath.js
View
@@ -1,32 +1,44 @@
// node-jpath.js - is a library that allows filtering of JSON data based on pattern-like expressions
(function(Array, undef) {
var
- TRUE = !0,
- FALSE = !1,
- UNDEF = "undefined",
- STRING = "string",
- PERIOD = ".",
+ TRUE = !0,
+ FALSE = !1,
+ STRING = "string",
+ FUNCTION = "function",
+ PERIOD = ".",
+ EMPTY = '',
+ NULL = null,
- rxTokens = new RegExp("([A-Za-z0-9_\\*@\\$\\-]+(?:\\[.+?\\])?)", "g"),
- rxIndex = new RegExp("(\\S+)\\[(\\d+)\\]"),
- rxPairs = new RegExp("([\\w@\\.]+)\\s*([><=]=?|[~\\^\\$\\!\\*]=|\\?|!\\*)\\s*([@\\w\\s_\\'$\\.\\+-\\/\\:]+)(\\s*|$)", "g"),
- rxCondition = new RegExp("(\\S+)\\[(.+)\\]"),
+ rxTokens = /([A-Za-z0-9_\*@\$\(\)]+(?:\[.+?\])?)/g,
+ rxIndex = /^(\S+)\((\d+)\)$/,
+ rxPairs = /(\(+)?([\w\.\(\)\$\_]+)(?:\s*)([\=\^\!\*\~\>\<\?\$]{1,2})\s*(?:\s*)("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|[^' \&\|\)\(]+)\s*(\)+)?/g,
+ rxCondition = /(\S+)\[(.+)\]/,
+ rxEscQuote = /\\('|")/g,
- app = Array.prototype.push,
- apc = Array.prototype.concat,
+ app = Array.prototype.push,
+ apc = Array.prototype.concat,
/**
* Private API
* @type {Object}
*/
hidden = {
/**
+ * Function that strips wrapping quotes
+ * @param {String} s String that contains quotes around a word
+ * @return {String} Word without quotes
+ */
+ qtrim: function(s) {
+ return((!s.indexOf("'") || !s.indexOf('"')) && (s.slice(-1) === "'" || s.slice(-1) === '"')) ? s.slice(1, -1) : s;
+ },
+ /**
* Converts an object into an Array if it isn't
* @param {Object} o Any type of object
* @return {Array} Array of an object or an empty Array
*/
toArray: function(o) {
- return o instanceof Array ? o : (o === undef || o === null) ? [] : [o];
+ return o instanceof Array ? o : (o === undef || o === NULL) ? [] : [o];
},
+
/**
* Recursive function that walks through an object, extracting pattern matches
* @param {String} pattern jPath expression
@@ -38,37 +50,38 @@
var out, data = (obj || this.data),
temp, tokens, token, idxToken, index, expToken, condition, tail, self = arguments.callee,
found, i, j, l;
- if (data && typeof(pattern) === STRING) {
+ if(data && typeof(pattern) === STRING) {
tokens = pattern.match(rxTokens); //dot notation splitter
//Get first token
token = tokens[0];
//Trailing tokens
tail = tokens.slice(1).join(PERIOD);
- if (data instanceof Array) {
+ if(data instanceof Array) {
temp = [];
- for (i = 0, l = data.length; l > i; i++) {
- j = data[i];
- found = self.apply(this, [token, cfn, j]);
- if (((found instanceof Array) && found.length) || found !== undef) {
- app.apply(temp, [found]);
+ for(i = 0, j;
+ (j = data[i]) != NULL; i++) {
+ found = self.call(this, token, cfn, j);
+ if(((found instanceof Array) && found.length) || found !== undef) {
+ app.call(temp, found);
}
}
- if (temp.length) {
- return tail ? self.apply(this, [tail, cfn, temp]) : temp;
+ if(temp.length) {
+ return tail ? self.call(this, tail, cfn, temp) : temp;
} else {
return;
}
- } else if (token === "*") {
- return tail ? self.apply(this, [tail, cfn, data]) : data;
- } else if (data[token] !== undef) {
- return tail ? self.apply(this, [tail, cfn, data[token]]) : data[token];
- } else if (rxIndex.test(token)) {
+ } else if(token === "*") {
+ return tail ? self.call(this, tail, cfn, data) : data;
+ } else if(data[token] !== undef) {
+ return tail ? self.call(this, tail, cfn, data[token]) : data[token];
+ } else if(rxIndex.test(token)) {
idxToken = token.match(rxIndex);
token = idxToken[1];
index = +idxToken[2];
- return tail ? self.apply(this, [tail, cfn, data[token][index]]) : data[token][index];
- } else if (rxCondition.test(token)) {
+ temp = data[token];
+ return tail ? self.call(this, tail, cfn, (temp && temp.length) ? temp[index] : temp) : (temp && temp.length) ? temp[index] : temp;
+ } else if(rxCondition.test(token)) {
expToken = token.match(rxCondition);
token = expToken[1];
condition = expToken[2];
@@ -76,36 +89,36 @@
var evalStr, isMatch, subset = token === "*" ? data : data[token],
elem;
- if (subset instanceof Array) {
+ if(subset instanceof Array) {
temp = [];
//Second loop here is faster than recursive call
- for (i = 0, l = subset.length; l > i; i++) {
- elem = subset[i];
+ for(i = 0;
+ (elem = subset[i]) != NULL; i++) {
//Convert condition pairs to booleans
- evalStr = condition.replace(rxPairs, function($0, $1, $2, $3) {
- return hidden.testPairs.apply(elem, [$1, $3, $2, cfn]);
+ evalStr = condition.replace(rxPairs, function(match, pl, left, operator, right, pr) {
+ return [pl, hidden.testPairs.call(elem, left, right, operator, cfn), pr].join(EMPTY);
});
//Evaluate expression
isMatch = eval(evalStr);
- if (isMatch) {
- app.apply(temp, [elem]);
+ if(isMatch) {
+ app.call(temp, elem);
}
}
- if (temp.length) {
- return tail ? self.apply(this, [tail, cfn, temp]) : temp;
+ if(temp.length) {
+ return tail ? self.call(this, tail, cfn, temp) : temp;
} else {
return;
}
} else {
elem = subset;
//Convert condition pairs to booleans
- evalStr = condition.replace(rxPairs, function($0, $1, $2, $3) {
- return hidden.testPairs.apply(elem, [$1, $3, $2, cfn]);
+ evalStr = condition.replace(rxPairs, function(match, pl, left, operator, right, pr) {
+ return [pl, hidden.testPairs.call(elem, left, right, operator, cfn), pr].join(EMPTY);
});
//Evaluate expression
isMatch = eval(evalStr);
- if (isMatch) {
- return tail ? self.apply(this, [tail, cfn, elem]) : elem;
+ if(isMatch) {
+ return tail ? self.call(this, tail, cfn, elem) : elem;
}
}
}
@@ -115,9 +128,9 @@
//Matches type of a to b
matchTypes: function(a, b) {
var _a, _b;
- switch (typeof(a)) {
- case "string":
- _b = b + '';
+ switch(typeof(a)) {
+ case STRING:
+ _b = b + EMPTY;
break;
case "boolean":
_b = b === "true" ? TRUE : FALSE;
@@ -132,10 +145,10 @@
default:
_b = b;
}
- if (b === "null") {
- _b = null;
+ if(b === "null") {
+ _b = NULL;
}
- if (b === "undefined") {
+ if(b === "undefined") {
_b = undef;
}
return {
@@ -155,9 +168,6 @@
"!=": function(l, r) {
return l !== r;
},
- "^=": function(l, r) {
- return !((l + '').indexOf(r));
- },
"<": function(l, r) {
return l < r;
},
@@ -171,22 +181,26 @@
return l >= r;
},
"~=": function(l, r) {
- return (l + '').toLowerCase() === (r + '').toLowerCase();
+ return(l + EMPTY).toLowerCase() === (r + EMPTY).toLowerCase();
+ },
+ "^=": function(l, r) {
+ return !((l + EMPTY).indexOf(r));
},
"$=": function(l, r) {
- return new RegExp(r + "$", "i").test(l);
+ return(r + EMPTY) === (l + EMPTY).slice(-(r + EMPTY).length);
},
"*=": function(l, r) {
- return (l + '').indexOf(r) >= 0;
+ return(l + EMPTY).toLowerCase().indexOf((r + EMPTY).toLowerCase()) !== -1;
}
};
return function(left, right, operator, fn) {
var out = FALSE,
- leftVal = left.indexOf(PERIOD) !== -1 ? hidden.traverse(left, null, this) : this[left],
- pairs = hidden.matchTypes(leftVal, right.trim());
- if (operator === "?") {
- if (typeof(fn) === "function") {
+ leftVal = left.indexOf(PERIOD) >= 0 ? hidden.traverse(left, NULL, this) : this[left],
+ //We clean up r to remove wrapping quotes and escaped quotes (both single/dbl)
+ pairs = hidden.matchTypes(leftVal, hidden.qtrim(right).trim().replace(rxEscQuote, '$1'));
+ if(operator === "?") {
+ if(typeof(fn) === FUNCTION) {
out = fn.call(this, pairs.left, right);
}
} else {
@@ -213,10 +227,10 @@
*/
function JPath(obj) {
- if (!(this instanceof JPath)) {
+ if(!(this instanceof JPath)) {
return new JPath(obj);
}
- this.data = obj || null;
+ this.data = obj || NULL;
this.selection = [];
}
@@ -235,14 +249,14 @@
* @return {Var} Any type of object located in the first element of the result Array
*/
first: function() {
- return this.selection.length ? this.selection[0] : null;
+ return this.selection.length ? this.selection[0] : NULL;
},
/**
* Returns a last match element
* @return {Var} Any type of object located in the last element of the result Array
*/
last: function() {
- return this.selection.length ? this.selection.slice(-1)[0] : null;
+ return this.selection.length ? this.selection.slice(-1)[0] : NULL;
},
/**
* Returns an exact match element located at idx position
@@ -250,7 +264,7 @@
* @return {Var} Any type of object located in result Array[idx]
*/
eq: function(idx) {
- return this.selection.length ? this.selection[idx] : null;
+ return this.selection.length ? this.selection[idx] : NULL;
},
/**
* Applies matching pattern to an object
@@ -290,7 +304,7 @@
* @return {JPath} Instance of a JPath object pre-filled with results
*/
module.exports.select = function(obj, pattern, cfn) {
- return JPath(obj).select(pattern, cfn, null);
+ return JPath(obj).select(pattern, cfn, NULL);
};
/**
* Returns results of the pattern-matching as an Array
@@ -300,6 +314,6 @@
* @return {Array} Search results
*/
module.exports.filter = function(obj, pattern, cfn) {
- return JPath(obj).select(pattern, cfn, null).val();
+ return JPath(obj).select(pattern, cfn, NULL).val();
};
})(Array);
2  package.json
View
@@ -1,7 +1,7 @@
{
"name": "node-jpath",
"description": "jPath: Traversal utility to help you digg deeper into complex objects or arrays of objects",
- "version": "2.0.0",
+ "version": "2.1.0",
"author": {
"name": "Simon Tsvilik",
"email": "webdevsimon@gmail.com"
Please sign in to comment.
Something went wrong with that request. Please try again.