├── .gitignore
├── test
    ├── all.js
    ├── js-array.js
    ├── intern.js
    └── query.js
├── .travis.yml
├── util
    ├── contains.js
    └── each.js
├── package.js
├── package.json
├── query.js
├── parser.js
├── README.md
├── js-array.js
└── specification
    ├── draft-zyp-rql-00.xml
    └── draft-zyp-rql-00.html


/.gitignore:
--------------------------------------------------------------------------------
1 | downloaded-modules
2 | node_modules
3 | npm-debug.log
4 | 


--------------------------------------------------------------------------------
/test/all.js:
--------------------------------------------------------------------------------
1 | define(function (require) {
2 | 	require('./js-array');
3 | 	require('./query');
4 | });
5 | 


--------------------------------------------------------------------------------
/.travis.yml:
--------------------------------------------------------------------------------
 1 | language: node_js
 2 | node_js:
 3 |   - 0.10
 4 | 
 5 | env:
 6 |   global:
 7 |       - SAUCE_USERNAME: persvr-ci
 8 |       - SAUCE_ACCESS_KEY: d8dc90f7-08ca-41a5-8055-c452116b9ef7
 9 | 
10 | install:
11 |   - travis_retry npm install
12 | 
13 | script: npm test && npm run test.sauce
14 | 


--------------------------------------------------------------------------------
/util/contains.js:
--------------------------------------------------------------------------------
 1 | ({define:typeof define!=='undefined'?define:function(deps, factory){module.exports = factory(exports);}}).
 2 | define([], function(){
 3 | return contains;
 4 | 
 5 | function contains(array, item){
 6 | 	for(var i = 0, l = array.length; i < l; i++){
 7 | 		if(array[i] === item){
 8 | 			return true;
 9 | 		}
10 | 	}
11 | }
12 | });
13 | 


--------------------------------------------------------------------------------
/util/each.js:
--------------------------------------------------------------------------------
 1 | ({define:typeof define!=='undefined'?define:function(deps, factory){module.exports = factory(exports);}}).
 2 | define([], function(){
 3 | return each;
 4 | 
 5 | function each(array, callback){
 6 | 	var emit, result;
 7 | 	if (callback.length > 1) {
 8 | 		// can take a second param, emit
 9 | 		result = [];
10 | 		emit = function(value){
11 | 			result.push(value);
12 | 		};
13 | 	}
14 | 	for(var i = 0, l = array.length; i < l; i++){
15 | 		if(callback(array[i], emit)){
16 | 			return result || true;
17 | 		}
18 | 	}
19 | 	return result;
20 | }
21 | });
22 | 


--------------------------------------------------------------------------------
/package.js:
--------------------------------------------------------------------------------
 1 | var miniExcludes = {
 2 | 		"rql/README.md": 1,
 3 | 		"rql/package": 1
 4 | 	},
 5 | 	amdExcludes = {
 6 | 	},
 7 | 	isJsRe = /\.js$/,
 8 | 	isTestRe = /\/test\//,
 9 | 	isSpecificationRe = /\/specification\//;
10 | 
11 | var profile = {
12 | 	resourceTags: {
13 | 		test: function(filename, mid){
14 | 			return isTestRe.test(filename);
15 | 		},
16 | 
17 | 		miniExclude: function(filename, mid){
18 | 			return isTestRe.test(filename) || isSpecificationRe.test(filename) || mid in miniExcludes;
19 | 		},
20 | 
21 | 		amd: function(filename, mid){
22 | 			return isJsRe.test(filename) && !(mid in amdExcludes);
23 | 		}
24 | 	}
25 | };
26 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "rql",
 3 |   "version": "0.3.3",
 4 |   "author": "Kris Zyp",
 5 |   "contributors": [
 6 |     "Vladimir Dronnikov <dronnikov@gmail.com>"
 7 |   ],
 8 |   "keywords": [
 9 |     "resource",
10 |     "query",
11 |     "uri"
12 |   ],
13 |   "description": "Query language for the web, NoSQL",
14 |   "licenses": [
15 |     {
16 |       "type": "AFLv2.1",
17 |       "url": "http://trac.dojotoolkit.org/browser/dojo/trunk/LICENSE#L43"
18 |     },
19 |     {
20 |       "type": "BSD",
21 |       "url": "http://trac.dojotoolkit.org/browser/dojo/trunk/LICENSE#L13"
22 |     }
23 |   ],
24 |   "directories": {
25 |     "lib": "."
26 |   },
27 |   "repository": {
28 |     "type": "git",
29 |     "url": "http://github.com/kriszyp/rql"
30 |   },
31 |   "maintainers": [
32 |     {
33 |       "name": "Kris Zyp",
34 |       "email": "kriszyp@gmail.com"
35 |     }
36 |   ],
37 |   "mappings": {
38 |     "patr": "http://github.com/kriszyp/patr/zipball/v0.2.1",
39 |     "promised-io": "http://github.com/kriszyp/promised-io/zipball/v0.2.1"
40 |   },
41 |   "dependencies": {
42 |     "promised-io": ">=0.3.0"
43 |   },
44 |   "devDependencies": {
45 |     "intern-geezer": "^2.1.1"
46 |   },
47 |   "scripts": {
48 |     "test": "intern-client config=test/intern",
49 |     "test.sauce": "intern-runner config=test/intern",
50 |     "test.proxy": "intern-runner config=test/intern --proxyOnly"
51 |   },
52 |   "icon": "http://packages.dojofoundation.org/images/persvr.png",
53 |   "dojoBuild": "package.js"
54 | }
55 | 


--------------------------------------------------------------------------------
/test/js-array.js:
--------------------------------------------------------------------------------
 1 | define(function (require) {
 2 | 	var test = require('intern!object'),
 3 | 		assert = require('intern/chai!assert'),
 4 | 		Query = require('../query').Query,
 5 | 		executeQuery = require('../js-array').executeQuery;
 6 | 
 7 | 	var data = [
 8 | 		{
 9 | 			'with/slash': 'slashed',
10 | 			nested: {
11 | 				property: 'value'
12 | 			},
13 | 			price: 10,
14 | 			name: 'ten',
15 | 			tags: [ 'fun', 'even' ]
16 | 		},
17 | 		{
18 | 			price: 5,
19 | 			name: 'five',
20 | 			tags: [ 'fun' ]
21 | 		}
22 | 	];
23 | 
24 | 	test({
25 | 		name: 'rql/test/js-array',
26 | 
27 | 		testFiltering: function () {
28 | 			assert.equal(executeQuery('price=lt=10', {}, data).length, 1);
29 | 			assert.equal(executeQuery('price=lt=11', {}, data).length, 2);
30 | 			assert.equal(executeQuery('nested/property=value', {}, data).length, 1);
31 | 			assert.equal(executeQuery('with%2Fslash=slashed', {}, data).length, 1);
32 | 			assert.equal(executeQuery('out(price,(5,10))', {}, data).length, 0);
33 | 			assert.equal(executeQuery('out(price,(5))', {}, data).length, 1);
34 | 			assert.equal(executeQuery('contains(tags,even)', {}, data).length, 1);
35 | 			assert.equal(executeQuery('contains(tags,fun)', {}, data).length, 2);
36 | 			assert.equal(executeQuery('excludes(tags,fun)', {}, data).length, 0);
37 | 			assert.equal(executeQuery('excludes(tags,ne(fun))', {}, data).length, 1);
38 | 			assert.equal(executeQuery('excludes(tags,ne(even))', {}, data).length, 0);
39 | 			// eq() on re: should trigger .match()
40 | 			assert.deepEqual(executeQuery('price=match=10', {}, data), [ data[0] ]);
41 | 			// ne() on re: should trigger .not(.match())
42 | 			assert.deepEqual(executeQuery('name=match=f.*', {}, data), [ data[1] ]);
43 | 			assert.deepEqual(executeQuery('name=match=glob:f*', {}, data), [ data[1] ]);
44 | 			assert.deepEqual(executeQuery(new Query().match('name', /f.*/), {}, data), [data[1]]);
45 | 		},
46 | 
47 | 		testFiltering1: function () {
48 | 			var data = [
49 | 				{ 'path.1': [ 1, 2, 3 ] },
50 | 				{ 'path.1': [ 9, 3, 7 ] }
51 | 			];
52 | 
53 | 			assert.deepEqual(executeQuery('contains(path,3)&sort()', {}, data), []); // path is undefined
54 | 			assert.deepEqual(executeQuery('contains(path.1,3)&sort()', {}, data), data); // 3 found in both
55 | 			assert.deepEqual(executeQuery('excludes(path.1,3)&sort()', {}, data), []); // 3 found in both
56 | 			assert.deepEqual(executeQuery('excludes(path.1,7)&sort()', {}, data), [ data[0] ]); // 7 found in second
57 | 		}
58 | 	});
59 | });
60 | 


--------------------------------------------------------------------------------
/test/intern.js:
--------------------------------------------------------------------------------
 1 | // Learn more about configuring this file at <https://github.com/theintern/intern/wiki/Configuring-Intern>.
 2 | // These default settings work OK for most people. The options that *must* be changed below are the
 3 | // packages, suites, excludeInstrumentation, and (if you want functional tests) functionalSuites.
 4 | define({
 5 | 	// The port on which the instrumenting proxy will listen
 6 | 	proxyPort: 9000,
 7 | 
 8 | 	// A fully qualified URL to the Intern proxy
 9 | 	proxyUrl: 'http://localhost:9000/',
10 | 
11 | 	// Default desired capabilities for all environments. Individual capabilities can be overridden by any of the
12 | 	// specified browser environments in the `environments` array below as well. See
13 | 	// https://code.google.com/p/selenium/wiki/DesiredCapabilities for standard Selenium capabilities and
14 | 	// https://saucelabs.com/docs/additional-config#desired-capabilities for Sauce Labs capabilities.
15 | 	// Note that the `build` capability will be filled in with the current commit ID from the Travis CI environment
16 | 	// automatically
17 | 	capabilities: {
18 | 		'selenium-version': '2.42.0',
19 | 		'idle-timeout': 30
20 | 	},
21 | 
22 | 	// Browsers to run integration testing against. Note that version numbers must be strings if used with Sauce
23 | 	// OnDemand. Options that will be permutated are browserName, version, platform, and platformVersion; any other
24 | 	// capabilities options specified for an environment will be copied as-is
25 | 	environments: [
26 | 		{ browserName: 'internet explorer', version: '11', platform: 'Windows 8.1' },
27 | 		{ browserName: 'internet explorer', version: '10', platform: 'Windows 8' },
28 | 		{ browserName: 'internet explorer', version: '9', platform: 'Windows 7' },
29 | 		{ browserName: 'internet explorer', version: '8', platform: 'Windows XP' },
30 | 		{ browserName: 'firefox', version: '31', platform: [ 'OS X 10.9', 'Windows 7', 'Linux' ] },
31 | 		{ browserName: 'chrome', version: '34', platform: [ 'OS X 10.9', 'Windows 7', 'Linux' ] },
32 | 		{ browserName: 'safari', version: '7', platform: 'OS X 10.9' }
33 | 	],
34 | 
35 | 	// Maximum number of simultaneous integration tests that should be executed on the remote WebDriver service
36 | 	maxConcurrency: 3,
37 | 
38 | 	// Name of the tunnel class to use for WebDriver tests
39 | 	tunnel: 'SauceLabsTunnel',
40 | 
41 | 	// Configuration options for the module loader; any AMD configuration options supported by the specified AMD loader
42 | 	// can be used here
43 | 	loader: (typeof process === 'undefined' && location.search.indexOf('config=rql') > -1) ?
44 | 		{
45 | 			// if we are using the full path to rql, we assume we are running
46 | 			// in a sibling path configuration
47 | 			baseUrl: '../..'
48 | 		} : {},
49 | 
50 | 	// Non-functional test suite(s) to run in each browser
51 | 	suites: [ (typeof process === 'undefined' && location.search.indexOf('config=rql') > -1) ?
52 | 		'rql/test/all' : 'test/all' ],
53 | 
54 | 	// A regular expression matching URLs to files that should not be included in code coverage analysis
55 | 	excludeInstrumentation: /^(?:test|node_modules)\//
56 | });
57 | 


