more tests, refinement of path statements, edited readme

Author: Phillip Clark

README.md

@@ -5,4 +5,63 @@ JSON-Path utility (XPath for JSON) for nodejs and modern browsers.
 
 You may be looking for the prior work [found here](http://goessner.net/articles/JsonPath/). This implementation is a new JSON-Path syntax building on [JSON Pointer (RFC 6901)](http://tools.ietf.org/html/rfc6901) in order to ensure that any valid JSON pointer is also valid JSON-Path.
 
-This is a work in progress with many expressions succeeding, but I've got some performance enhancements and additional testing to complete before I make an NPM package.
+## Basics
+
+JSON-Path takes a specially formatted *path* statement and applies it to an object graph in order to *select* results. The results are returned as an array of data that matches the path.
+
+Most paths start out looking like a JSON Pointer...
+
+```javascript
+// From: http://goessner.net/articles/JsonPath/
+var data = {
+  store: {
+    book: [
+      { category: "reference",
+        author: "Nigel Rees",
+        title: "Sayings of the Century",
+        price: 8.95
+      },
+      { category: "fiction",
+        author: "Evelyn Waugh",
+        title: "Sword of Honour",
+        price: 12.99
+      },
+      { category: "fiction",
+        author: "Herman Melville",
+        title: "Moby Dick",
+        isbn: "0-553-21311-3",
+        price: 8.99
+      },
+      { category: "fiction",
+        author: "J. R. R. Tolkien",
+        title: "The Lord of the Rings",
+        isbn: "0-395-19395-8",
+        price: 22.99
+      }
+    ],
+    bicycle: {
+      color: "red",
+      price: 19.95
+    }
+  }
+};
+```
+
+The pointer `/store/book/0` refers to the first book in the array of books (the one by Nigen Rees).
+
+**Differentiator**
+
+The thing that makes JSON-Path different from JSON-Pointer is that you can do more than reference a single thing. Instead, you are able to `select` the things out of a structure, such as:
+
+`/store/book[*]/price`
+```javascript
+[8.95, 12.99, 8.99, 22.99]
+```
+
+In the preceding example, the path `/store/book[*]/price` has three distinct statements:
+
+Statement | Meaning
+--- | ---
+`/store/book` | Get the book property from store. This is similar to `data.store.book` in javascript.
+`*` | Select any element (or property).
+`/price` | Select the price property.

examples/json-path-example.js

@@ -129,4 +129,16 @@ res = p.resolve(data, {
 expect(res).to.contain(data.store.book[0].category);
 expect(res).to.contain(data.store.book[2].category);
 
+p = jpath.resolve(data, '/store/book[first(2)]');
+
+p = jpath.create("#/store/book[*][@]");
+var res = p.resolve(data, function(obj, accum, sel) {
+  if (obj.price && obj.price < 10)
+    accum.push(obj);
+  return accum;
+});
+expect(res).to.contain(data["store"]["book"][0]);
+expect(res).to.contain(data["store"]["book"][2]);
+expect(res).to.have.length(2);
+
 // p = jpath.parseSelector("[..#/book[*][{#/price >= 10}]]");

index.js

@@ -117,9 +117,7 @@
 	}
 
 	function expect(source, state, expected) {
-		dbc([source.indexOf(expected, state.cursor) == state.cursor], function() {
-			return "Expected `".concat(expected, '` at position ', state.cursor, '.');
-		});
+		expectSequence(source, state.cursor, source.length, expected);
 	}
 
 	function pipedSelect(datum, steps, fn) {
@@ -245,11 +243,18 @@
 		}
 		var n = source.substring(cursor, end);
 		state.result.push(function(data, accum, sel) {
+			var target;
 			if (data) {
-				dbc([sel, typeof sel[n] === "function"], function() {
-					return "Missing user-supplied function: `".concat(n, "`.");
-				});
-				return sel[n](data, accum, sel);
+ 				if (n.length === 0 && typeof sel === 'function') {
+ 					target = sel;
+				} else if (typeof sel === 'object' && sel) {
+					target = sel[n];
+				}
+				if (!target) {
+					throw new Error("Missing user-supplied function: `"
+						.concat((n.length) ? n : '@', "`."));
+				}
+				return target(data, accum, sel);
 			}
 			return accum;
 		});
@@ -267,6 +272,33 @@
 		return state.result;
 	}
 
+	function expectInteger(source, cursor, end) {
+		var c = cursor;
+		while(source[c] >= '0' && source[c] <= '9') c++;
+		if (c == cursor) {
+			throw new Error('Expected an integer at position '
+				.concat(c, '.'));
+		}
+		return c - cursor;
+	}
+
+	function parseArrayVerb(source, cursor, end, verb, thems){
+		var index = 1
+		, len;
+ 		expectSequence(source, cursor, end, verb);
+		cursor += (verb.length - 1);
+		if (source[cursor + 1] === '(') {
+			cursor += 2;
+			len = expectInteger(source, cursor, end);
+			index = parseInt(source.substring(cursor, cursor + len));
+			cursor += len;
+			expectSequence(source, cursor, end, ')');
+			++cursor;
+		}
+		thems.push({ kind: verb[0], index: index});
+		return cursor;
+	}
+
 	function parseSelectByIndex(source, state) {
 		var cursor = state.cursor - 1
 		, len = source.length
@@ -282,14 +314,14 @@
 			switch(source[cursor]) {
 				case ' ':
 				if (num !== null) {
-					thems.push({ kind: 'index', index: parseInt(source.substring(num, cursor))});
+					thems.push({ kind: 'i', index: parseInt(source.substring(num, cursor))});
 					num = null;
 					punct = true;
 				}
 				break;
 				case ',': {
 					if (num !== null) {
-						thems.push({ kind: 'index', index: parseInt(source.substring(num, cursor))});
+						thems.push({ kind: 'i', index: parseInt(source.substring(num, cursor))});
 						num = null;
 					}
 					if (punct) punct = false;
@@ -298,7 +330,7 @@
 				case '.': {
 					expectSequence(source, cursor, end, '..');
 					if (num !== null) {
-						thems.push({ kind: 'sequence', index: parseInt(source.substring(num, cursor))});
+						thems.push({ kind: 's', index: parseInt(source.substring(num, cursor))});
 						num = null;
 					}
 					cursor++;
@@ -321,63 +353,70 @@
 						throw Error("Unexpected numeral at position "
 							.concat(cursor, " expected punctuation."));
 					}
-					expectSequence(source, cursor, end, 'last');
-					cursor += 3
-					thems.push('last');
+					cursor = parseArrayVerb(source, cursor, end, "last", thems);
 					break;
 				}
 				case 'f': {
 					if (punct) {
 						throw Error("Unexpected numeral at position "
 							.concat(cursor, " expected punctuation."));
 					}
-					expectSequence(source, cursor, end, 'first');
-					cursor += 4
-					thems.push('first');
+					cursor = parseArrayVerb(source, cursor, end, "first", thems);
+					break;
+				}
+				case 'c': {
+					if (punct) {
+						throw Error("Unexpected numeral at position "
+							.concat(cursor, " expected punctuation."));
+					}
+					cursor = parseArrayVerb(source, cursor, end, "count", thems);
 					break;
 				}
 			}
 		}
 		if (num !== null) {
-			thems.push({ kind: 'index', index: parseInt(source.substring(num, cursor))});
+			thems.push({ kind: 'i', index: parseInt(source.substring(num, cursor))});
 		}
 		state.result.push(function(obj, accum) {
 			accum = accum || [];
 			if (Array.isArray(obj)) {
 				var i = -1
 				, len = thems.length
 				, alen = obj.length
-				, s, slast
+				, j, last
 				;
 				while(++i < len) {
 					var it = thems[i];
-					if (typeof it === 'string') {
-						switch(it[0]) {
-							case 'c': {
-								accum.push(alen);
-								break;
-							}
-							case 'f': {
-								if (alen) {
-									accum.push(obj[0]);
-								}
-								break;
+					switch(it.kind) {
+						case 'c': {
+							accum.push(alen);
+							break;
+						}
+						case 'f': {
+							j = -1;
+							while(++j < it.index && j < alen) {
+								accum.push(obj[j]);
 							}
-							case 'l': {
-								if (alen) {
-									accum.push(obj[alen - 1]);
-								}
-								break;
+							break;
+						}
+						case 'l': {
+							j = alen;
+							last = alen - it.index;
+							while(--j >= last && j > 0) {
+								accum.push(obj[j]);
 							}
+							break;
 						}
-					} else {
-						if (it.index < alen) {
-							accum.push(obj[it.index]);
-							if (it.kind === 'sequence') {
-								s = it.index;
-								slast = (++i < len) ? thems[i].index : alen - 1;
-								while(++s <= slast) {
-									accum.push(obj[s]);
+						case 'i':
+						case 's': {
+							if (it.index < alen) {
+								accum.push(obj[it.index]);
+								if (it.kind === 's') {
+									j = it.index;
+									last = (++i < len) ? thems[i].index : alen - 1;
+									while(++j <= last) {
+										accum.push(obj[j]);
+									}
 								}
 							}
 						}
@@ -449,7 +488,6 @@
 					break;
 				}
 				case '@': {
-					expect(source, state, '@');
 					state.cursor += 1;
 					parseUserSelector(source,state);
 					break;

test/tests.js

@@ -490,4 +490,95 @@ describe('JSON-path references resolve all valid JSON Pointers', function() {
 			});
 		});
 
+		describe('the path /store/book[first(2)]', function() {
+			it('selects the first 2 books', function() {
+				var p = JsonPath.create("/store/book[first(2)]"),
+				res = p.resolve(data);
+				expect(res).to.contain(data["store"]["book"][0]);
+				expect(res).to.contain(data["store"]["book"][1]);
+				expect(res).to.have.length(2);
+			});
+		});
+
+
+		describe('the path /store/book[count]', function() {
+			it('selects the book count', function() {
+				var p = JsonPath.create("/store/book[count]"),
+				res = p.resolve(data);
+				expect(res).to.contain(data.store.book.length);
+				expect(res).to.have.length(1);
+			});
+		});
+
+		describe('the path /store/book[last(2)]', function() {
+			it('selects the last 2 books', function() {
+				var p = JsonPath.create("/store/book[last(2)]"),
+				res = p.resolve(data);
+				expect(res).to.contain(data["store"]["book"][data.store.book.length - 1]);
+				expect(res).to.contain(data["store"]["book"][data.store.book.length - 2]);
+				expect(res).to.have.length(2);
+			});
+		});
+
+		describe('the path /store/book[*]/isbn', function() {
+			it('selects the last 2 books', function() {
+				var p = JsonPath.create("/store/book[*]/isbn"),
+				res = p.resolve(data);
+				expect(res).to.contain(data["store"]["book"][2]["isbn"]);
+				expect(res).to.contain(data["store"]["book"][3]["isbn"]);
+				expect(res).to.have.length(2);
+			});
+		});
+
+		describe('the path #/store/book[*]#/isbn', function() {
+			it('selects the last 2 books', function() {
+				var p = JsonPath.create("#/store/book[*]#/isbn"),
+				res = p.resolve(data);
+				expect(res).to.contain(data["store"]["book"][2]["isbn"]);
+				expect(res).to.contain(data["store"]["book"][3]["isbn"]);
+				expect(res).to.have.length(2);
+			});
+		});
+
+		describe('path with user-supplied selector #/store/book[*][@]', function() {
+			it('selects the books with prices greater than ten', function() {
+				var p = JsonPath.create("#/store/book[*][@]"),
+				res = p.resolve(data, function(obj, accum, sel) {
+					if (obj.price && obj.price < 10)
+						accum.push(obj);
+					return accum;
+				});
+				expect(res).to.contain(data["store"]["book"][0]);
+				expect(res).to.contain(data["store"]["book"][2]);
+				expect(res).to.have.length(2);
+			});
+		});
+
+		describe('path with user-supplied selector #/store/book[*][@gt10]', function() {
+			it('selects the books with prices greater than ten', function() {
+				var p = JsonPath.create("#/store/book[*][@gt10]"),
+				res = p.resolve(data, { gt10: function(obj, accum, sel) {
+					if (obj.price && obj.price < 10)
+						accum.push(obj);
+					return accum;
+				}});
+				expect(res).to.contain(data["store"]["book"][0]);
+				expect(res).to.contain(data["store"]["book"][2]);
+				expect(res).to.have.length(2);
+			});
+		});
+
+		describe('path with user-supplied selector followed by further path #/store/book[*][@gt10]/catagory', function() {
+			it('selects the books with prices greater than ten', function() {
+				var p = JsonPath.create("#/store/book[*][@gt10]/category"),
+				res = p.resolve(data, { gt10: function(obj, accum, sel) {
+					if (obj.price && obj.price < 10)
+						accum.push(obj);
+					return accum;
+				}});
+				expect(res).to.contain(data["store"]["book"][0].category);
+				expect(res).to.contain(data["store"]["book"][2].category);
+				expect(res).to.have.length(2);
+			});
+		});
 	});