--------------------------------------------------------------------------------
/query.js:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * Provides a Query constructor with chainable capability. For example:
  3 |  * var Query = require("./query").Query;
  4 |  * query = Query();
  5 |  * query.executor = function(query){
  6 |  *		require("./js-array").query(query, params, data); // if we want to operate on an array
  7 |  * };
  8 |  * query.eq("a", 3).le("b", 4).forEach(function(object){
  9 |  *	 // for each object that matches the query
 10 |  * });
 11 |  */
 12 | //({define:typeof define!="undefined"?define:function(deps, factory){module.exports = factory(exports, require("./parser"), require("./js-array"));}}).
 13 | //define(["exports", "./parser", "./js-array"], function(exports, parser, jsarray){
 14 | ({define:typeof define!="undefined"?define:function(deps, factory){module.exports = factory(exports, require("./parser"), require("./util/each"));}}).
 15 | define(["exports", "./parser", "./util/each"], function(exports, parser, each){
 16 | 
 17 | var parseQuery = parser.parseQuery;
 18 | try{
 19 | 	var when = require("promised-io/promise").when;
 20 | }catch(e){
 21 | 	when = function(value, callback){callback(value)};
 22 | }
 23 | 
 24 | parser.Query = function(seed, params){
 25 | 	if (typeof seed === 'string')
 26 | 		return parseQuery(seed, params);
 27 | 	var q = new Query();
 28 | 	if (seed && seed.name && seed.args)
 29 | 		q.name = seed.name, q.args = seed.args;
 30 | 	return q;
 31 | };
 32 | exports.Query = parser.Query;
 33 | //TODO:THE RIGHT WAY IS:exports.knownOperators = Object.keys(jsarray.operators || {}).concat(Object.keys(jsarray.jsOperatorMap || {}));
 34 | exports.knownOperators = ["sort", "match", "in", "out", "or", "and", "select", "contains", "excludes", "values", "limit", "distinct", "recurse", "aggregate", "between", "sum", "mean", "max", "min", "count", "first", "one", "eq", "ne", "le", "ge", "lt", "gt"];
 35 | exports.knownScalarOperators = ["mean", "sum", "min", "max", "count", "first", "one"];
 36 | exports.arrayMethods = ["forEach", "reduce", "map", "filter", "indexOf", "some", "every"];
 37 | 
 38 | function Query(name){
 39 | 	this.name = name || "and";
 40 | 	this.args = [];
 41 | }
 42 | function serializeArgs(array, delimiter){
 43 | 	var results = [];
 44 | 	for(var i = 0, l = array.length; i < l; i++){
 45 | 		results.push(queryToString(array[i]));
 46 | 	}
 47 | 	return results.join(delimiter);
 48 | }
 49 | exports.Query.prototype = Query.prototype;
 50 | Query.prototype.toString = function(){
 51 | 	return this.name === "and" ?
 52 | 		serializeArgs(this.args, "&") :
 53 | 		queryToString(this);
 54 | };
 55 | 
 56 | function queryToString(part) {
 57 | 		if (part instanceof Array) {
 58 | 				return '(' + serializeArgs(part, ",")+')';
 59 | 		}
 60 | 		if (part && part.name && part.args) {
 61 | 				return [
 62 | 						part.name,
 63 | 						"(",
 64 | 						serializeArgs(part.args, ","),
 65 | 						")"
 66 | 				].join("");
 67 | 		}
 68 | 		return exports.encodeValue(part);
 69 | };
 70 | 
 71 | function encodeString(s) {
 72 | 		if (typeof s === "string") {
 73 | 				s = encodeURIComponent(s);
 74 | 				if (s.match(/[\(\)]/)) {
 75 | 						s = s.replace("(","%28").replace(")","%29");
 76 | 				};
 77 | 		}
 78 | 		return s;
 79 | }
 80 | 
 81 | exports.encodeValue = function(val) {
 82 | 		var encoded;
 83 | 		if (val === null) val = 'null';
 84 | 		if (val !== parser.converters["default"]('' + (
 85 | 				val.toISOString && val.toISOString() || val.toString()
 86 | 		))) {
 87 | 				var type = typeof val;
 88 | 				if(val instanceof RegExp){
 89 | 					// TODO: control whether to we want simpler glob() style
 90 | 					val = val.toString();
 91 | 					var i = val.lastIndexOf('/');
 92 | 					type = val.substring(i).indexOf('i') >= 0 ? "re" : "RE";
 93 | 					val = encodeString(val.substring(1, i));
 94 | 					encoded = true;
 95 | 				}
 96 | 				if(type === "object"){
 97 | 						type = "epoch";
 98 | 						val = val.getTime();
 99 | 						encoded = true;
100 | 				}
101 | 				if(type === "string") {
102 | 						val = encodeString(val);
103 | 						encoded = true;
104 | 				}
105 | 				val = [type, val].join(":");
106 | 		}
107 | 		if (!encoded && typeof val === "string") val = encodeString(val);
108 | 		return val;
109 | };
110 | 
111 | exports.updateQueryMethods = function(){
112 | 	each(exports.knownOperators, function(name){
113 | 		Query.prototype[name] = function(){
114 | 			var newQuery = new Query();
115 | 			newQuery.executor = this.executor;
116 | 			var newTerm = new Query(name);
117 | 			newTerm.args = Array.prototype.slice.call(arguments);
118 | 			newQuery.args = this.args.concat([newTerm]);
119 | 			return newQuery;
120 | 		};
121 | 	});
122 | 	each(exports.knownScalarOperators, function(name){
123 | 		Query.prototype[name] = function(){
124 | 			var newQuery = new Query();
125 | 			newQuery.executor = this.executor;
126 | 			var newTerm = new Query(name);
127 | 			newTerm.args = Array.prototype.slice.call(arguments);
128 | 			newQuery.args = this.args.concat([newTerm]);
129 | 			return newQuery.executor(newQuery);
130 | 		};
131 | 	});
132 | 	each(exports.arrayMethods, function(name){
133 | 		// this makes no guarantee of ensuring that results supports these methods
134 | 		Query.prototype[name] = function(){
135 | 			var args = arguments;
136 | 			return when(this.executor(this), function(results){
137 | 				return results[name].apply(results, args);
138 | 			});
139 | 		};
140 | 	});
141 | 
142 | };
143 | 
144 | exports.updateQueryMethods();
145 | 
146 | /* recursively iterate over query terms calling 'fn' for each term */
147 | Query.prototype.walk = function(fn, options){
148 | 	options = options || {};
149 | 	function walk(name, terms){
150 | 		terms = terms || [];
151 | 
152 | 		var i = 0,
153 | 			l = terms.length,
154 | 			term,
155 | 			args,
156 | 			func,
157 | 			newTerm;
158 | 
159 | 		for (; i < l; i++) {
160 | 			term = terms[i];
161 | 			if (term == null) {
162 | 				term = {};
163 | 			}
164 | 			func = term.name;
165 | 			args = term.args;
166 | 			if (!func || !args) {
167 | 				continue;
168 | 			}
169 | 			if (args[0] instanceof Query) {
170 | 				walk.call(this, func, args);
171 | 			}
172 | 			else {
173 | 				newTerm = fn.call(this, func, args);
174 | 				if (newTerm && newTerm.name && newTerm.ags) {
175 | 					terms[i] = newTerm;
176 | 				}
177 | 			}
178 | 		}
179 | 	}
180 | 	walk.call(this, this.name, this.args);
181 | };
182 | 
183 | /* append a new term */
184 | Query.prototype.push = function(term){
185 | 	this.args.push(term);
186 | 	return this;
187 | };
188 | 
189 | /* disambiguate query */
190 | Query.prototype.normalize = function(options){
191 | 	options = options || {};
192 | 	options.primaryKey = options.primaryKey || 'id';
193 | 	options.map = options.map || {};
194 | 	var result = {
195 | 		original: this,
196 | 		sort: [],
197 | 		limit: [Infinity, 0, Infinity],
198 | 		skip: 0,
199 | 		limit: Infinity,
200 | 		select: [],
201 | 		values: false
202 | 	};
203 | 	var plusMinus = {
204 | 		// [plus, minus]
205 | 		sort: [1, -1],
206 | 		select: [1, 0]
207 | 	};
208 | 	function normal(func, args){
209 | 		// cache some parameters
210 | 		if (func === 'sort' || func === 'select') {
211 | 			result[func] = args;
212 | 			var pm = plusMinus[func];
213 | 			result[func+'Arr'] = result[func].map(function(x){
214 | 				if (x instanceof Array) x = x.join('.');
215 | 				var o = {};
216 | 				var a = /([-+]*)(.+)/.exec(x);
217 | 				o[a[2]] = pm[(a[1].charAt(0) === '-')*1];
218 | 				return o;
219 | 			});
220 | 			result[func+'Obj'] = {};
221 | 			result[func].forEach(function(x){
222 | 				if (x instanceof Array) x = x.join('.');
223 | 				var a = /([-+]*)(.+)/.exec(x);
224 | 				result[func+'Obj'][a[2]] = pm[(a[1].charAt(0) === '-')*1];
225 | 			});
226 | 		} else if (func === 'limit') {
227 | 			// validate limit() args to be numbers, with sane defaults
228 | 			var limit = args;
229 | 			result.skip = +limit[1] || 0;
230 | 			limit = +limit[0] || 0;
231 | 			if (options.hardLimit && limit > options.hardLimit)
232 | 				limit = options.hardLimit;
233 | 			result.limit = limit;
234 | 			result.needCount = true;
235 | 		} else if (func === 'values') {
236 | 			// N.B. values() just signals we want array of what we select()
237 | 			result.values = true;
238 | 		} else if (func === 'eq') {
239 | 			// cache primary key equality -- useful to distinguish between .get(id) and .query(query)
240 | 			var t = typeof args[1];
241 | 			//if ((args[0] instanceof Array ? args[0][args[0].length-1] : args[0]) === options.primaryKey && ['string','number'].indexOf(t) >= 0) {
242 | 			if (args[0] === options.primaryKey && ('string' === t || 'number' === t)) {
243 | 				result.pk = String(args[1]);
244 | 			}
245 | 		}
246 | 		// cache search conditions
247 | 		//if (options.known[func])
248 | 		// map some functions
249 | 		/*if (options.map[func]) {
250 | 			func = options.map[func];
251 | 		}*/
252 | 	}
253 | 	this.walk(normal);
254 | 	return result;
255 | };
256 | 
257 | /* FIXME: an example will be welcome
258 | Query.prototype.toMongo = function(options){
259 | 	return this.normalize({
260 | 		primaryKey: '_id',
261 | 		map: {
262 | 			ge: 'gte',
263 | 			le: 'lte'
264 | 		},
265 | 		known: ['lt','lte','gt','gte','ne','in','nin','not','mod','all','size','exists','type','elemMatch']
266 | 	});
267 | };
268 | */
269 | 
270 | return exports;
271 | });
272 | 


--------------------------------------------------------------------------------
/parser.js:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * This module provides RQL parsing. For example:
  3 |  * var parsed = require("./parser").parse("b=3&le(c,5)");
  4 |  */
  5 | ({define:typeof define!="undefined"?define:function(deps, factory){module.exports = factory(exports, require("./util/contains"));}}).
  6 | define(["exports", "./util/contains"], function(exports, contains){
  7 | 
  8 | var operatorMap = {
  9 | 	"=": "eq",
 10 | 	"==": "eq",
 11 | 	">": "gt",
 12 | 	">=": "ge",
 13 | 	"<": "lt",
 14 | 	"<=": "le",
 15 | 	"!=": "ne"
 16 | };
 17 | 
 18 | 
 19 | exports.primaryKeyName = 'id';
 20 | exports.lastSeen = ['sort', 'select', 'values', 'limit'];
 21 | exports.jsonQueryCompatible = true;
 22 | 
 23 | function parse(/*String|Object*/query, parameters){
 24 | 	if (typeof query === "undefined" || query === null)
 25 | 		query = '';
 26 | 	var term = new exports.Query();
 27 | 	var topTerm = term;
 28 | 	topTerm.cache = {}; // room for lastSeen params
 29 | 	var topTermName = topTerm.name;
 30 | 	topTerm.name = '';
 31 | 	if(typeof query === "object"){
 32 | 		if(query instanceof exports.Query){
 33 | 			return query;
 34 | 		}
 35 | 		for(var i in query){
 36 | 			var term = new exports.Query();
 37 | 			topTerm.args.push(term);
 38 | 			term.name = "eq";
 39 | 			term.args = [i, query[i]];
 40 | 		}
 41 | 		return topTerm;
 42 | 	}
 43 | 	if(query.charAt(0) == "?"){
 44 | 		throw new URIError("Query must not start with ?");
 45 | 	}
 46 | 	if(exports.jsonQueryCompatible){
 47 | 		query = query.replace(/%3C=/g,"=le=").replace(/%3E=/g,"=ge=").replace(/%3C/g,"=lt=").replace(/%3E/g,"=gt=");
 48 | 	}
 49 | 	if(query.indexOf("/") > -1){ // performance guard
 50 | 		// convert slash delimited text to arrays
 51 | 		query = query.replace(/[\+\*\$\-:\w%\._]*\/[\+\*\$\-:\w%\._\/]*/g, function(slashed){
 52 | 			return "(" + slashed.replace(/\//g, ",") + ")";
 53 | 		});
 54 | 	}
 55 | 	// convert FIQL to normalized call syntax form
 56 | 	query = query.replace(/(\([\+\*\$\-:\w%\._,]+\)|[\+\*\$\-:\w%\._]*|)([<>!]?=(?:[\w]*=)?|>|<)(\([\+\*\$\-:\w%\._,]+\)|[\+\*\$\-:\w%\._]*|)/g,
 57 | 						// <---------       property        -----------><------  operator -----><----------------   value ------------------>
 58 | 			function(t, property, operator, value){
 59 | 		if(operator.length < 3){
 60 | 			if(!operatorMap[operator]){
 61 | 				throw new URIError("Illegal operator " + operator);
 62 | 			}
 63 | 			operator = operatorMap[operator];
 64 | 		}
 65 | 		else{
 66 | 			operator = operator.substring(1, operator.length - 1);
 67 | 		}
 68 | 		return operator + '(' + property + "," + value + ")";
 69 | 	});
 70 | 	if(query.charAt(0)=="?"){
 71 | 		query = query.substring(1);
 72 | 	}
 73 | 	var leftoverCharacters = query.replace(/(\))|([&\|,])?([\+\*\$\-:\w%\._]*)(\(?)/g,
 74 | 							//   <-closedParan->|<-delim-- propertyOrValue -----(> |
 75 | 		function(t, closedParan, delim, propertyOrValue, openParan){
 76 | 			if(delim){
 77 | 				if(delim === "&"){
 78 | 					setConjunction("and");
 79 | 				}
 80 | 				if(delim === "|"){
 81 | 					setConjunction("or");
 82 | 				}
 83 | 			}
 84 | 			if(openParan){
 85 | 				var newTerm = new exports.Query();
 86 | 				newTerm.name = propertyOrValue;
 87 | 				newTerm.parent = term;
 88 | 				call(newTerm);
 89 | 			}
 90 | 			else if(closedParan){
 91 | 				var isArray = !term.name;
 92 | 				term = term.parent;
 93 | 				if(!term){
 94 | 					throw new URIError("Closing paranthesis without an opening paranthesis");
 95 | 				}
 96 | 				if(isArray){
 97 | 					term.args.push(term.args.pop().args);
 98 | 				}
 99 | 			}
100 | 			else if(propertyOrValue || delim === ','){
101 | 				term.args.push(stringToValue(propertyOrValue, parameters));
102 | 
103 | 				// cache the last seen sort(), select(), values() and limit()
104 | 				if (contains(exports.lastSeen, term.name)) {
105 | 					topTerm.cache[term.name] = term.args;
106 | 				}
107 | 				// cache the last seen id equality
108 | 				if (term.name === 'eq' && term.args[0] === exports.primaryKeyName) {
109 | 					var id = term.args[1];
110 | 					if (id && !(id instanceof RegExp)) id = id.toString();
111 | 					topTerm.cache[exports.primaryKeyName] = id;
112 | 				}
113 | 			}
114 | 			return "";
115 | 		});
116 | 	if(term.parent){
117 | 		throw new URIError("Opening paranthesis without a closing paranthesis");
118 | 	}
119 | 	if(leftoverCharacters){
120 | 		// any extra characters left over from the replace indicates invalid syntax
121 | 		throw new URIError("Illegal character in query string encountered " + leftoverCharacters);
122 | 	}
123 | 
124 | 	function call(newTerm){
125 | 		term.args.push(newTerm);
126 | 		term = newTerm;
127 | 		// cache the last seen sort(), select(), values() and limit()
128 | 		if (contains(exports.lastSeen, term.name)) {
129 | 			topTerm.cache[term.name] = term.args;
130 | 		}
131 | 	}
132 | 	function setConjunction(operator){
133 | 		if(!term.name){
134 | 			term.name = operator;
135 | 		}
136 | 		else if(term.name !== operator){
137 | 			throw new Error("Can not mix conjunctions within a group, use paranthesis around each set of same conjuctions (& and |)");
138 | 		}
139 | 	}
140 | 	function removeParentProperty(obj) {
141 | 		if(obj && obj.args){
142 | 			delete obj.parent;
143 | 			var args = obj.args;
144 | 			for(var i = 0, l = args.length; i < l; i++){
145 | 				removeParentProperty(args[i]);
146 | 			}
147 | 		}
148 | 		return obj;
149 | 	};
150 | 	removeParentProperty(topTerm);
151 | 	if (!topTerm.name) {
152 | 		topTerm.name = topTermName;
153 | 	}
154 | 	return topTerm;
155 | };
156 | 
157 | exports.parse = exports.parseQuery = parse;
158 | 
159 | /* dumps undesirable exceptions to Query().error */
160 | exports.parseGently = function(){
161 | 	var terms;
162 | 	try {
163 | 		terms = parse.apply(this, arguments);
164 | 	} catch(err) {
165 | 		terms = new exports.Query();
166 | 		terms.error = err.message;
167 | 	}
168 | 	return terms;
169 | }
170 | 
171 | exports.commonOperatorMap = {
172 | 	"and" : "&",
173 | 	"or" : "|",
174 | 	"eq" : "=",
175 | 	"ne" : "!=",
176 | 	"le" : "<=",
177 | 	"ge" : ">=",
178 | 	"lt" : "<",
179 | 	"gt" : ">"
180 | }
181 | function stringToValue(string, parameters){
182 | 	var converter = exports.converters['default'];
183 | 	if(string.charAt(0) === "$"){
184 | 		var param_index = parseInt(string.substring(1)) - 1;
185 | 		return param_index >= 0 && parameters ? parameters[param_index] : undefined;
186 | 	}
187 | 	if(string.indexOf(":") > -1){
188 | 		var parts = string.split(":");
189 | 		converter = exports.converters[parts[0]];
190 | 		if(!converter){
191 | 			throw new URIError("Unknown converter " + parts[0]);
192 | 		}
193 | 		string = parts.slice(1).join(':');
194 | 	}
195 | 	return converter(string);
196 | };
197 | 
198 | var autoConverted = exports.autoConverted = {
199 | 	"true": true,
200 | 	"false": false,
201 | 	"null": null,
202 | 	"undefined": undefined,
203 | 	"Infinity": Infinity,
204 | 	"-Infinity": -Infinity
205 | };
206 | 
207 | exports.converters = {
208 | 	auto: function(string){
209 | 		if(autoConverted.hasOwnProperty(string)){
210 | 			return autoConverted[string];
211 | 		}
212 | 		var number = +string;
213 | 		if(isNaN(number) || number.toString() !== string){
214 |           /*var isoDate = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?Z$/.exec(x);
215 |           if (isoDate) {
216 |             date = new Date(Date.UTC(+isoDate[1], +isoDate[2] - 1, +isoDate[3], +isoDate[4], +isoDate[5], +isoDate[6], +isoDate[7] || 0));
217 |           }*/
218 | 			string = decodeURIComponent(string);
219 | 			if(exports.jsonQueryCompatible){
220 | 				if(string.charAt(0) == "'" && string.charAt(string.length-1) == "'"){
221 | 					return JSON.parse('"' + string.substring(1,string.length-1) + '"');
222 | 				}
223 | 			}
224 | 			return string;
225 | 		}
226 | 		return number;
227 | 	},
228 | 	number: function(x){
229 | 		var number = +x;
230 | 		if(isNaN(number)){
231 | 			throw new URIError("Invalid number " + number);
232 | 		}
233 | 		return number;
234 | 	},
235 | 	epoch: function(x){
236 | 		var date = new Date(+x);
237 | 		if (isNaN(date.getTime())) {
238 | 			throw new URIError("Invalid date " + x);
239 | 		}
240 | 		return date;
241 | 	},
242 | 	isodate: function(x){
243 | 		// four-digit year
244 | 		var date = '0000'.substr(0,4-x.length)+x;
245 | 		// pattern for partial dates
246 | 		date += '0000-01-01T00:00:00Z'.substring(date.length);
247 | 		return exports.converters.date(date);
248 | 	},
249 | 	date: function(x){
250 | 		var isoDate = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?Z$/.exec(x);
251 | 		var date;
252 | 		if (isoDate) {
253 | 			date = new Date(Date.UTC(+isoDate[1], +isoDate[2] - 1, +isoDate[3], +isoDate[4], +isoDate[5], +isoDate[6], +isoDate[7] || 0));
254 | 		}else{
255 | 			date = new Date(x);
256 | 		}
257 | 		if (isNaN(date.getTime())){
258 | 			throw new URIError("Invalid date " + x);
259 | 		}
260 | 		return date;
261 | 	},
262 | 	"boolean": function(x){
263 | 		return x === "true";
264 | 	},
265 | 	string: function(string){
266 | 		return decodeURIComponent(string);
267 | 	},
268 | 	re: function(x){
269 | 		return new RegExp(decodeURIComponent(x), 'i');
270 | 	},
271 | 	RE: function(x){
272 | 		return new RegExp(decodeURIComponent(x));
273 | 	},
274 | 	glob: function(x){
275 | 		var s = decodeURIComponent(x).replace(/([\\|\||\(|\)|\[|\{|\^|\$|\*|\+|\?|\.|\<|\>])/g, function(x){return '\\'+x;}).replace(/\\\*/g,'.*').replace(/\\\?/g,'.?');
276 | 		if (s.substring(0,2) !== '.*') s = '^'+s; else s = s.substring(2);
277 | 		if (s.substring(s.length-2) !== '.*') s = s+'$'; else s = s.substring(0, s.length-2);
278 | 		return new RegExp(s, 'i');
279 | 	}
280 | };
281 | 
282 | // exports.converters["default"] can be changed to a different converter if you want
283 | // a different default converter, for example:
284 | // RP = require("rql/parser");
285 | // RP.converters["default"] = RQ.converter.string;
286 | exports.converters["default"] = exports.converters.auto;
287 | 
288 | // this can get replaced by the chainable query if query.js is loaded
289 | exports.Query = function(){
290 | 	this.name = "and";
291 | 	this.args = [];
292 | };
293 | return exports;
294 | });
295 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | [![Build Status](https://travis-ci.org/persvr/rql.svg?branch=master)](https://travis-ci.org/persvr/rql)
  2 | 
  3 | Resource Query Language (RQL) is a query language designed for use in URIs with object
  4 | style data structures. This project includes the RQL specification and
  5 | provides a JavaScript implementation of query
  6 | parsing and query execution implementation for JavaScript arrays. The JavaScript library
  7 | supports AMD and NodeJS/CommonJS module format so it can be run in the browser or
  8 | in the server. RQL can be thought as basically a set of
  9 | nestable named operators which each have a set of arguments. RQL is designed to
 10 | have an extremely simple, but extensible grammar that can be written in a URL friendly query string. A simple RQL
 11 | query with a single operator that indicates a search for any resources with a property of
 12 | "foo" that has value of 3 could be written:
 13 | 
 14 |     eq(foo,3)
 15 | 
 16 | RQL is a compatible superset of standard HTML form URL encoding. The following query
 17 | is identical to the query (it is sugar for the query above):
 18 | 
 19 |     foo=3
 20 | 
 21 | Such that this can be used in URIs like:
 22 | 
 23 |     http://example.org/data?foo=3
 24 | 
 25 | # JavaScript Library
 26 | 
 27 | Using the JavaScript library we can construct queries
 28 | using chained operator calls in JavaScript. We could execute the query above like this:
 29 | 
 30 |     var Query = require("rql/query").Query;
 31 |     var fooEq3Query = new Query().eq("foo",3);
 32 | 
 33 | # RQL Rules
 34 | 
 35 | The RQL grammar is based around standard URI delimiters. The standard rules for
 36 | encoding strings with URL encoding (%xx) are observed. RQL also supersets FIQL.
 37 | Therefore we can write a query that finds resources with a "price" property below
 38 | 10 with a "lt" operator using FIQL syntax:
 39 | 
 40 |     price=lt=10
 41 | 
 42 | Which is identical (and sugar for call operator syntax known as the normalized form):
 43 | 
 44 |     lt(price,10)
 45 | 
 46 | One can combine conditions with multiple operators with "&":
 47 | 
 48 |     foo=3&price=lt=10
 49 | 
 50 | Is the same as:
 51 | 
 52 |     eq(foo,3)&lt(price,10)
 53 | 
 54 | Which is also the same as:
 55 | 
 56 |     and(eq(foo,3),lt(price,10))
 57 | 
 58 | We can execute a query against a JavaScript array:
 59 | 
 60 | 	require("rql/js-array").executeQuery("foo=3&price=lt=10", {}, data)...
 61 | 
 62 | The | operator can be used to indicate an "or" operation. We can also use paranthesis
 63 | to group expressions. For example:
 64 | 
 65 |     (foo=3|foo=bar)&price=lt=10
 66 | 
 67 | Which is the same as:
 68 | 
 69 |     and(or(eq(foo,3),eq(foo,bar)),lt(price,10))
 70 | 
 71 | Values in queries can be strings (using URL encoding), numbers, booleans, null, undefined,
 72 | and dates (in ISO UTC format without colon encoding). We can also denote arrays
 73 | with paranthesis enclosed, comma separated values. For example to find the objects
 74 | where foo can be the number 3, the string bar, the boolean true, or the date for the
 75 | first day of the century we could write an array with the "in" operator:
 76 | 
 77 |     foo=in=(3,bar,true,2000-01-01T00:00:00Z)
 78 | 
 79 | We can also explicitly specify primitive types in queries. To explicitly specify a string "3",
 80 | we can do:
 81 | 
 82 |     foo=string:3
 83 | 
 84 | Any property can be nested by using an array of properties. To search by the bar property of
 85 | the object in the foo property we can do:
 86 | 
 87 |     (foo,bar)=3
 88 | 
 89 | We can also use slashes as shorthand for arrays, so we could equivalently write the nested
 90 | query:
 91 | 
 92 |     foo/bar=3
 93 | 
 94 | Another common operator is sort. We can use the sort operator to sort by a specified property.
 95 | To sort by foo in ascending order:
 96 | 
 97 | 	price=lt=10&sort(+foo)
 98 | 
 99 | We can also do multiple property sorts. To sort by price in ascending order and rating in descending order:
100 | 
101 |     sort(+price,-rating)
102 | 
103 | The aggregate function can be used for aggregation. To calculate the sum of sales for
104 | each department:
105 | 
106 |     aggregate(departmentId,sum(sales))
107 | 
108 | Here is a definition of the common operators (individual stores may have support
109 | for more less operators):
110 | 
111 | * sort(&lt;+|->&lt;property) - Sorts by the given property in order specified by the prefix (+ for ascending, - for descending)
112 | * select(&lt;property>,&lt;property>,...) - Trims each object down to the set of properties defined in the arguments
113 | * values(&lt;property>) - Returns an array of the given property value for each object
114 | * aggregate(&lt;property|function>,...) - Aggregates the array, grouping by objects that are distinct for the provided properties, and then reduces the remaining other property values using the provided functions
115 | * distinct() - Returns a result set with duplicates removed
116 | * in(&lt;property>,&lt;array-of-values>) - Filters for objects where the specified property's value is in the provided array
117 | * out(&lt;property>,&lt;array-of-values>) - Filters for objects where the specified property's value is not in the provided array
118 | * contains(&lt;property>,&lt;value | expression>) - Filters for objects where the specified property's value is an array and the array contains any value that equals the provided value or satisfies the provided expression.
119 | * excludes(&lt;property>,&lt;value | expression>) - Filters for objects where the specified property's value is an array and the array does not contain any of value that equals the provided value or satisfies the provided expression.
120 | * limit(count,start,maxCount) - Returns the given range of objects from the result set
121 | * and(&lt;query>,&lt;query>,...) - Applies all the given queries
122 | * or(&lt;query>,&lt;query>,...) - The union of the given queries
123 | * eq(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is equal to the provided value
124 | * lt(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is less than the provided value
125 | * le(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is less than or equal to the provided value
126 | * gt(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is greater than the provided value
127 | * ge(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is greater than or equal to the provided value
128 | * ne(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is not equal to the provided value
129 | * rel(&lt;relation name?>,&lt;query>) - Applies the provided query against the linked data of the provided relation name.
130 | * sum(&lt;property?>) - Finds the sum of every value in the array or if the property argument is provided, returns the sum of the value of property for every object in the array
131 | * mean(&lt;property?>) - Finds the mean of every value in the array or if the property argument is provided, returns the mean of the value of property for every object in the array
132 | * max(&lt;property?>) - Finds the maximum of every value in the array or if the property argument is provided, returns the maximum of the value of property for every object in the array
133 | * min(&lt;property?>) - Finds the minimum of every value in the array or if the property argument is provided, returns the minimum of the value of property for every object in the array
134 | * recurse(&lt;property?>) - Recursively searches, looking in children of the object as objects in arrays in the given property value
135 | * first() - Returns the first record of the query's result set
136 | * one() - Returns the first and only record of the query's result set, or produces an error if the query's result set has more or less than one record in it.
137 | * count() - Returns the count of the number of records in the query's result set
138 | 
139 | # JavaScript Modules
140 | 
141 | ## rql/query
142 | 
143 |     var newQuery = require("rql/query").Query();
144 | 
145 | This module allows us to construct queries. With the query object, we could execute
146 | RQL operators as methods against the query object. For example:
147 | 
148 |     var Query = require("rql/query").Query;
149 |     var fooBetween3And10Query = new Query().lt("foo",3).gt("foo",10);
150 | 
151 | ## rql/parser
152 | 
153 | 	var parsedQueryObject = require("rql/parser").parseQuery(rqlString);
154 | 
155 | If you are writing an implementation of RQL for a database or other storage endpoint, or want to introspect queries, you can use the parsed query data
156 | structures. You can parse string queries with parser module's parseQuery function.
157 | Query objects have a "name" property and an "args" with an array of the arguments.
158 | For example:
159 | 
160 | 	require("rql/parser").parseQuery("(foo=3|foo=bar)&price=lt=10") ->
161 | 	{
162 | 		name: "and",
163 | 		args: [
164 | 			{
165 | 				name:"or",
166 | 				args:[
167 | 					{
168 | 						name:"eq",
169 | 						args:["foo",3]
170 | 					},
171 | 					{
172 | 						name:"eq",
173 | 						args:["foo","bar"]
174 | 					}
175 | 				]
176 | 			},
177 | 			{
178 | 				name:"lt",
179 | 				args:["price",10]
180 | 			}
181 | 		]
182 | 	}
183 | 
184 | Installation
185 | ========
186 | 
187 | RQL can be installed using any standard package manager, for example with NPM:
188 | 
189 |     npm install rql
190 | 
191 | or CPM:
192 | 
193 |     cpm install rql
194 | 
195 | or RingoJS:
196 | 
197 |     ringo-admin install persvr/rql
198 | 
199 | 
200 | Licensing
201 | --------
202 | 
203 | The RQL implementation is part of the Persevere project, and therefore is licensed under the
204 | AFL or BSD license. The Persevere project is administered under the Dojo foundation,
205 | and all contributions require a Dojo CLA.
206 | 
207 | Project Links
208 | ------------
209 | 
210 | See the main Persevere project for more information:
211 | 
212 | ### Homepage:
213 | 
214 | * [http://persvr.org/](http://persvr.org/)
215 | 
216 | ### Mailing list:
217 | 
218 | * [http://groups.google.com/group/json-query](http://groups.google.com/group/json-query)
219 | 
220 | ### IRC:
221 | 
222 | * [\#persevere on irc.freenode.net](http://webchat.freenode.net/?channels=persevere)
223 | 


--------------------------------------------------------------------------------
/test/query.js:
--------------------------------------------------------------------------------
  1 | define(function (require) {
  2 | 	var test = require('intern!object'),
  3 | 		assert = require('intern/chai!assert'),
  4 | 		Query = require('../query').Query,
  5 | 		parseQuery = require('../parser').parseQuery,
  6 | 		JSON = require('intern/dojo/json'),
  7 | 		supportsDateString = !isNaN(new Date('2009')),
  8 | 		queryPairs = {
  9 | 			arrays: {
 10 | 				a: { name: 'and', args: [ 'a' ]},
 11 | 				'(a)': { name: 'and', args: [[ 'a' ]]},
 12 | 				'a,b,c': { name: 'and', args: [ 'a', 'b', 'c' ]},
 13 | 				'(a,b,c)': { name: 'and', args: [[ 'a', 'b', 'c']]},
 14 | 				'a(b)': { name: 'and', args: [{ name: 'a', args: [ 'b' ]}]},
 15 | 				'a(b,c)': { name: 'and', args: [{ name: 'a', args: [ 'b', 'c' ]}]},
 16 | 				'a((b),c)': { name: 'and', args: [{ name: 'a', args: [ [ 'b' ], 'c' ]}]},
 17 | 				'a((b,c),d)': { name: 'and', args: [{ name: 'a', args: [ [ 'b', 'c' ], 'd' ]}]},
 18 | 				'a(b/c,d)': { name: 'and', args: [{ name: 'a', args: [ [ 'b', 'c' ], 'd' ]}]},
 19 | 				'a(b)&c(d(e))': { name: 'and', args:[
 20 | 					{ name: 'a', args: [ 'b' ]},
 21 | 					{ name: 'c', args: [ { name: 'd', args: [ 'e' ]} ]}
 22 | 				]}
 23 | 			},
 24 | 			'dot-comparison': {
 25 | 				'foo.bar=3': { name: 'and', args: [{ name: 'eq', args: [ 'foo.bar', 3 ]}]},
 26 | 				'select(sub.name)': {
 27 | 					name: 'and',
 28 | 					args: [ { name: 'select', args: [ 'sub.name' ]} ],
 29 | 					cache: { select: [ 'sub.name' ]}
 30 | 				}
 31 | 			},
 32 | 			equality: {
 33 | 				'eq(a,b)': { name: 'and', args:[{ name: 'eq', args: [ 'a', 'b' ]}]},
 34 | 				'a=eq=b': 'eq(a,b)',
 35 | 				'a=b': 'eq(a,b)'
 36 | 			},
 37 | 			inequality: {
 38 | 				'ne(a,b)': { name: 'and', args: [{ name: 'ne', args: [ 'a', 'b' ]}]},
 39 | 				'a=ne=b': 'ne(a,b)',
 40 | 				'a!=b': 'ne(a,b)'
 41 | 			},
 42 | 			'less-than': {
 43 | 				'lt(a,b)': { name: 'and', args: [{ name: 'lt', args: [ 'a', 'b' ]}]},
 44 | 				'a=lt=b': 'lt(a,b)',
 45 | 				'a<b': 'lt(a,b)'
 46 | 			},
 47 | 			'less-than-equals': {
 48 | 				'le(a,b)': { name: 'and', args: [{ name: 'le', args: [ 'a','b' ]}]},
 49 | 				'a=le=b': 'le(a,b)',
 50 | 				'a<=b': 'le(a,b)'
 51 | 			},
 52 | 			'greater-than': {
 53 | 				'gt(a,b)': { name: 'and', args: [{ name: 'gt', args: [ 'a', 'b' ]}]},
 54 | 				'a=gt=b': 'gt(a,b)',
 55 | 				'a>b': 'gt(a,b)'
 56 | 			},
 57 | 			'greater-than-equals': {
 58 | 				'ge(a,b)': { name: 'and', args: [{ name: 'ge', args: [ 'a', 'b' ]}]},
 59 | 				'a=ge=b': 'ge(a,b)',
 60 | 				'a>=b': 'ge(a,b)'
 61 | 			},
 62 | 			'nested comparisons': {
 63 | 				'a(b(le(c,d)))': { name: 'and', args: [
 64 | 					{ name: 'a', args: [{ name: 'b', args: [{ name: 'le', args: [ 'c', 'd' ]}]}]}
 65 | 				]},
 66 | 				'a(b(c=le=d))': 'a(b(le(c,d)))',
 67 | 				'a(b(c<=d))': 'a(b(le(c,d)))'
 68 | 			},
 69 | 			'arbitrary FIQL desugaring': {
 70 | 				'a=b=c': { name: 'and', args: [{ name: 'b', args: [ 'a', 'c' ]}]},
 71 | 				'a(b=cd=e)': { name: 'and', args: [{ name: 'a', args: [{ name: 'cd', args: [ 'b', 'e' ]}]}]}
 72 | 			},
 73 | 			'and grouping': {
 74 | 				'a&b&c': { name: 'and', args: [ 'a', 'b', 'c' ]},
 75 | 				'a(b)&c': { name: 'and', args: [ { name: 'a', args: [ 'b' ] }, 'c' ]},
 76 | 				'a&(b&c)': { name: 'and', args: [ 'a', { name: 'and', args: [ 'b', 'c' ]}]}
 77 | 			},
 78 | 			'or grouping': {
 79 | 				'(a|b|c)': { name: 'and', args: [{ name: 'or', args: [ 'a', 'b', 'c' ]}]},
 80 | 				'(a(b)|c)': { name: 'and', args: [{ name: 'or', args: [ { name: 'a', args: [ 'b' ]}, 'c' ]}]}
 81 | 			},
 82 | 			'complex grouping': {
 83 | 				'a&(b|c)': { name: 'and', args: [ 'a', { name: 'or', args: [ 'b', 'c' ]}]},
 84 | 				'a|(b&c)': { name: 'or', args: [ 'a', { name: 'and', args: [ 'b', 'c' ]}]},
 85 | 				'a(b(c<d,e(f=g)))': { 'name': 'and', 'args': [{ 'name': 'a', 'args': [{ 'name': 'b', 'args': [{ 'name': 'lt', 'args': ['c', 'd']}, {'name':'e', 'args': [{ 'name': 'eq', 'args': [ 'f', 'g' ]}]}]}]}]}
 86 | 			},
 87 | 			'complex comparisons': {
 88 | 
 89 | 			},
 90 | 			'string coercion': {
 91 | 				'a(string)': { name: 'and', args: [{ name: 'a', args: [ 'string' ]}]},
 92 | 				'a(string:b)': { name: 'and', args: [{ name: 'a', args: [ 'b' ]}]},
 93 | 				'a(string:1)': { name: 'and', args: [{ name: 'a', args: [ '1' ]}]}
 94 | 			},
 95 | 			'number coercion': {
 96 | 				'a(number)': { name: 'and', args: [{ name: 'a', args: [ 'number' ]}]},
 97 | 				'a(number:1)': {name: 'and', args: [{ name: 'a', args: [ 1 ]}]}
 98 | 				//'a(number:b)': { name: 'and', args: [{ name: 'a', args: [ NaN ]}]} // supposed to throw an error
 99 | 			},
100 | 			'date coercion': {
101 | 				//FIXME do we need proper ISO date subset parsing?
102 | 				'a(date)': { name: 'and', args: [{ name: 'a', args: [ 'date' ]}]},
103 | 				'a(date:2009)': supportsDateString && { name: 'and', args: [{ name: 'a', args: [ new Date('2009') ]}]},
104 | 				'a(date:2009-01-01T10:00:00Z)': { name: 'and', args: [{ name: 'a', args: [ new Date(Date.UTC(2009, 0, 1, 10)) ]}]},
105 | 				'a(date:1989-11-21)': {name: 'and', args:[{name: 'a', args: [(new Date('1989-11-21'))]}]},
106 | 				'a(date:1989-11-21T00:21:00.21Z)': {name: 'and', args:[{name: 'a', args: [(new Date(Date.UTC(1989, 10, 21, 0, 21, 0, 21)))]}]},
107 | 				'a(date:1989-11-21T00:21:00Z)': {name: 'and', args:[{name: 'a', args: [(new Date(Date.UTC(1989, 10, 21, 0, 21, 0)))]}]}
108 | 				//'a(date:b)': { name: 'and', args: [{ name: 'a', args: [ new Date(NaN) ]}]} // XXX?// supposed to throw an error
109 | 			},
110 | 			'boolean coercion': {
111 | 				'a(true)': { name: 'and', args: [{ name: 'a', args: [ true ]}]},
112 | 				'a(false)': { name: 'and', args: [{ name: 'a', args: [ false ]}]},
113 | 				'a(boolean:true)': { name: 'and', args: [{ name: 'a', args: [ true ]}]}
114 | 			},
115 | 			'null coercion': {
116 | 				'a(null)': { name: 'and', args: [{ name: 'a', args: [ null ]}]},
117 | 				'a(auto:null)': { name: 'and', args: [{ name: 'a', args: [ null ]}]},
118 | 				'a(string:null)': { name: 'and', args: [{ name: 'a', args: [ 'null' ]}]}
119 | 			},
120 | 			'complex coercion': {
121 | 				'(a=b|c=d)&(e=f|g=1)': { name: 'and', args: [
122 | 					{ name: 'or', args: [{ name: 'eq', args: [ 'a', 'b' ]}, { name: 'eq', args: [ 'c', 'd' ]}]},
123 | 					{ name: 'or', args: [{ name: 'eq', args: [ 'e', 'f' ]}, { name: 'eq', args: [ 'g', 1 ]}]}
124 | 				]}
125 | 			}
126 | 		},
127 | 		testParsing = (function () {
128 | 			var tests = {},
129 | 				test,
130 | 				group,
131 | 				pairs,
132 | 				key;
133 | 
134 | 			for (group in queryPairs) {
135 | 				tests[ group ] = test = {};
136 | 				pairs = queryPairs [ group ];
137 | 				for (key in pairs) {
138 | 					// Wrap the test function in another function call so
139 | 					// that the keys and pairs objects are correctly bound
140 | 					var f = function (k, p) {
141 | 						return function () {
142 | 							// skip tests which don't have an expected value
143 | 							if (!p[ k ]) {
144 | 								return this.skip();
145 | 							}
146 | 
147 | 							var actual = parseQuery(k),
148 | 								expected = p[ k ];
149 | 
150 | 							if (!hasKeys(actual.cache)) {
151 | 								delete actual.cache;
152 | 							}
153 | 
154 | 							if (typeof expected === 'string') {
155 | 								expected = parseQuery(expected);
156 | 							}
157 | 
158 | 							if (!hasKeys(expected.cache)) {
159 | 								delete expected.cache;
160 | 							}
161 | 
162 | 							// someone decided that matching constructors is necessary for deep equality
163 | 							// see https://github.com/theintern/intern/issues/284
164 | 							// the deepEqual assertion also fails due to properties like toString so this assertion seems to
165 | 							// be the most suitable.
166 | 							assert.strictEqual(JSON.stringify(actual), JSON.stringify(expected));
167 | 						};
168 | 					};
169 | 					test[ key ] = f(key, pairs);
170 | 				}
171 | 			}
172 | 
173 | 			return tests;
174 | 		})();
175 | 
176 | 	function hasKeys(it) {
177 | 		var key;
178 | 
179 | 		if (it == null || typeof it !== 'object') {
180 | 			return false;
181 | 		}
182 | 
183 | 		for (key in it) {
184 | 			if (it.hasOwnProperty(key)) {
185 | 				return true;
186 | 			}
187 | 		}
188 | 		return false;
189 | 	}
190 | 
191 | 	test({
192 | 		name: 'rql/test/query',
193 | 
194 | 		testBehavior: function () {
195 | 			//assert.error(parseQuery(), "parseQuery requires a string");
196 | 			assert.ok(parseQuery('') instanceof Query, 'should inherit from Query');
197 | 			assert.ok(parseQuery('a=b') instanceof Query, 'should inherit from Query');
198 | 			//assert.error(parseQuery('?a=b'), 'cannot begin with a ?');
199 | 		},
200 | 
201 | 		testParsing: testParsing,
202 | 
203 | 		testBindParameters: function () {
204 | 			// TODO
205 | 			var parsed;
206 | 			parsed = parseQuery('in(id,$1)', [['a','b','c']]);
207 | 			assert.strictEqual(JSON.stringify(parsed), JSON.stringify({
208 | 				name: 'and',
209 | 				args: [{ name: 'in', args: [ 'id', [ 'a', 'b', 'c' ]]}],
210 | 				cache: {}
211 | 			}));
212 | 			parsed = parseQuery('eq(id,$1)', [ 'a' ]);
213 | 			assert.deepEqual(JSON.stringify(parsed), JSON.stringify({
214 | 				name: 'and',
215 | 				args: [{ name: 'eq', args: ['id', 'a']}],
216 | 				cache: {id: 'a'}
217 | 			}));
218 | 		},
219 | 
220 | 		testStringification: function () {
221 | 			// TODO
222 | 			var parsed;
223 | 			parsed = parseQuery('eq(id1,RE:%5Eabc%5C%2F)');
224 | 			// Hmmm. deepEqual gives null for regexps?
225 | 			assert.ok(parsed.args[0].args[1].toString() === /^abc\//.toString());
226 | 			//assert.deepEqual(parsed, {name: 'and', args: [{name: 'eq', args: ['id1', /^abc\//]}]});
227 | 			assert.ok(new Query().eq('_1',/GGG(EE|FF)/i) + '' === 'eq(_1,re:GGG%28EE%7CFF%29)');
228 | 			parsed = parseQuery('eq(_1,re:GGG%28EE%7CFF%29)');
229 | 			console.log(parsed.args[0].args[1].toString() === /GGG(EE|FF)/i.toString());
230 | 			//assert.ok(Query().eq('_1',/GGG(EE|FF)/)+'' === 'eq(_1,RE:GGG%28EE%7CFF%29)');
231 | 			// string to array and back
232 | 			var str = 'somefunc(and(1),(a,b),(10,(10,1)),(a,b.c))';
233 | 			assert.equal(parseQuery(str) + '', str);
234 | 			// quirky arguments
235 | 			var name = ['a/b','c.d'];
236 | 			assert.equal(parseQuery(new Query().eq(name,1) + '') + '', 'eq((a%2Fb,c.d),1)');
237 | 			assert.deepEqual(parseQuery(new Query().eq(name,1) + '').args[0].args[0], name);
238 | 		},
239 | 
240 | 		testMatches: function () {
241 | 			var query = new Query().match('name', /Will*/);
242 | 			assert.equal('' + query, 'match(name,RE:Will*)');
243 | 		}
244 | 	});
245 | });


--------------------------------------------------------------------------------
/js-array.js:
--------------------------------------------------------------------------------
  1 | /*
  2 |  * An implementation of RQL for JavaScript arrays. For example:
  3 |  * require("./js-array").query("a=3", {}, [{a:1},{a:3}]) -> [{a:3}]
  4 |  *
  5 |  */
  6 | 
  7 | ({define:typeof define!="undefined"?define:function(deps, factory){module.exports = factory(exports, require("./parser"), require("./query"), require("./util/each"), require("./util/contains"));}}).
  8 | define(["exports", "./parser", "./query", "./util/each", "./util/contains"], function(exports, parser, QUERY, each, contains){
  9 | //({define:typeof define!="undefined"?define:function(deps, factory){module.exports = factory(exports, require("./parser"));}}).
 10 | //define(["exports", "./parser"], function(exports, parser){
 11 | 
 12 | var parseQuery = parser.parseQuery;
 13 | var stringify = typeof JSON !== "undefined" && JSON.stringify || function(str){
 14 | 	return '"' + str.replace(/"/g, "\\\"") + '"';
 15 | };
 16 | var nextId = 1;
 17 | exports.jsOperatorMap = {
 18 | 	"eq" : "===",
 19 | 	"ne" : "!==",
 20 | 	"le" : "<=",
 21 | 	"ge" : ">=",
 22 | 	"lt" : "<",
 23 | 	"gt" : ">"
 24 | };
 25 | exports.operators = {
 26 | 	sort: function(){
 27 | 		var terms = [];
 28 | 		for(var i = 0; i < arguments.length; i++){
 29 | 			var sortAttribute = arguments[i];
 30 | 			var firstChar = sortAttribute.charAt(0);
 31 | 			var term = {attribute: sortAttribute, ascending: true};
 32 | 			if (firstChar == "-" || firstChar == "+") {
 33 | 				if(firstChar == "-"){
 34 | 					term.ascending = false;
 35 | 				}
 36 | 				term.attribute = term.attribute.substring(1);
 37 | 			}
 38 | 			terms.push(term);
 39 | 		}
 40 | 		this.sort(function(a, b){
 41 | 			for (var term, i = 0; term = terms[i]; i++) {
 42 | 				if (a[term.attribute] != b[term.attribute]) {
 43 | 					return term.ascending == a[term.attribute] > b[term.attribute] ? 1 : -1;
 44 | 				}
 45 | 			}
 46 | 			return 0;
 47 | 		});
 48 | 		return this;
 49 | 	},
 50 | 	match: filter(function(value, regex){
 51 | 		return new RegExp(regex).test(value);
 52 | 	}),
 53 | 	"in": filter(function(value, values){
 54 | 		return contains(values, value);
 55 | 	}),
 56 | 	out: filter(function(value, values){
 57 | 		return !contains(values, value);
 58 | 	}),
 59 | 	contains: filter(function(array, value){
 60 | 		if(typeof value == "function"){
 61 | 			return array instanceof Array && each(array, function(v){
 62 | 				return value.call([v]).length;
 63 | 			});
 64 | 		}
 65 | 		else{
 66 | 			return array instanceof Array && contains(array, value);
 67 | 		}
 68 | 	}),
 69 | 	excludes: filter(function(array, value){
 70 | 		if(typeof value == "function"){
 71 | 			return !each(array, function(v){
 72 | 				return value.call([v]).length;
 73 | 			});
 74 | 		}
 75 | 		else{
 76 | 			return !contains(array, value);
 77 | 		}
 78 | 	}),
 79 | 	or: function(){
 80 | 		var items = [];
 81 | 		var idProperty = "__rqlId" + nextId++;
 82 | 		try{
 83 | 			for(var i = 0; i < arguments.length; i++){
 84 | 				var group = arguments[i].call(this);
 85 | 				for(var j = 0, l = group.length;j < l;j++){
 86 | 					var item = group[j];
 87 | 					// use marker to do a union in linear time.
 88 | 					if(!item[idProperty]){
 89 | 						item[idProperty] = true;
 90 | 						items.push(item);
 91 | 					}
 92 | 				}
 93 | 			}
 94 | 		}finally{
 95 | 			// cleanup markers
 96 | 			for(var i = 0, l = items.length; i < l; i++){
 97 | 				delete items[idProperty];
 98 | 			}
 99 | 		}
100 | 		return items;
101 | 	},
102 | 	and: function(){
103 | 		var items = this;
104 | 		// TODO: use condition property
105 | 		for(var i = 0; i < arguments.length; i++){
106 | 			items = arguments[i].call(items);
107 | 		}
108 | 		return items;
109 | 	},
110 | 	select: function(){
111 | 		var args = arguments;
112 | 		var argc = arguments.length;
113 | 		return each(this, function(object, emit){
114 | 			var selected = {};
115 | 			for(var i = 0; i < argc; i++){
116 | 				var propertyName = args[i];
117 | 				var value = evaluateProperty(object, propertyName);
118 | 				if(typeof value != "undefined"){
119 | 					selected[propertyName] = value;
120 | 				}
121 | 			}
122 | 			emit(selected);
123 | 		});
124 | 	},
125 | 	unselect: function(){
126 | 		var args = arguments;
127 | 		var argc = arguments.length;
128 | 		return each(this, function(object, emit){
129 | 			var selected = {};
130 | 			for (var i in object) if (object.hasOwnProperty(i)) {
131 | 				selected[i] = object[i];
132 | 			}
133 | 			for(var i = 0; i < argc; i++) {
134 | 				delete selected[args[i]];
135 | 			}
136 | 			emit(selected);
137 | 		});
138 | 	},
139 | 	values: function(first){
140 | 		if(arguments.length == 1){
141 | 			return each(this, function(object, emit){
142 | 				emit(object[first]);
143 | 			});
144 | 		}
145 | 		var args = arguments;
146 | 		var argc = arguments.length;
147 | 		return each(this, function(object, emit){
148 | 			var selected = [];
149 | 			if (argc === 0) {
150 | 				for(var i in object) if (object.hasOwnProperty(i)) {
151 | 					selected.push(object[i]);
152 | 				}
153 | 			} else {
154 | 				for(var i = 0; i < argc; i++){
155 | 					var propertyName = args[i];
156 | 					selected.push(object[propertyName]);
157 | 				}
158 | 			}
159 | 			emit(selected);
160 | 		});
161 | 	},
162 | 	limit: function(limit, start, maxCount){
163 | 		var totalCount = this.length;
164 | 		start = start || 0;
165 | 		var sliced = this.slice(start, start + limit);
166 | 		if(maxCount){
167 | 			sliced.start = start;
168 | 			sliced.end = start + sliced.length - 1;
169 | 			sliced.totalCount = Math.min(totalCount, typeof maxCount === "number" ? maxCount : Infinity);
170 | 		}
171 | 		return sliced;
172 | 	},
173 | 	distinct: function(){
174 | 		var primitives = {};
175 | 		var needCleaning = [];
176 | 		var newResults = this.filter(function(value){
177 | 			if(value && typeof value == "object"){
178 | 				if(!value.__found__){
179 | 					value.__found__ = function(){};// get ignored by JSON serialization
180 | 					needCleaning.push(value);
181 | 					return true;
182 | 				}
183 | 			}else{
184 | 				if(!primitives[value]){
185 | 					primitives[value] = true;
186 | 					return true;
187 | 				}
188 | 			}
189 | 		});
190 | 		each(needCleaning, function(object){
191 | 			delete object.__found__;
192 | 		});
193 | 		return newResults;
194 | 	},
195 | 	recurse: function(property){
196 | 		// TODO: this needs to use lazy-array
197 | 		var newResults = [];
198 | 		function recurse(value){
199 | 			if(value instanceof Array){
200 | 				each(value, recurse);
201 | 			}else{
202 | 				newResults.push(value);
203 | 				if(property){
204 | 					value = value[property];
205 | 					if(value && typeof value == "object"){
206 | 						recurse(value);
207 | 					}
208 | 				}else{
209 | 					for(var i in value){
210 | 						if(value[i] && typeof value[i] == "object"){
211 | 							recurse(value[i]);
212 | 						}
213 | 					}
214 | 				}
215 | 			}
216 | 		}
217 | 		recurse(this);
218 | 		return newResults;
219 | 	},
220 | 	aggregate: function(){
221 | 		var distinctives = [];
222 | 		var aggregates = [];
223 | 		for(var i = 0; i < arguments.length; i++){
224 | 			var arg = arguments[i];
225 | 			if(typeof arg === "function"){
226 | 				 aggregates.push(arg);
227 | 			}else{
228 | 				distinctives.push(arg);
229 | 			}
230 | 		}
231 | 		var distinctObjects = {};
232 | 		var dl = distinctives.length;
233 | 		each(this, function(object){
234 | 			var key = "";
235 | 			for(var i = 0; i < dl;i++){
236 | 				key += '/' + object[distinctives[i]];
237 | 			}
238 | 			var arrayForKey = distinctObjects[key];
239 | 			if(!arrayForKey){
240 | 				arrayForKey = distinctObjects[key] = [];
241 | 			}
242 | 			arrayForKey.push(object);
243 | 		});
244 | 		var al = aggregates.length;
245 | 		var newResults = [];
246 | 		for(var key in distinctObjects){
247 | 			var arrayForKey = distinctObjects[key];
248 | 			var newObject = {};
249 | 			for(var i = 0; i < dl;i++){
250 | 				var property = distinctives[i];
251 | 				newObject[property] = arrayForKey[0][property];
252 | 			}
253 | 			for(var i = 0; i < al;i++){
254 | 				var aggregate = aggregates[i];
255 | 				newObject[i] = aggregate.call(arrayForKey);
256 | 			}
257 | 			newResults.push(newObject);
258 | 		}
259 | 		return newResults;
260 | 	},
261 | 	between: filter(function(value, range){
262 | 		return value >= range[0] && value < range[1];
263 | 	}),
264 | 	sum: reducer(function(a, b){
265 | 		return a + b;
266 | 	}),
267 | 	mean: function(property){
268 | 		return exports.operators.sum.call(this, property)/this.length;
269 | 	},
270 | 	max: reducer(function(a, b){
271 | 		return Math.max(a, b);
272 | 	}),
273 | 	min: reducer(function(a, b){
274 | 		return Math.min(a, b);
275 | 	}),
276 | 	count: function(){
277 | 		return this.length;
278 | 	},
279 | 	first: function(){
280 | 		return this[0];
281 | 	},
282 | 	one: function(){
283 | 		if(this.length > 1){
284 | 			throw new TypeError("More than one object found");
285 | 		}
286 | 		return this[0];
287 | 	}
288 | };
289 | exports.filter = filter;
290 | function filter(condition, not){
291 | 	// convert to boolean right now
292 | 	var filter = function(property, second){
293 | 		if(typeof second == "undefined"){
294 | 			second = property;
295 | 			property = undefined;
296 | 		}
297 | 		var args = arguments;
298 | 		var filtered = [];
299 | 		for(var i = 0, length = this.length; i < length; i++){
300 | 			var item = this[i];
301 | 			if(condition(evaluateProperty(item, property), second)){
302 | 				filtered.push(item);
303 | 			}
304 | 		}
305 | 		return filtered;
306 | 	};
307 | 	filter.condition = condition;
308 | 	return filter;
309 | };
310 | function reducer(func){
311 | 	return function(property){
312 | 		var result = this[0];
313 | 		if(property){
314 | 			result = result && result[property];
315 | 			for(var i = 1, l = this.length; i < l; i++) {
316 | 				result = func(result, this[i][property]);
317 | 			}
318 | 		}else{
319 | 			for(var i = 1, l = this.length; i < l; i++) {
320 | 				result = func(result, this[i]);
321 | 			}
322 | 		}
323 | 		return resul;t
324 | 	}
325 | }
326 | exports.evaluateProperty = evaluateProperty;
327 | function evaluateProperty(object, property){
328 | 	if(property instanceof Array){
329 | 		each(property, function(part){
330 | 			object = object[decodeURIComponent(part)];
331 | 		});
332 | 		return object;
333 | 	}else if(typeof property == "undefined"){
334 | 		return object;
335 | 	}else{
336 | 		return object[decodeURIComponent(property)];
337 | 	}
338 | };
339 | var conditionEvaluator = exports.conditionEvaluator = function(condition){
340 | 	var jsOperator = exports.jsOperatorMap[term.name];
341 | 	if(jsOperator){
342 | 		js += "(function(item){return item." + term[0] + jsOperator + "parameters[" + (index -1) + "][1];});";
343 | 	}
344 | 	else{
345 | 		js += "operators['" + term.name + "']";
346 | 	}
347 | 	return eval(js);
348 | };
349 | exports.executeQuery = function(query, options, target){
350 | 	return exports.query(query, options, target);
351 | }
352 | exports.query = query;
353 | exports.missingOperator = function(operator){
354 | 	throw new Error("Operator " + operator + " is not defined");
355 | }
356 | function query(query, options, target){
357 | 	options = options || {};
358 | 	query = parseQuery(query, options.parameters);
359 | 	function t(){}
360 | 	t.prototype = exports.operators;
361 | 	var operators = new t;
362 | 	// inherit from exports.operators
363 | 	for(var i in options.operators){
364 | 		operators[i] = options.operators[i];
365 | 	}
366 | 	function op(name){
367 | 		return operators[name]||exports.missingOperator(name);
368 | 	}
369 | 	var parameters = options.parameters || [];
370 | 	var js = "";
371 | 	function queryToJS(value){
372 | 		if(value && typeof value === "object" && !(value instanceof RegExp)){
373 | 			if(value instanceof Array){
374 | 				return '[' + each(value, function(value, emit){
375 | 					emit(queryToJS(value));
376 | 				}) + ']';
377 | 			}else{
378 | 				var jsOperator = exports.jsOperatorMap[value.name];
379 | 				if(jsOperator){
380 | 					// item['foo.bar'] ==> (item && item.foo && item.foo.bar && ...)
381 | 					var path = value.args[0];
382 | 					var target = value.args[1];
383 | 					if (typeof target == "undefined"){
384 | 						var item = "item";
385 | 						target = path;
386 | 					}else if(path instanceof Array){
387 | 						var item = "item";
388 | 						var escaped = [];
389 | 						for(var i = 0;i < path.length; i++){
390 | 							escaped.push(stringify(path[i]));
391 | 							item +="&&item[" + escaped.join("][") + ']';
392 | 						}
393 | 					}else{
394 | 						var item = "item&&item[" + stringify(path) + "]";
395 | 					}
396 | 					// use native Array.prototype.filter if available
397 | 					var condition = item + jsOperator + queryToJS(target);
398 | 					if (typeof Array.prototype.filter === 'function') {
399 | 						return "(function(){return this.filter(function(item){return " + condition + "})})";
400 | 						//???return "this.filter(function(item){return " + condition + "})";
401 | 					} else {
402 | 						return "(function(){var filtered = []; for(var i = 0, length = this.length; i < length; i++){var item = this[i];if(" + condition + "){filtered.push(item);}} return filtered;})";
403 | 					}
404 | 				}else{
405 | 					if (value instanceof Date){
406 | 						return value.valueOf();
407 | 					}
408 | 					return "(function(){return op('" + value.name + "').call(this" +
409 | 						(value && value.args && value.args.length > 0 ? (", " + each(value.args, function(value, emit){
410 | 								emit(queryToJS(value));
411 | 							}).join(",")) : "") +
412 | 						")})";
413 | 				}
414 | 			}
415 | 		}else{
416 | 			return typeof value === "string" ? stringify(value) : value;
417 | 		}
418 | 	}
419 | 	var evaluator = eval("(1&&function(target){return " + queryToJS(query) + ".call(target);})");
420 | 	return target ? evaluator(target) : evaluator;
421 | }
422 | function throwMaxIterations(){
423 | 	throw new Error("Query has taken too much computation, and the user is not allowed to execute resource-intense queries. Increase maxIterations in your config file to allow longer running non-indexed queries to be processed.");
424 | }
425 | exports.maxIterations = 10000;
426 | return exports;
427 | });
428 | 


--------------------------------------------------------------------------------
/specification/draft-zyp-rql-00.xml:
--------------------------------------------------------------------------------
  1 | <?xml version="1.0" encoding="US-ASCII"?>
  2 | <!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
  3 | <!ENTITY rfc2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
  4 | <!ENTITY rfc3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
  5 | <!ENTITY html401 SYSTEM "http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-html401-19991224.xml">
  6 | <!ENTITY fiql SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.nottingham-atompub-fiql.xml">
  7 | ]>
  8 | <?rfc toc="yes"?>
  9 | <?rfc symrefs="yes"?>
 10 | <?rfc compact="yes"?>
 11 | <?rfc subcompact="no"?>
 12 | <?rfc strict="no"?>
 13 | <?rfc rfcedstyle="yes"?>
 14 | <rfc category="info" docName="draft-zyp-rql-00" year="2010" ipr="trust200902">
 15 |   <front>
 16 |     
 17 | 
 18 |     <title abbrev="Resource Query Language">Resource Query Language</title>
 19 | 
 20 | 
 21 |     <author fullname="Kris Zyp" initials="K" role="editor"
 22 |             surname="Zyp">
 23 |       <organization>SitePen (USA)</organization>
 24 | 
 25 |       <address>
 26 |         <postal>
 27 |           <street>530 Lytton Avenue</street>
 28 | 
 29 |           <city>Palo Alto, CA 94301</city>
 30 | 
 31 |           <country>USA</country>
 32 |         </postal>
 33 | 
 34 |         <phone>+1 650 968 8787</phone>
 35 | 
 36 |         <email>kris@sitepen.com</email>
 37 |       </address>
 38 |     </author>
 39 | 
 40 |     <date year="2010" />
 41 | 
 42 |     <workgroup>Internet Engineering Task Force</workgroup>
 43 | 
 44 |     <keyword>resource</keyword>
 45 | 
 46 |     <keyword>query</keyword>
 47 | 
 48 |     <!--[TODO] add additional keywords here for IETF website search engine -->
 49 | 
 50 |     <abstract>
 51 |       <t>Resource Query Languages (RQL) defines a syntactically simple query language 
 52 |       for querying and retrieving resources. RQL is designed to be URI friendly, 
 53 |       particularly as a query component of a URI, and highly extensible. RQL is a superset
 54 |       of HTML's URL encoding of form values, and a superset of Feed Item Query Language (FIQL).
 55 |       RQL basically consists of a set of nestable named operators which each have a set of 
 56 |       arguments and operate on a collection of resources. An example of an RQL for finding
 57 |       resources with a category of "toy" and sorted by price in ascending order:
 58 |       <figure>
 59 |         <artwork>
 60 |         <![CDATA[	
 61 | category=toy&sort(+price)
 62 | ]]></artwork></figure>
 63 |       </t>
 64 | 
 65 |     </abstract>
 66 | 
 67 |   </front>
 68 | 
 69 |   <middle>
 70 |     <section title="Introduction">
 71 |       <t>Resource Query Languages (RQL) defines a syntactically simple query language 
 72 |       for querying and retrieving resources. RQL is designed to be URI friendly, 
 73 |       particularly as a query component of a URI, and highly extensible. RQL is a superset
 74 |       of HTML's URL encoding of form values, and a superset of Feed Item Query Language (FIQL).
 75 | </t>
 76 |     </section>
 77 | 
 78 | 
 79 |     <section title="Conventions">
 80 |       <t><!-- The text in this section has been copied from the official boilerplate, 
 81 |                   and should not be modified.-->The key words "MUST", "MUST
 82 |       NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
 83 |       "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
 84 |       interpreted as described in RFC 2119.</t>
 85 |     </section>
 86 | 
 87 |     <!-- ********************************************* -->
 88 | 
 89 |     <section title="Overview">
 90 |       <t>RQL consists of a set of nestable named operators which each have a set of 
 91 |       arguments. RQL is designed to be applied to a collection of resources. Each top-level 
 92 |       operator defines a constraint or modification to the result of the query from the base 
 93 |       collection of resources. Nested operators provide constraint information for the operators within which they are embedded. 
 94 |       </t>
 95 |     </section>
 96 |     <section title="Operators">
 97 |     <t>
 98 |       An operator consists of an operator name followed by a list of comma-delimited arguments within paranthesis:
 99 |       <figure>
100 |         <artwork>
101 |         <![CDATA[	
102 | name(args,...)
103 | ]]></artwork></figure>
104 |       Each argument may be a value (a string of unreserved or URL-encoded characters), an array, or another operator. The name of the operator indicates the type of action the operator will perform on the collection, using the given arguments. This document defines the semantics of a set of operators, but the query language can be extended with additional operators.</t>
105 | <t>      
106 |       A simple RQL query with a single operator that indicates a search for any 
107 |       resources with a property of "foo" that has value of 3 could be written:
108 |       <figure>
109 |         <artwork>
110 |         <![CDATA[	
111 | eq(foo,3)
112 | ]]></artwork></figure>
113 |       </t>
114 |     </section>
115 |     <section title="Values">
116 |       <t>
117 | 	Simple values are simply URL-encoded sequences of characters. Unreserved characters do not need to be encoded, other characters should be encoding using standard URL encoding. Simple values can be decoded to determine the intended string of characters. Values can also include arrays or typed values. These are described in the "Typed Values" and "Arrays" section below.
118 |       </t>
119 |     </section>
120 |     <section title="Arrays">
121 |       
122 |       <t>
123 |       One of the allowable arguments for operators is an array. An array is paranthesis-enclosed comma-delimited set of items. Each item in the array can be a value or an operator. A query that finds all the resources where the category can be "toy" or "food" could be written with an array argument:
124 |       <figure>
125 |         <artwork>
126 |         <![CDATA[	
127 | in(category,(toy,food))
128 | ]]></artwork></figure>
129 |       
130 |       </t>
131 |     </section>
132 |     <section title="Nested Operators">
133 |       <t>
134 |       Operators may be nested. For example, a set of operators can be used as the arguments for the "or" operator. Another query that finds all the resources where the category can be "toy" or "food" could be written with nested "eq" operators within an "or" operator:
135 |       <figure>
136 |         <artwork>
137 |         <![CDATA[	
138 | or(eq(category,toy),eq(category,food))
139 | ]]></artwork></figure>
140 |       </t>
141 |     </section>
142 |     <section title="Defined Operators">
143 |       
144 |       <t>
145 |       RQL defines the following semantics for these operators:
146 |      <section title="sort">
147 |       <t>sort(&lt;+|->&lt;property) - Sorts the returned query result by the given property. The order of sort is specified by the prefix (+ for ascending, - for descending) to property.
148 |       To sort by foo in ascending order:
149 |       <figure>
150 |         <artwork>
151 |         <![CDATA[	
152 | sort(+foo)
153 | ]]></artwork></figure>
154 |       One can also do multiple property sorts. To sort by price in ascending order and rating in descending order:
155 |       <figure>
156 |         <artwork>
157 |         <![CDATA[	
158 | sort(+price,-rating)
159 | ]]></artwork></figure>
160 |       </t>
161 |      </section>
162 |      <section title="select">
163 |       <t>select(&lt;property>) - Returns a query result where each item is value of the property specified by the argument</t>
164 |       <t>select(&lt;property>,&lt;property>,...) - Trims each object down to the set of properties defined in the arguments</t>
165 |      </section>
166 |      <section title="aggregate">
167 |       <t>aggregate(&lt;property|operator>,...) - The aggregate function can be used for aggregation, it aggregates the result set, grouping by objects that are distinct for the provided properties, and then reduces the remaining other property values using the provided operator. To calculate the sum of sales for each department:
168 |       <figure>
169 |         <artwork>
170 |         <![CDATA[	
171 | aggregate(departmentId,sum(sales))
172 | ]]></artwork></figure>
173 | </t>
174 |      </section>
175 |      <section title="distinct">
176 |       <t>distinct() - Returns a result set with duplicates removed</t>
177 |      </section>
178 |      <section title="in">
179 |       <t>in(&lt;property>,&lt;array-of-values>) - Filters for objects where the specified property's value is in the provided array</t>
180 |      </section>
181 |      <section title="out">
182 |       <t>out(&lt;property>,&lt;array-of-values>) - Filters for objects where the specified property's value is not in the provided array</t>
183 |      </section>
184 |      <section title="contains">
185 |       <t>contains(&lt;property>,&lt;value | query>) - Filters for objects where the specified property's value is an array and the array contains any value that equals the provided value or satisfies the provided query.</t>
186 |      </section>
187 |      <section title="excludes">
188 |       <t>contains(&lt;property>,&lt;value | query>) - Filters for objects where the specified property's value is an array and the array does not contains any value that equals the provided value or satisfies the provided query.</t>
189 |      </section>
190 |      <section title="limit">
191 |       <t>limit(&tl;count>,&lt;start>) - Returns a limited range of records from the result set. The first parameter indicates the number of records to return, and the optional second parameter indicates the starting offset.</t>
192 |      </section>
193 |      <section title="and">
194 |       <t>and(&lt;query>,&lt;query>,...) - Returns a query result set applying all the given operators to constrain the query</t>
195 |      </section>
196 |      <section title="or">
197 |       <t>or(&lt;query>,&lt;query>,...) - Returns a union result set of the given operators</t>
198 |      </section>
199 |      <section title="eq">
200 |       <t>eq(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is equal to the provided value</t>
201 |      </section>
202 |      <section title="lt">
203 |       <t>lt(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is less than the provided value</t>
204 |      </section>
205 |      <section title="le">
206 |       <t>le(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is less than or equal to the provided value</t>
207 |      </section>
208 |      <section title="gt">
209 |       <t>gt(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is greater than the provided value</t>
210 |      </section>
211 |      <section title="ge">
212 |       <t>ge(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is greater than or equal to the provided value</t>
213 |      </section>
214 |      <section title="ne">
215 |       <t>ne(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is not equal to the provided value</t>
216 |      </section>
217 |      <section title="rel">
218 |       <t>rel(&lt;relation name?>,&lt;query>) - Applies the provided query against the linked data of the provided relation name.</t>
219 |      </section>
220 |      <section title="sum">
221 |       <t>sum(&lt;property?>) - Finds the sum of every value in the array or if the property argument is provided, returns the sum of the value of property for every object in the array</t>
222 |      </section>
223 |      <section title="mean">
224 |       <t>mean(&lt;property?>) - Finds the mean of every value in the array or if the property argument is provided, returns the mean of the value of property for every object in the array</t>
225 |      </section>
226 |      <section title="max">
227 |       <t>max(&lt;property?>) - Finds the maximum of every value in the array or if the property argument is provided, returns the maximum of the value of property for every object in the array</t>
228 |      </section>
229 |      <section title="min">
230 |       <t>min(&lt;property?>) - Finds the minimum of every value in the array or if the property argument is provided, returns the minimum of the value of property for every object in the array</t>
231 |      </section>
232 |      <section title="first">
233 |       <t>first() - Returns the first record of the query's result set</t>
234 |      </section>
235 |      <section title="one">
236 |       <t>one() - Returns the first and only record of the query's result set, or produces an error if the query's result set has more or less than one record in it.</t>
237 |      </section>
238 |      <section title="count">
239 |       <t>count() - Returns the count of the number of records in the query's result set</t>
240 |      </section>
241 |      <section title="recurse">
242 |       <t>recurse(&lt;property?>) - Recursively searches, looking in children of the object as objects in arrays in the given property value</t>
243 |      </section>
244 |       </t>
245 |     </section>
246 |     <section title="Comparison Syntax">
247 |       
248 |       <t>
249 |     RQL provides a semantically equivelant syntactic alternate to operator syntax with comparison syntax. A comparison operator may
250 |     be written in the form:
251 |       <figure>
252 |         <artwork>
253 |         <![CDATA[	
254 | name=value
255 | ]]></artwork></figure>
256 | As shorthand for:
257 |       <figure>
258 |         <artwork>
259 |         <![CDATA[	
260 | eq(name,value)
261 | ]]></artwork></figure>
262 | RQL also supports provides sugar for the "and" operator with ampersand delimited operators. The following form:
263 |       <figure>
264 |         <artwork>
265 |         <![CDATA[	
266 | operator&operator
267 | ]]></artwork></figure>
268 | As shorthand for:
269 |       <figure>
270 |         <artwork>
271 |         <![CDATA[	
272 | and(operator,operator)
273 | ]]></artwork></figure>
274 | With these transformations, one can write queries of the form:
275 |       <figure>
276 |         <artwork>
277 |         <![CDATA[	
278 | foo=3&bar=text
279 | ]]></artwork></figure>
280 | This makes the HTML's form url encoding of name value pairs a proper query within RQL.</t>
281 | <t>
282 | Ampersand delimited operators may be grouped by placing them within paranthesis. Top level queries themselves are considered to be implicitly a part of an "and" operator group, and therefore the top level ampersand delimited operators do not need to be enclosed with paranthesis, but "and" groups used within other operators do need to be enclosed in paranthesis.</t>
283 | <t>
284 | Pipe delimited operators may also be placed within paranthesis-enclosed groups as shorthand for the "or" operator. One can write a query:
285 |       <figure>
286 |         <artwork>
287 |         <![CDATA[	
288 | foo=3&(bar=text|bar=string)
289 | ]]></artwork></figure>
290 | Also, Feed Item Query Language is a subset of RQL valid. RQL supports named comparisons as shorthand for operators as well. The following form is a named comparison:
291 |       <figure>
292 |         <artwork>
293 |         <![CDATA[	
294 | name=comparator=value
295 | ]]></artwork></figure>
296 | Which is shorthand for:
297 |       <figure>
298 |         <artwork>
299 |         <![CDATA[	
300 | comparator(name,value)
301 | ]]></artwork></figure>
302 | For example, to find resources with a "price" less than 10:
303 |       <figure>
304 |         <artwork>
305 |         <![CDATA[	
306 | price=lt=10
307 | ]]></artwork></figure>
308 | </t>
309 | </section>
310 | <section title="Typed Values">
311 | <t>
312 | Basic values in RQL are simply a string of characters and it is up to the recipient of a query to determine how these characters should be interpreted and if they should be coerced to alternate data types understood by the language or database processing the query. However, RQL supports typed values to provide hints to the recipient of the intended data type of the value. The syntax of a typed value is:
313 |       <figure>
314 |         <artwork>
315 |         <![CDATA[	
316 | type:value
317 | ]]></artwork></figure>
318 | RQL suggests the following types to be supported:
319 | <list>
320 | <t>string - Indicates the value string should not be coerced, it should remain a string.</t>
321 | <t>number - Indicates the value string should be coerced to a number.</t>
322 | <t>boolean - Indicates the value string should be coerced to a boolean. A value of "true" should indicate true and a value of "false" should indicate false.</t>
323 | <t>epoch - Indicates the value string should be treated as the milliseconds since the epoch and coerced to a date.</t>
324 | </list>
325 | For example, to query for resources where foo explicitly equals the number 4:
326 |       <figure>
327 |         <artwork>
328 |         <![CDATA[	
329 | foo=number:4
330 | ]]></artwork></figure>
331 | 
332 | </t>
333 | </section>
334 | <section title="ABNF for RQL">
335 | <t>
336 | The following is the collected ABNF for RQL:
337 |       <figure>
338 |         <artwork>
339 |         <![CDATA[
340 | query = and
341 | 
342 | and = operator *( "&" operator )
343 | operator = comparison / call-operator / group
344 | call-operator = name "(" [ argument *( "," argument ) ] ")"
345 | argument = call-operator / value
346 | value = *nchar / typed-value / array
347 | typed-value = 1*nchar ":" *nchar
348 | array = "(" [ value *( "," value ) ] ")"
349 | name = *nchar
350 | 
351 | comparison = name ( "=" [ name "=" ] ) value
352 | group = "(" ( and / or ) ")"
353 | or = operator *( "|" operator )
354 | 
355 | nchar = unreserved / pct-encoded / "*" / "+"
356 | pct-encoded   = "%" HEXDIG HEXDIG
357 | unreserved    = ALPHA / DIGIT / "-" / "." / "_" / "~"
358 | 
359 | ]]></artwork></figure>
360 | 
361 | </t>
362 | </section>
363 | <section title="HTTP">
364 | <t>
365 | If RQL is used as for to define queries in HTTP URLs, there are several considerations. First, servers that allow publicly initiated requests should enforce proper security measures to protect against excessive resource consumption. Many operators may be understood
366 | by the server, but not efficiently executable and servers can therefore reject such queries. Rejections may be indicated by a 403 Forbidden status code response, or if authentication may provide the authorization necessary to perform the query, a 401 Unauthorized status code can be sent.
367 | </t>
368 | <t>
369 | If the query is not syntactically valid, (does not follow the RQL grammar), the server may return a status code of 400 Bad Request. If the query is syntactically valid, but the operator name is not known, the server may also return a status code of 400 Bad Request.
370 | </t>
371 | </section>
372 | <section title="IANA Considerations">
373 | <t>
374 |    The proposed MIME media type for Resource Query Language is application/rql
375 | </t>
376 | <t>
377 |    Type name: application
378 | </t>
379 | <t>
380 |    Subtype name: rql
381 | </t>
382 | <t>
383 |    Required parameters: none
384 |    </t>
385 | <t>
386 |    Optional parameters: none
387 |    </t>
388 | 
389 | 
390 | </section>
391 |   </middle>
392 | 
393 |   <back>
394 |     <!-- References Section -->
395 | 
396 | 
397 |     <references title="Normative References">
398 |       &rfc2119;
399 |       &rfc3986;
400 |     </references>
401 | 
402 |     <references title="Informative References">
403 |       &html401;
404 |       &fiql;
405 |     </references>
406 | 
407 |     <!--
408 | <section anchor="appendix" title="Appendix A">
409 | 	<t>You can add appendices just as regular sections, the only
410 | difference is that they go under "back" element, and get letters 
411 | instead of numbers</t>
412 | </section>
413 | -->
414 | 
415 |     <section title="Change Log ">
416 |           <t>-00</t>
417 |           <t>
418 |             <list style="symbols">
419 |               <t>Initial draft</t>
420 |             </list>
421 |           </t>
422 | 
423 |     </section>
424 | 
425 |     <section title="Open Issues">
426 | 
427 |     </section>
428 | 
429 |     <!--
430 | $Log: draft-zyp-rql.xml,v $
431 | Revision 0.1  2009/09/25 02:46:57  H73653
432 | *** empty log message ***
433 | 	place for source control log here
434 |   -->
435 |   </back>
436 | </rfc>
437 | 


--------------------------------------------------------------------------------
/specification/draft-zyp-rql-00.html:
--------------------------------------------------------------------------------
  1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  2 | <html lang="en"><head><title>Resource Query Language</title>
  3 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  4 | <meta name="description" content="Resource Query Language">
  5 | <meta name="keywords" content="resource, query">
  6 | <meta name="generator" content="xml2rfc v1.35 (http://xml.resource.org/)">
  7 | <style type='text/css'><!--
  8 |         body {
  9 |                 font-family: verdana, charcoal, helvetica, arial, sans-serif;
 10 |                 font-size: small; color: #000; background-color: #FFF;
 11 |                 margin: 2em;
 12 |         }
 13 |         h1, h2, h3, h4, h5, h6 {
 14 |                 font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif;
 15 |                 font-weight: bold; font-style: normal;
 16 |         }
 17 |         h1 { color: #900; background-color: transparent; text-align: right; }
 18 |         h3 { color: #333; background-color: transparent; }
 19 | 
 20 |         td.RFCbug {
 21 |                 font-size: x-small; text-decoration: none;
 22 |                 width: 30px; height: 30px; padding-top: 2px;
 23 |                 text-align: justify; vertical-align: middle;
 24 |                 background-color: #000;
 25 |         }
 26 |         td.RFCbug span.RFC {
 27 |                 font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
 28 |                 font-weight: bold; color: #666;
 29 |         }
 30 |         td.RFCbug span.hotText {
 31 |                 font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
 32 |                 font-weight: normal; text-align: center; color: #FFF;
 33 |         }
 34 | 
 35 |         table.TOCbug { width: 30px; height: 15px; }
 36 |         td.TOCbug {
 37 |                 text-align: center; width: 30px; height: 15px;
 38 |                 color: #FFF; background-color: #900;
 39 |         }
 40 |         td.TOCbug a {
 41 |                 font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif;
 42 |                 font-weight: bold; font-size: x-small; text-decoration: none;
 43 |                 color: #FFF; background-color: transparent;
 44 |         }
 45 | 
 46 |         td.header {
 47 |                 font-family: arial, helvetica, sans-serif; font-size: x-small;
 48 |                 vertical-align: top; width: 33%;
 49 |                 color: #FFF; background-color: #666;
 50 |         }
 51 |         td.author { font-weight: bold; font-size: x-small; margin-left: 4em; }
 52 |         td.author-text { font-size: x-small; }
 53 | 
 54 |         /* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
 55 |         a.info {
 56 |                 /* This is the key. */
 57 |                 position: relative;
 58 |                 z-index: 24;
 59 |                 text-decoration: none;
 60 |         }
 61 |         a.info:hover {
 62 |                 z-index: 25;
 63 |                 color: #FFF; background-color: #900;
 64 |         }
 65 |         a.info span { display: none; }
 66 |         a.info:hover span.info {
 67 |                 /* The span will display just on :hover state. */
 68 |                 display: block;
 69 |                 position: absolute;
 70 |                 font-size: smaller;
 71 |                 top: 2em; left: -5em; width: 15em;
 72 |                 padding: 2px; border: 1px solid #333;
 73 |                 color: #900; background-color: #EEE;
 74 |                 text-align: left;
 75 |         }
 76 | 
 77 |         a { font-weight: bold; }
 78 |         a:link    { color: #900; background-color: transparent; }
 79 |         a:visited { color: #633; background-color: transparent; }
 80 |         a:active  { color: #633; background-color: transparent; }
 81 | 
 82 |         p { margin-left: 2em; margin-right: 2em; }
 83 |         p.copyright { font-size: x-small; }
 84 |         p.toc { font-size: small; font-weight: bold; margin-left: 3em; }
 85 |         table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; }
 86 |         td.toc { font-size: small; font-weight: bold; vertical-align: text-top; }
 87 | 
 88 |         ol.text { margin-left: 2em; margin-right: 2em; }
 89 |         ul.text { margin-left: 2em; margin-right: 2em; }
 90 |         li      { margin-left: 3em; }
 91 | 
 92 |         /* RFC-2629 <spanx>s and <artwork>s. */
 93 |         em     { font-style: italic; }
 94 |         strong { font-weight: bold; }
 95 |         dfn    { font-weight: bold; font-style: normal; }
 96 |         cite   { font-weight: normal; font-style: normal; }
 97 |         tt     { color: #036; }
 98 |         tt, pre, pre dfn, pre em, pre cite, pre span {
 99 |                 font-family: "Courier New", Courier, monospace; font-size: small;
100 |         }
101 |         pre {
102 |                 text-align: left; padding: 4px;
103 |                 color: #000; background-color: #CCC;
104 |         }
105 |         pre dfn  { color: #900; }
106 |         pre em   { color: #66F; background-color: #FFC; font-weight: normal; }
107 |         pre .key { color: #33C; font-weight: bold; }
108 |         pre .id  { color: #900; }
109 |         pre .str { color: #000; background-color: #CFF; }
110 |         pre .val { color: #066; }
111 |         pre .rep { color: #909; }
112 |         pre .oth { color: #000; background-color: #FCF; }
113 |         pre .err { background-color: #FCC; }
114 | 
115 |         /* RFC-2629 <texttable>s. */
116 |         table.all, table.full, table.headers, table.none {
117 |                 font-size: small; text-align: center; border-width: 2px;
118 |                 vertical-align: top; border-collapse: collapse;
119 |         }
120 |         table.all, table.full { border-style: solid; border-color: black; }
121 |         table.headers, table.none { border-style: none; }
122 |         th {
123 |                 font-weight: bold; border-color: black;
124 |                 border-width: 2px 2px 3px 2px;
125 |         }
126 |         table.all th, table.full th { border-style: solid; }
127 |         table.headers th { border-style: none none solid none; }
128 |         table.none th { border-style: none; }
129 |         table.all td {
130 |                 border-style: solid; border-color: #333;
131 |                 border-width: 1px 2px;
132 |         }
133 |         table.full td, table.headers td, table.none td { border-style: none; }
134 | 
135 |         hr { height: 1px; }
136 |         hr.insert {
137 |                 width: 80%; border-style: none; border-width: 0;
138 |                 color: #CCC; background-color: #CCC;
139 |         }
140 | --></style>
141 | </head>
142 | <body>
143 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
144 | <table summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1">
145 | <tr><td class="header">Internet Engineering Task Force</td><td class="header">K. Zyp, Ed.</td></tr>
146 | <tr><td class="header">Internet-Draft</td><td class="header">SitePen (USA)</td></tr>
147 | <tr><td class="header">Intended status: Informational</td><td class="header">June 30, 2010</td></tr>
148 | <tr><td class="header">Expires: January 1, 2011</td><td class="header">&nbsp;</td></tr>
149 | </table></td></tr></table>
150 | <h1><br />Resource Query Language<br />draft-zyp-rql-00</h1>
151 | 
152 | <h3>Abstract</h3>
153 | 
154 | <p>Resource Query Languages (RQL) defines a syntactically simple query language 
155 |       for querying and retrieving resources. RQL is designed to be URI friendly, 
156 |       particularly as a query component of a URI, and highly extensible. RQL is a superset
157 |       of HTML's URL encoding of form values, and a superset of Feed Item Query Language (FIQL).
158 |       RQL basically consists of a set of nestable named operators which each have a set of 
159 |       arguments and operate on a collection of resources. An example of an RQL for finding
160 |       resources with a category of "toy" and sorted by price in ascending order:
161 |       </p>
162 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
163 | 
164 | category=toy&amp;sort(+price)
165 | </pre></div><p>
166 | 
167 |       
168 | </p>
169 | <h3>Status of This Memo</h3>
170 | <p>
171 | This Internet-Draft is submitted  in full
172 | conformance with the provisions of BCP&nbsp;78 and BCP&nbsp;79.</p>
173 | <p>
174 | Internet-Drafts are working documents of the Internet Engineering
175 | Task Force (IETF).  Note that other groups may also distribute
176 | working documents as Internet-Drafts.  The list of current
177 | Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.</p>
178 | <p>
179 | Internet-Drafts are draft documents valid for a maximum of six months
180 | and may be updated, replaced, or obsoleted by other documents at any time.
181 | It is inappropriate to use Internet-Drafts as reference material or to cite
182 | them other than as &ldquo;work in progress.&rdquo;</p>
183 | <p>
184 | This Internet-Draft will expire on January 1, 2011.</p>
185 | 
186 | <h3>Copyright Notice</h3>
187 | <p>
188 | Copyright (c) 2010 IETF Trust and the persons identified as the
189 | document authors.  All rights reserved.</p>
190 | <p>
191 | This document is subject to BCP 78 and the IETF Trust's Legal
192 | Provisions Relating to IETF Documents
193 | (http://trustee.ietf.org/license-info) in effect on the date of
194 | publication of this document.  Please review these documents
195 | carefully, as they describe your rights and restrictions with respect
196 | to this document. Code Components extracted from this document must
197 | include Simplified BSD License text as described in Section 4.e of
198 | the Trust Legal Provisions and are provided without warranty as
199 | described in the Simplified BSD License.</p>
200 | <a name="toc"></a><br /><hr />
201 | <h3>Table of Contents</h3>
202 | <p class="toc">
203 | <a href="#anchor1">1.</a>&nbsp;
204 | Introduction<br />
205 | <a href="#anchor2">2.</a>&nbsp;
206 | Conventions<br />
207 | <a href="#anchor3">3.</a>&nbsp;
208 | Overview<br />
209 | <a href="#anchor4">4.</a>&nbsp;
210 | Operators<br />
211 | <a href="#anchor5">5.</a>&nbsp;
212 | Values<br />
213 | <a href="#anchor6">6.</a>&nbsp;
214 | Arrays<br />
215 | <a href="#anchor7">7.</a>&nbsp;
216 | Nested Operators<br />
217 | <a href="#anchor8">8.</a>&nbsp;
218 | Defined Operators<br />
219 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor9">8.1.</a>&nbsp;
220 | sort<br />
221 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor10">8.2.</a>&nbsp;
222 | select<br />
223 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor11">8.3.</a>&nbsp;
224 | aggregate<br />
225 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor12">8.4.</a>&nbsp;
226 | distinct<br />
227 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor13">8.5.</a>&nbsp;
228 | in<br />
229 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor14">8.6.</a>&nbsp;
230 | contains<br />
231 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor15">8.7.</a>&nbsp;
232 | limit<br />
233 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor16">8.8.</a>&nbsp;
234 | and<br />
235 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor17">8.9.</a>&nbsp;
236 | or<br />
237 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor18">8.10.</a>&nbsp;
238 | eq<br />
239 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor19">8.11.</a>&nbsp;
240 | lt<br />
241 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor20">8.12.</a>&nbsp;
242 | le<br />
243 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor21">8.13.</a>&nbsp;
244 | gt<br />
245 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor22">8.14.</a>&nbsp;
246 | ge<br />
247 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor23">8.15.</a>&nbsp;
248 | ne<br />
249 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor24">8.16.</a>&nbsp;
250 | sum<br />
251 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor25">8.17.</a>&nbsp;
252 | mean<br />
253 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor26">8.18.</a>&nbsp;
254 | max<br />
255 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor27">8.19.</a>&nbsp;
256 | min<br />
257 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor28">8.20.</a>&nbsp;
258 | recurse<br />
259 | <a href="#anchor29">9.</a>&nbsp;
260 | Comparison Syntax<br />
261 | <a href="#anchor30">10.</a>&nbsp;
262 | Typed Values<br />
263 | <a href="#anchor31">11.</a>&nbsp;
264 | ABNF for RQL<br />
265 | <a href="#anchor32">12.</a>&nbsp;
266 | HTTP<br />
267 | <a href="#anchor33">13.</a>&nbsp;
268 | IANA Considerations<br />
269 | <a href="#rfc.references1">14.</a>&nbsp;
270 | References<br />
271 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#rfc.references1">14.1.</a>&nbsp;
272 | Normative References<br />
273 | &nbsp;&nbsp;&nbsp;&nbsp;<a href="#rfc.references2">14.2.</a>&nbsp;
274 | Informative References<br />
275 | <a href="#anchor36">Appendix&nbsp;A.</a>&nbsp;
276 | Change Log <br />
277 | <a href="#anchor37">Appendix&nbsp;B.</a>&nbsp;
278 | Open Issues<br />
279 | </p>
280 | <br clear="all" />
281 | 
282 | <a name="anchor1"></a><br /><hr />
283 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
284 | <a name="rfc.section.1"></a><h3>1.&nbsp;
285 | Introduction</h3>
286 | 
287 | <p>Resource Query Languages (RQL) defines a syntactically simple query language 
288 |       for querying and retrieving resources. RQL is designed to be URI friendly, 
289 |       particularly as a query component of a URI, and highly extensible. RQL is a superset
290 |       of HTML's URL encoding of form values, and a superset of Feed Item Query Language (FIQL).
291 | 
292 | </p>
293 | <a name="anchor2"></a><br /><hr />
294 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
295 | <a name="rfc.section.2"></a><h3>2.&nbsp;
296 | Conventions</h3>
297 | 
298 | <p>The key words "MUST", "MUST
299 |       NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
300 |       "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
301 |       interpreted as described in RFC 2119.
302 | </p>
303 | <a name="anchor3"></a><br /><hr />
304 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
305 | <a name="rfc.section.3"></a><h3>3.&nbsp;
306 | Overview</h3>
307 | 
308 | <p>RQL consists of a set of nestable named operators which each have a set of 
309 |       arguments. RQL is designed to be applied to a collection of resources. Each top-level 
310 |       operator defines a constraint or modification to the result of the query from the base 
311 |       collection of resources. Nested operators provide constraint information for the operators within which they are embedded. 
312 |       
313 | </p>
314 | <a name="anchor4"></a><br /><hr />
315 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
316 | <a name="rfc.section.4"></a><h3>4.&nbsp;
317 | Operators</h3>
318 | 
319 | <p>
320 |       An operator consists of an operator name followed by a list of comma-delimited arguments within paranthesis:
321 |       </p>
322 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
323 | 
324 | name(args,...)
325 | </pre></div><p>
326 | 
327 |       Each argument may be a value (a string of unreserved or URL-encoded characters), an array, or another operator. The name of the operator indicates the type of action the operator will perform on the collection, using the given arguments. This document defines the semantics of a set of operators, but the query language can be extended with additional operators.
328 | </p>
329 | <p>      
330 |       A simple RQL query with a single operator that indicates a search for any 
331 |       resources with a property of "foo" that has value of 3 could be written:
332 |       </p>
333 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
334 | 
335 | eq(foo,3)
336 | </pre></div><p>
337 | 
338 |       
339 | </p>
340 | <a name="anchor5"></a><br /><hr />
341 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
342 | <a name="rfc.section.5"></a><h3>5.&nbsp;
343 | Values</h3>
344 | 
345 | <p>
346 | 	Simple values are simply URL-encoded sequences of characters. Unreserved characters do not need to be encoded, other characters should be encoding using standard URL encoding. Simple values can be decoded to determine the intended string of characters. Values can also include arrays or typed values. These are described in the "Typed Values" and "Arrays" section below.
347 |       
348 | </p>
349 | <a name="anchor6"></a><br /><hr />
350 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
351 | <a name="rfc.section.6"></a><h3>6.&nbsp;
352 | Arrays</h3>
353 | 
354 | <p>
355 |       One of the allowable arguments for operators is an array. An array is paranthesis-enclosed comma-delimited set of items. Each item in the array can be a value or an operator. A query that finds all the resources where the category can be "toy" or "food" could be written with an array argument:
356 |       </p>
357 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
358 | 
359 | in(category,(toy,food))
360 | </pre></div><p>
361 | 
362 |       
363 |       
364 | </p>
365 | <a name="anchor7"></a><br /><hr />
366 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
367 | <a name="rfc.section.7"></a><h3>7.&nbsp;
368 | Nested Operators</h3>
369 | 
370 | <p>
371 |       Operators may be nested. For example, a set of operators can be used as the arguments for the "or" operator. Another query that finds all the resources where the category can be "toy" or "food" could be written with nested "eq" operators within an "or" operator:
372 |       </p>
373 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
374 | 
375 | or(eq(category,toy),eq(category,food))
376 | </pre></div><p>
377 | 
378 |       
379 | </p>
380 | <a name="anchor8"></a><br /><hr />
381 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
382 | <a name="rfc.section.8"></a><h3>8.&nbsp;
383 | Defined Operators</h3>
384 | 
385 | <p>
386 |       RQL defines the following semantics for these operators:
387 |      
388 | <a name="anchor9"></a><br /><hr />
389 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
390 | <a name="rfc.section.8.1"></a><h3>8.1.&nbsp;
391 | sort</h3>
392 | 
393 | <p>sort(&lt;+|->&lt;property) - Sorts the returned query result by the given property. The order of sort is specified by the prefix (+ for ascending, - for descending) to property.
394 |       To sort by foo in ascending order:
395 |       </p>
396 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
397 | 
398 | sort(+foo)
399 | </pre></div><p>
400 | 
401 |       One can also do multiple property sorts. To sort by price in ascending order and rating in descending order:
402 |       </p>
403 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
404 | 
405 | sort(+price,-rating)
406 | </pre></div><p>
407 | 
408 |       
409 | </p>
410 |      
411 | <a name="anchor10"></a><br /><hr />
412 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
413 | <a name="rfc.section.8.2"></a><h3>8.2.&nbsp;
414 | select</h3>
415 | 
416 | <p>select(&lt;property>) - Returns a query result where each item is value of the property specified by the argument
417 | </p>
418 | <p>select(&lt;property>,&lt;property>,...) - Trims each object down to the set of properties defined in the arguments
419 | </p>
420 |      
421 | <a name="anchor11"></a><br /><hr />
422 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
423 | <a name="rfc.section.8.3"></a><h3>8.3.&nbsp;
424 | aggregate</h3>
425 | 
426 | <p>aggregate(&lt;property|operator>,...) - The aggregate function can be used for aggregation, it aggregates the result set, grouping by objects that are distinct for the provided properties, and then reduces the remaining other property values using the provided operator. To calculate the sum of sales for each department:
427 |       </p>
428 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
429 | 
430 | aggregate(departmentId,sum(sales))
431 | </pre></div><p>
432 | 
433 | 
434 | </p>
435 |      
436 | <a name="anchor12"></a><br /><hr />
437 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
438 | <a name="rfc.section.8.4"></a><h3>8.4.&nbsp;
439 | distinct</h3>
440 | 
441 | <p>distinct() - Returns a result set with duplicates removed
442 | </p>
443 |      
444 | <a name="anchor13"></a><br /><hr />
445 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
446 | <a name="rfc.section.8.5"></a><h3>8.5.&nbsp;
447 | in</h3>
448 | 
449 | <p>in(&lt;property>,&lt;array-of-values>) - Filters for objects where the specified property's value is in the provided array
450 | </p>
451 |      
452 | <a name="anchor14"></a><br /><hr />
453 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
454 | <a name="rfc.section.8.6"></a><h3>8.6.&nbsp;
455 | contains</h3>
456 | 
457 | <p>contains(&lt;property>,&lt;value | array-of-values>) - Filters for objects where the specified property's value is an array and the array contains the provided value or contains a value in the provided array
458 | </p>
459 |      
460 | <a name="anchor15"></a><br /><hr />
461 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
462 | <a name="rfc.section.8.7"></a><h3>8.7.&nbsp;
463 | limit</h3>
464 | 
465 | <p>limit(start,count) - Returns a limited range of records from the result set. The first parameter indicates the starting offset and the second parameter indicates the number of records to return.
466 | </p>
467 |      
468 | <a name="anchor16"></a><br /><hr />
469 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
470 | <a name="rfc.section.8.8"></a><h3>8.8.&nbsp;
471 | and</h3>
472 | 
473 | <p>and(&lt;query>,&lt;query>,...) - Returns a query result set applying all the given operators to constrain the query
474 | </p>
475 |      
476 | <a name="anchor17"></a><br /><hr />
477 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
478 | <a name="rfc.section.8.9"></a><h3>8.9.&nbsp;
479 | or</h3>
480 | 
481 | <p>or(&lt;query>,&lt;query>,...) - Returns a union result set of the given operators
482 | </p>
483 |      
484 | <a name="anchor18"></a><br /><hr />
485 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
486 | <a name="rfc.section.8.10"></a><h3>8.10.&nbsp;
487 | eq</h3>
488 | 
489 | <p>eq(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is equal to the provided value
490 | </p>
491 |      
492 | <a name="anchor19"></a><br /><hr />
493 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
494 | <a name="rfc.section.8.11"></a><h3>8.11.&nbsp;
495 | lt</h3>
496 | 
497 | <p>lt(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is less than the provided value
498 | </p>
499 |      
500 | <a name="anchor20"></a><br /><hr />
501 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
502 | <a name="rfc.section.8.12"></a><h3>8.12.&nbsp;
503 | le</h3>
504 | 
505 | <p>le(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is less than or equal to the provided value
506 | </p>
507 |      
508 | <a name="anchor21"></a><br /><hr />
509 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
510 | <a name="rfc.section.8.13"></a><h3>8.13.&nbsp;
511 | gt</h3>
512 | 
513 | <p>gt(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is greater than the provided value
514 | </p>
515 |      
516 | <a name="anchor22"></a><br /><hr />
517 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
518 | <a name="rfc.section.8.14"></a><h3>8.14.&nbsp;
519 | ge</h3>
520 | 
521 | <p>ge(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is greater than or equal to the provided value
522 | </p>
523 |      
524 | <a name="anchor23"></a><br /><hr />
525 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
526 | <a name="rfc.section.8.15"></a><h3>8.15.&nbsp;
527 | ne</h3>
528 | 
529 | <p>ne(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is not equal to the provided value
530 | </p>
531 |      
532 | <a name="anchor24"></a><br /><hr />
533 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
534 | <a name="rfc.section.8.16"></a><h3>8.16.&nbsp;
535 | sum</h3>
536 | 
537 | <p>sum(&lt;property?>) - Finds the sum of every value in the array or if the property argument is provided, returns the sum of the value of property for every object in the array
538 | </p>
539 |      
540 | <a name="anchor25"></a><br /><hr />
541 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
542 | <a name="rfc.section.8.17"></a><h3>8.17.&nbsp;
543 | mean</h3>
544 | 
545 | <p>mean(&lt;property?>) - Finds the mean of every value in the array or if the property argument is provided, returns the mean of the value of property for every object in the array
546 | </p>
547 |      
548 | <a name="anchor26"></a><br /><hr />
549 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
550 | <a name="rfc.section.8.18"></a><h3>8.18.&nbsp;
551 | max</h3>
552 | 
553 | <p>max(&lt;property?>) - Finds the maximum of every value in the array or if the property argument is provided, returns the maximum of the value of property for every object in the array
554 | </p>
555 |      
556 | <a name="anchor27"></a><br /><hr />
557 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
558 | <a name="rfc.section.8.19"></a><h3>8.19.&nbsp;
559 | min</h3>
560 | 
561 | <p>min(&lt;property?>) - Finds the minimum of every value in the array or if the property argument is provided, returns the minimum of the value of property for every object in the array
562 | </p>
563 |      
564 | <a name="anchor28"></a><br /><hr />
565 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
566 | <a name="rfc.section.8.20"></a><h3>8.20.&nbsp;
567 | recurse</h3>
568 | 
569 | <p>recurse(&lt;property?>) - Recursively searches, looking in children of the object as objects in arrays in the given property value
570 | </p>
571 |       
572 | 
573 | <a name="anchor29"></a><br /><hr />
574 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
575 | <a name="rfc.section.9"></a><h3>9.&nbsp;
576 | Comparison Syntax</h3>
577 | 
578 | <p>
579 |     RQL provides a semantically equivelant syntactic alternate to operator syntax with comparison syntax. A comparison operator may
580 |     be written in the form:
581 |       </p>
582 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
583 | 
584 | name=value
585 | </pre></div><p>
586 | 
587 | As shorthand for:
588 |       </p>
589 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
590 | 
591 | eq(name,value)
592 | </pre></div><p>
593 | 
594 | RQL also supports provides sugar for the "and" operator with ampersand delimited operators. The following form:
595 |       </p>
596 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
597 | 
598 | operator&amp;operator
599 | </pre></div><p>
600 | 
601 | As shorthand for:
602 |       </p>
603 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
604 | 
605 | and(operator,operator)
606 | </pre></div><p>
607 | 
608 | With these transformations, one can write queries of the form:
609 |       </p>
610 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
611 | 
612 | foo=3&amp;bar=text
613 | </pre></div><p>
614 | 
615 | This makes the HTML's form url encoding of name value pairs a proper query within RQL.
616 | </p>
617 | <p>
618 | Ampersand delimited operators may be grouped by placing them within paranthesis. Top level queries themselves are considered to be implicitly a part of an "and" operator group, and therefore the top level ampersand delimited operators do not need to be enclosed with paranthesis, but "and" groups used within other operators do need to be enclosed in paranthesis.
619 | </p>
620 | <p>
621 | Pipe delimited operators may also be placed within paranthesis-enclosed groups as shorthand for the "or" operator. One can write a query:
622 |       </p>
623 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
624 | 
625 | foo=3&amp;(bar=text|bar=string)
626 | </pre></div><p>
627 | 
628 | Also, Feed Item Query Language is a subset of RQL valid. RQL supports named comparisons as shorthand for operators as well. The following form is a named comparison:
629 |       </p>
630 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
631 | 
632 | name=comparator=value
633 | </pre></div><p>
634 | 
635 | Which is shorthand for:
636 |       </p>
637 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
638 | 
639 | comparator(name,value)
640 | </pre></div><p>
641 | 
642 | For example, to find resources with a "price" less than 10:
643 |       </p>
644 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
645 | 
646 | price=lt=10
647 | </pre></div><p>
648 | 
649 | 
650 | </p>
651 | <a name="anchor30"></a><br /><hr />
652 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
653 | <a name="rfc.section.10"></a><h3>10.&nbsp;
654 | Typed Values</h3>
655 | 
656 | <p>
657 | Basic values in RQL are simply a string of characters and it is up to the recipient of a query to determine how these characters should be interpreted and if they should be coerced to alternate data types understood by the language or database processing the query. However, RQL supports typed values to provide hints to the recipient of the intended data type of the value. The syntax of a typed value is:
658 |       </p>
659 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
660 | 
661 | type:value
662 | </pre></div><p>
663 | 
664 | RQL suggests the following types to be supported:
665 | </p>
666 | <blockquote class="text">
667 | <p>string - Indicates the value string should not be coerced, it should remain a string.
668 | </p>
669 | <p>number - Indicates the value string should be coerced to a number.
670 | </p>
671 | <p>boolean - Indicates the value string should be coerced to a boolean. A value of "true" should indicate true and a value of "false" should indicate false.
672 | </p>
673 | <p>epoch - Indicates the value string should be treated as the milliseconds since the epoch and coerced to a date.
674 | </p>
675 | </blockquote><p>
676 | For example, to query for resources where foo explicitly equals the number 4:
677 |       </p>
678 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
679 | 
680 | foo=number:4
681 | </pre></div><p>
682 | 
683 | 
684 | 
685 | </p>
686 | <a name="anchor31"></a><br /><hr />
687 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
688 | <a name="rfc.section.11"></a><h3>11.&nbsp;
689 | ABNF for RQL</h3>
690 | 
691 | <p>
692 | The following is the collected ABNF for RQL:
693 |       </p>
694 | <div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
695 | 
696 | query = and
697 | 
698 | and = operator *( "&amp;" operator )
699 | operator = comparison / call-operator / group
700 | call-operator = name "(" [ argument *( "," argument ) ] ")"
701 | argument = call-operator / value
702 | value = *nchar / typed-value / array
703 | typed-value = 1*nchar ":" *nchar
704 | array = "(" [ value *( "," value ) ] ")"
705 | name = *nchar
706 | 
707 | comparison = name ( "=" [ name "=" ] ) value
708 | group = "(" ( and / or ) ")"
709 | or = operator *( "|" operator )
710 | 
711 | nchar = unreserved / pct-encoded / "*" / "+"
712 | pct-encoded   = "%" HEXDIG HEXDIG
713 | unreserved    = ALPHA / DIGIT / "-" / "." / "_" / "~"
714 | 
715 | </pre></div><p>
716 | 
717 | 
718 | 
719 | </p>
720 | <a name="anchor32"></a><br /><hr />
721 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
722 | <a name="rfc.section.12"></a><h3>12.&nbsp;
723 | HTTP</h3>
724 | 
725 | <p>
726 | If RQL is used as for to define queries in HTTP URLs, there are several considerations. First, servers that allow publicly initiated requests should enforce proper security measures to protect against excessive resource consumption. Many operators may be understood
727 | by the server, but not efficiently executable and servers can therefore reject such queries. Rejections may be indicated by a 403 Forbidden status code response, or if authentication may provide the authorization necessary to perform the query, a 401 Unauthorized status code can be sent.
728 | 
729 | </p>
730 | <p>
731 | If the query is not syntactically valid, (does not follow the RQL grammar), the server may return a status code of 400 Bad Request. If the query is syntactically valid, but the operator name is not known, the server may also return a status code of 400 Bad Request.
732 | 
733 | </p>
734 | <a name="anchor33"></a><br /><hr />
735 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
736 | <a name="rfc.section.13"></a><h3>13.&nbsp;
737 | IANA Considerations</h3>
738 | 
739 | <p>
740 |    The proposed MIME media type for Resource Query Language is application/rql
741 | 
742 | </p>
743 | <p>
744 |    Type name: application
745 | 
746 | </p>
747 | <p>
748 |    Subtype name: rql
749 | 
750 | </p>
751 | <p>
752 |    Required parameters: none
753 |    
754 | </p>
755 | <p>
756 |    Optional parameters: none
757 |    
758 | </p>
759 | <a name="rfc.references"></a><br /><hr />
760 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
761 | <a name="rfc.section.14"></a><h3>14.&nbsp;
762 | References</h3>
763 | 
764 | <a name="rfc.references1"></a><br /><hr />
765 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
766 | <h3>14.1.&nbsp;Normative References</h3>
767 | <table width="99%" border="0">
768 | <tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td>
769 | <td class="author-text"><a href="mailto:sob@harvard.edu">Bradner, S.</a>, &ldquo;<a href="http://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a>,&rdquo; BCP&nbsp;14, RFC&nbsp;2119, March&nbsp;1997 (<a href="http://www.rfc-editor.org/rfc/rfc2119.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc2119.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc2119.xml">XML</a>).</td></tr>
770 | <tr><td class="author-text" valign="top"><a name="RFC3986">[RFC3986]</a></td>
771 | <td class="author-text"><a href="mailto:timbl@w3.org">Berners-Lee, T.</a>, <a href="mailto:fielding@gbiv.com">Fielding, R.</a>, and <a href="mailto:LMM@acm.org">L. Masinter</a>, &ldquo;<a href="http://tools.ietf.org/html/rfc3986">Uniform Resource Identifier (URI): Generic Syntax</a>,&rdquo; STD&nbsp;66, RFC&nbsp;3986, January&nbsp;2005 (<a href="http://www.rfc-editor.org/rfc/rfc3986.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc3986.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc3986.xml">XML</a>).</td></tr>
772 | </table>
773 | 
774 | <a name="rfc.references2"></a><br /><hr />
775 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
776 | <h3>14.2.&nbsp;Informative References</h3>
777 | <table width="99%" border="0">
778 | <tr><td class="author-text" valign="top"><a name="W3C.REC-html401-19991224">[W3C.REC-html401-19991224]</a></td>
779 | <td class="author-text">Hors, A., Raggett, D., and I. Jacobs, &ldquo;<a href="http://www.w3.org/TR/1999/REC-html401-19991224">HTML 4.01 Specification</a>,&rdquo; World Wide Web Consortium Recommendation&nbsp;REC-html401-19991224, December&nbsp;1999 (<a href="http://www.w3.org/TR/1999/REC-html401-19991224">HTML</a>).</td></tr>
780 | <tr><td class="author-text" valign="top"><a name="I-D.nottingham-atompub-fiql">[I-D.nottingham-atompub-fiql]</a></td>
781 | <td class="author-text">Nottingham, M., &ldquo;<a href="http://www.ietf.org/internet-drafts/draft-nottingham-atompub-fiql-00.txt">FIQL: The Feed Item Query Language</a>,&rdquo; draft-nottingham-atompub-fiql-00 (work in progress), December&nbsp;2007 (<a href="http://www.ietf.org/internet-drafts/draft-nottingham-atompub-fiql-00.txt">TXT</a>).</td></tr>
782 | </table>
783 | 
784 | <a name="anchor36"></a><br /><hr />
785 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
786 | <a name="rfc.section.A"></a><h3>Appendix A.&nbsp;
787 | Change Log </h3>
788 | 
789 | <p>-00
790 | </p>
791 | <p>
792 |             </p>
793 | <ul class="text">
794 | <li>Initial draft
795 | </li>
796 | </ul><p>
797 |           
798 | </p>
799 | <a name="anchor37"></a><br /><hr />
800 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
801 | <a name="rfc.section.B"></a><h3>Appendix B.&nbsp;
802 | Open Issues</h3>
803 | 
804 | <a name="rfc.authors"></a><br /><hr />
805 | <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
806 | <h3>Author's Address</h3>
807 | <table width="99%" border="0" cellpadding="0" cellspacing="0">
808 | <tr><td class="author-text">&nbsp;</td>
809 | <td class="author-text">Kris Zyp (editor)</td></tr>
810 | <tr><td class="author-text">&nbsp;</td>
811 | <td class="author-text">SitePen (USA)</td></tr>
812 | <tr><td class="author-text">&nbsp;</td>
813 | <td class="author-text">530 Lytton Avenue</td></tr>
814 | <tr><td class="author-text">&nbsp;</td>
815 | <td class="author-text">Palo Alto, CA 94301</td></tr>
816 | <tr><td class="author-text">&nbsp;</td>
817 | <td class="author-text">USA</td></tr>
818 | <tr><td class="author" align="right">Phone:&nbsp;</td>
819 | <td class="author-text">+1 650 968 8787</td></tr>
820 | <tr><td class="author" align="right">EMail:&nbsp;</td>
821 | <td class="author-text"><a href="mailto:kris@sitepen.com">kris@sitepen.com</a></td></tr>
822 | </table>
823 | </body></html>
824 | 
825 | 


--------------------------------------------------------------------------------