You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by an...@apache.org on 2016/07/11 14:23:03 UTC
[04/54] [abbrv] [partial] cordova-windows git commit: CB-11552
Updated checked-in node_modules
http://git-wip-us.apache.org/repos/asf/cordova-windows/blob/3aca1d87/node_modules/plist/examples/browser/index.html
----------------------------------------------------------------------
diff --git a/node_modules/plist/examples/browser/index.html b/node_modules/plist/examples/browser/index.html
new file mode 100644
index 0000000..8ce7d92
--- /dev/null
+++ b/node_modules/plist/examples/browser/index.html
@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>plist.js browser example</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ </head>
+ <body>
+ <script src="../../dist/plist.js"></script>
+ <script>
+ // TODO: add <input type=file> drag and drop example
+ console.log(plist);
+ </script>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/cordova-windows/blob/3aca1d87/node_modules/plist/lib/build.js
----------------------------------------------------------------------
diff --git a/node_modules/plist/lib/build.js b/node_modules/plist/lib/build.js
new file mode 100644
index 0000000..e2b9454
--- /dev/null
+++ b/node_modules/plist/lib/build.js
@@ -0,0 +1,138 @@
+
+/**
+ * Module dependencies.
+ */
+
+var base64 = require('base64-js');
+var xmlbuilder = require('xmlbuilder');
+
+/**
+ * Module exports.
+ */
+
+exports.build = build;
+
+/**
+ * Accepts a `Date` instance and returns an ISO date string.
+ *
+ * @param {Date} d - Date instance to serialize
+ * @returns {String} ISO date string representation of `d`
+ * @api private
+ */
+
+function ISODateString(d){
+ function pad(n){
+ return n < 10 ? '0' + n : n;
+ }
+ return d.getUTCFullYear()+'-'
+ + pad(d.getUTCMonth()+1)+'-'
+ + pad(d.getUTCDate())+'T'
+ + pad(d.getUTCHours())+':'
+ + pad(d.getUTCMinutes())+':'
+ + pad(d.getUTCSeconds())+'Z';
+}
+
+/**
+ * Returns the internal "type" of `obj` via the
+ * `Object.prototype.toString()` trick.
+ *
+ * @param {Mixed} obj - any value
+ * @returns {String} the internal "type" name
+ * @api private
+ */
+
+var toString = Object.prototype.toString;
+function type (obj) {
+ var m = toString.call(obj).match(/\[object (.*)\]/);
+ return m ? m[1] : m;
+}
+
+/**
+ * Generate an XML plist string from the input object `obj`.
+ *
+ * @param {Object} obj - the object to convert
+ * @param {Object} [opts] - optional options object
+ * @returns {String} converted plist XML string
+ * @api public
+ */
+
+function build (obj, opts) {
+ var XMLHDR = {
+ version: '1.0',
+ encoding: 'UTF-8'
+ };
+
+ var XMLDTD = {
+ pubid: '-//Apple//DTD PLIST 1.0//EN',
+ sysid: 'http://www.apple.com/DTDs/PropertyList-1.0.dtd'
+ };
+
+ var doc = xmlbuilder.create('plist');
+
+ doc.dec(XMLHDR.version, XMLHDR.encoding, XMLHDR.standalone);
+ doc.dtd(XMLDTD.pubid, XMLDTD.sysid);
+ doc.att('version', '1.0');
+
+ walk_obj(obj, doc);
+
+ if (!opts) opts = {};
+ // default `pretty` to `true`
+ opts.pretty = opts.pretty !== false;
+ return doc.end(opts);
+}
+
+/**
+ * depth first, recursive traversal of a javascript object. when complete,
+ * next_child contains a reference to the build XML object.
+ *
+ * @api private
+ */
+
+function walk_obj(next, next_child) {
+ var tag_type, i, prop;
+ var name = type(next);
+
+ if ('Undefined' == name) {
+ return;
+ } else if (Array.isArray(next)) {
+ next_child = next_child.ele('array');
+ for (i = 0; i < next.length; i++) {
+ walk_obj(next[i], next_child);
+ }
+
+ } else if (Buffer.isBuffer(next)) {
+ next_child.ele('data').raw(next.toString('base64'));
+
+ } else if ('Object' == name) {
+ next_child = next_child.ele('dict');
+ for (prop in next) {
+ if (next.hasOwnProperty(prop)) {
+ next_child.ele('key').txt(prop);
+ walk_obj(next[prop], next_child);
+ }
+ }
+
+ } else if ('Number' == name) {
+ // detect if this is an integer or real
+ // TODO: add an ability to force one way or another via a "cast"
+ tag_type = (next % 1 === 0) ? 'integer' : 'real';
+ next_child.ele(tag_type).txt(next.toString());
+
+ } else if ('Date' == name) {
+ next_child.ele('date').txt(ISODateString(new Date(next)));
+
+ } else if ('Boolean' == name) {
+ next_child.ele(next ? 'true' : 'false');
+
+ } else if ('String' == name) {
+ next_child.ele('string').txt(next);
+
+ } else if ('ArrayBuffer' == name) {
+ next_child.ele('data').raw(base64.fromByteArray(next));
+
+ } else if (next && next.buffer && 'ArrayBuffer' == type(next.buffer)) {
+ // a typed array
+ next_child.ele('data').raw(base64.fromByteArray(new Uint8Array(next.buffer), next_child));
+
+ }
+}
http://git-wip-us.apache.org/repos/asf/cordova-windows/blob/3aca1d87/node_modules/plist/lib/node.js
----------------------------------------------------------------------
diff --git a/node_modules/plist/lib/node.js b/node_modules/plist/lib/node.js
new file mode 100644
index 0000000..ac18e32
--- /dev/null
+++ b/node_modules/plist/lib/node.js
@@ -0,0 +1,49 @@
+/**
+ * Module dependencies.
+ */
+
+var fs = require('fs');
+var parse = require('./parse');
+var deprecate = require('util-deprecate');
+
+/**
+ * Module exports.
+ */
+
+exports.parseFile = deprecate(parseFile, '`parseFile()` is deprecated. ' +
+ 'Use `parseString()` instead.');
+exports.parseFileSync = deprecate(parseFileSync, '`parseFileSync()` is deprecated. ' +
+ 'Use `parseStringSync()` instead.');
+
+/**
+ * Parses file `filename` as a .plist file.
+ * Invokes `fn` callback function when done.
+ *
+ * @param {String} filename - name of the file to read
+ * @param {Function} fn - callback function
+ * @api public
+ * @deprecated use parseString() instead
+ */
+
+function parseFile (filename, fn) {
+ fs.readFile(filename, { encoding: 'utf8' }, onread);
+ function onread (err, inxml) {
+ if (err) return fn(err);
+ parse.parseString(inxml, fn);
+ }
+}
+
+/**
+ * Parses file `filename` as a .plist file.
+ * Returns a when done.
+ *
+ * @param {String} filename - name of the file to read
+ * @param {Function} fn - callback function
+ * @api public
+ * @deprecated use parseStringSync() instead
+ */
+
+function parseFileSync (filename) {
+ var inxml = fs.readFileSync(filename, 'utf8');
+ return parse.parseStringSync(inxml);
+}
http://git-wip-us.apache.org/repos/asf/cordova-windows/blob/3aca1d87/node_modules/plist/lib/parse.js
----------------------------------------------------------------------
diff --git a/node_modules/plist/lib/parse.js b/node_modules/plist/lib/parse.js
new file mode 100644
index 0000000..c154384
--- /dev/null
+++ b/node_modules/plist/lib/parse.js
@@ -0,0 +1,200 @@
+
+/**
+ * Module dependencies.
+ */
+
+var deprecate = require('util-deprecate');
+var DOMParser = require('xmldom').DOMParser;
+
+/**
+ * Module exports.
+ */
+
+exports.parse = parse;
+exports.parseString = deprecate(parseString, '`parseString()` is deprecated. ' +
+ 'It\'s not actually async. Use `parse()` instead.');
+exports.parseStringSync = deprecate(parseStringSync, '`parseStringSync()` is ' +
+ 'deprecated. Use `parse()` instead.');
+
+/**
+ * We ignore raw text (usually whitespace), <!-- xml comments -->,
+ * and raw CDATA nodes.
+ *
+ * @param {Element} node
+ * @returns {Boolean}
+ * @api private
+ */
+
+function shouldIgnoreNode (node) {
+ return node.nodeType === 3 // text
+ || node.nodeType === 8 // comment
+ || node.nodeType === 4; // cdata
+}
+
+
+/**
+ * Parses a Plist XML string. Returns an Object.
+ *
+ * @param {String} xml - the XML String to decode
+ * @returns {Mixed} the decoded value from the Plist XML
+ * @api public
+ */
+
+function parse (xml) {
+ var doc = new DOMParser().parseFromString(xml);
+ if (doc.documentElement.nodeName !== 'plist') {
+ throw new Error('malformed document. First element should be <plist>');
+ }
+ var plist = parsePlistXML(doc.documentElement);
+
+ // the root <plist> node gets interpreted as an Array,
+ // so pull out the inner data first
+ if (plist.length == 1) plist = plist[0];
+
+ return plist;
+}
+
+/**
+ * Parses a Plist XML string. Returns an Object. Takes a `callback` function.
+ *
+ * @param {String} xml - the XML String to decode
+ * @param {Function} callback - callback function
+ * @returns {Mixed} the decoded value from the Plist XML
+ * @api public
+ * @deprecated not actually async. use parse() instead
+ */
+
+function parseString (xml, callback) {
+ var doc, error, plist;
+ try {
+ doc = new DOMParser().parseFromString(xml);
+ plist = parsePlistXML(doc.documentElement);
+ } catch(e) {
+ error = e;
+ }
+ callback(error, plist);
+}
+
+/**
+ * Parses a Plist XML string. Returns an Object.
+ *
+ * @param {String} xml - the XML String to decode
+ * @param {Function} callback - callback function
+ * @returns {Mixed} the decoded value from the Plist XML
+ * @api public
+ * @deprecated use parse() instead
+ */
+
+function parseStringSync (xml) {
+ var doc = new DOMParser().parseFromString(xml);
+ var plist;
+ if (doc.documentElement.nodeName !== 'plist') {
+ throw new Error('malformed document. First element should be <plist>');
+ }
+ plist = parsePlistXML(doc.documentElement);
+
+ // if the plist is an array with 1 element, pull it out of the array
+ if (plist.length == 1) {
+ plist = plist[0];
+ }
+ return plist;
+}
+
+/**
+ * Convert an XML based plist document into a JSON representation.
+ *
+ * @param {Object} xml_node - current XML node in the plist
+ * @returns {Mixed} built up JSON object
+ * @api private
+ */
+
+function parsePlistXML (node) {
+ var i, new_obj, key, val, new_arr, res, d;
+
+ if (!node)
+ return null;
+
+ if (node.nodeName === 'plist') {
+ new_arr = [];
+ for (i=0; i < node.childNodes.length; i++) {
+ // ignore comment nodes (text)
+ if (!shouldIgnoreNode(node.childNodes[i])) {
+ new_arr.push( parsePlistXML(node.childNodes[i]));
+ }
+ }
+ return new_arr;
+
+ } else if (node.nodeName === 'dict') {
+ new_obj = {};
+ key = null;
+ for (i=0; i < node.childNodes.length; i++) {
+ // ignore comment nodes (text)
+ if (!shouldIgnoreNode(node.childNodes[i])) {
+ if (key === null) {
+ key = parsePlistXML(node.childNodes[i]);
+ } else {
+ new_obj[key] = parsePlistXML(node.childNodes[i]);
+ key = null;
+ }
+ }
+ }
+ return new_obj;
+
+ } else if (node.nodeName === 'array') {
+ new_arr = [];
+ for (i=0; i < node.childNodes.length; i++) {
+ // ignore comment nodes (text)
+ if (!shouldIgnoreNode(node.childNodes[i])) {
+ res = parsePlistXML(node.childNodes[i]);
+ if (null != res) new_arr.push(res);
+ }
+ }
+ return new_arr;
+
+ } else if (node.nodeName === '#text') {
+ // TODO: what should we do with text types? (CDATA sections)
+
+ } else if (node.nodeName === 'key') {
+ return node.childNodes[0].nodeValue;
+
+ } else if (node.nodeName === 'string') {
+ res = '';
+ for (d=0; d < node.childNodes.length; d++) {
+ res += node.childNodes[d].nodeValue;
+ }
+ return res;
+
+ } else if (node.nodeName === 'integer') {
+ // parse as base 10 integer
+ return parseInt(node.childNodes[0].nodeValue, 10);
+
+ } else if (node.nodeName === 'real') {
+ res = '';
+ for (d=0; d < node.childNodes.length; d++) {
+ if (node.childNodes[d].nodeType === 3) {
+ res += node.childNodes[d].nodeValue;
+ }
+ }
+ return parseFloat(res);
+
+ } else if (node.nodeName === 'data') {
+ res = '';
+ for (d=0; d < node.childNodes.length; d++) {
+ if (node.childNodes[d].nodeType === 3) {
+ res += node.childNodes[d].nodeValue.replace(/\s+/g, '');
+ }
+ }
+
+ // decode base64 data to a Buffer instance
+ return new Buffer(res, 'base64');
+
+ } else if (node.nodeName === 'date') {
+ return new Date(node.childNodes[0].nodeValue);
+
+ } else if (node.nodeName === 'true') {
+ return true;
+
+ } else if (node.nodeName === 'false') {
+ return false;
+ }
+}
http://git-wip-us.apache.org/repos/asf/cordova-windows/blob/3aca1d87/node_modules/plist/lib/plist.js
----------------------------------------------------------------------
diff --git a/node_modules/plist/lib/plist.js b/node_modules/plist/lib/plist.js
new file mode 100644
index 0000000..00a4167
--- /dev/null
+++ b/node_modules/plist/lib/plist.js
@@ -0,0 +1,23 @@
+
+var i;
+
+/**
+ * Parser functions.
+ */
+
+var parserFunctions = require('./parse');
+for (i in parserFunctions) exports[i] = parserFunctions[i];
+
+/**
+ * Builder functions.
+ */
+
+var builderFunctions = require('./build');
+for (i in builderFunctions) exports[i] = builderFunctions[i];
+
+/**
+ * Add Node.js-specific functions (they're deprecated\u2026).
+ */
+
+var nodeFunctions = require('./node');
+for (i in nodeFunctions) exports[i] = nodeFunctions[i];
http://git-wip-us.apache.org/repos/asf/cordova-windows/blob/3aca1d87/node_modules/plist/package.json
----------------------------------------------------------------------
diff --git a/node_modules/plist/package.json b/node_modules/plist/package.json
new file mode 100644
index 0000000..9e93934
--- /dev/null
+++ b/node_modules/plist/package.json
@@ -0,0 +1,126 @@
+{
+ "_args": [
+ [
+ {
+ "raw": "plist@^1.2.0",
+ "scope": null,
+ "escapedName": "plist",
+ "name": "plist",
+ "rawSpec": "^1.2.0",
+ "spec": ">=1.2.0 <2.0.0",
+ "type": "range"
+ },
+ "d:\\cordova\\cordova-windows\\node_modules\\cordova-common"
+ ]
+ ],
+ "_from": "plist@>=1.2.0 <2.0.0",
+ "_id": "plist@1.2.0",
+ "_inCache": true,
+ "_installable": true,
+ "_location": "/plist",
+ "_nodeVersion": "5.0.0",
+ "_npmUser": {
+ "name": "mreinstein",
+ "email": "reinstein.mike@gmail.com"
+ },
+ "_npmVersion": "3.3.11",
+ "_phantomChildren": {},
+ "_requested": {
+ "raw": "plist@^1.2.0",
+ "scope": null,
+ "escapedName": "plist",
+ "name": "plist",
+ "rawSpec": "^1.2.0",
+ "spec": ">=1.2.0 <2.0.0",
+ "type": "range"
+ },
+ "_requiredBy": [
+ "/cordova-common"
+ ],
+ "_resolved": "https://registry.npmjs.org/plist/-/plist-1.2.0.tgz",
+ "_shasum": "084b5093ddc92506e259f874b8d9b1afb8c79593",
+ "_shrinkwrap": null,
+ "_spec": "plist@^1.2.0",
+ "_where": "d:\\cordova\\cordova-windows\\node_modules\\cordova-common",
+ "author": {
+ "name": "Nathan Rajlich",
+ "email": "nathan@tootallnate.net"
+ },
+ "bugs": {
+ "url": "https://github.com/TooTallNate/node-plist/issues"
+ },
+ "contributors": [
+ {
+ "name": "Hans Huebner",
+ "email": "hans.huebner@gmail.com"
+ },
+ {
+ "name": "Pierre Metrailler"
+ },
+ {
+ "name": "Mike Reinstein",
+ "email": "reinstein.mike@gmail.com"
+ },
+ {
+ "name": "Vladimir Tsvang"
+ },
+ {
+ "name": "Mathieu D'Amours"
+ }
+ ],
+ "dependencies": {
+ "base64-js": "0.0.8",
+ "util-deprecate": "1.0.2",
+ "xmlbuilder": "4.0.0",
+ "xmldom": "0.1.x"
+ },
+ "description": "Mac OS X Plist parser/builder for Node.js and browsers",
+ "devDependencies": {
+ "browserify": "12.0.1",
+ "mocha": "2.3.3",
+ "multiline": "1.0.2",
+ "zuul": "3.7.2"
+ },
+ "directories": {},
+ "dist": {
+ "shasum": "084b5093ddc92506e259f874b8d9b1afb8c79593",
+ "tarball": "https://registry.npmjs.org/plist/-/plist-1.2.0.tgz"
+ },
+ "gitHead": "69520574f27864145192338b72e608fbe1bda6f7",
+ "homepage": "https://github.com/TooTallNate/node-plist#readme",
+ "keywords": [
+ "apple",
+ "browser",
+ "mac",
+ "plist",
+ "parser",
+ "xml"
+ ],
+ "license": "MIT",
+ "main": "lib/plist.js",
+ "maintainers": [
+ {
+ "name": "TooTallNate",
+ "email": "nathan@tootallnate.net"
+ },
+ {
+ "name": "tootallnate",
+ "email": "nathan@tootallnate.net"
+ },
+ {
+ "name": "mreinstein",
+ "email": "reinstein.mike@gmail.com"
+ }
+ ],
+ "name": "plist",
+ "optionalDependencies": {},
+ "readme": "ERROR: No README data found!",
+ "repository": {
+ "type": "git",
+ "url": "git://github.com/TooTallNate/node-plist.git"
+ },
+ "scripts": {
+ "test": "make test"
+ },
+ "version": "1.2.0"
+}
http://git-wip-us.apache.org/repos/asf/cordova-windows/blob/3aca1d87/node_modules/q/package.json
----------------------------------------------------------------------
diff --git a/node_modules/q/package.json b/node_modules/q/package.json
index e48d757..5986038 100644
--- a/node_modules/q/package.json
+++ b/node_modules/q/package.json
@@ -1,27 +1,56 @@
{
- "name": "q",
- "version": "1.4.1",
- "description": "A library for promises (CommonJS/Promises/A,B,D)",
- "homepage": "https://github.com/kriskowal/q",
+ "_args": [
+ [
+ {
+ "raw": "q@^1.4.1",
+ "scope": null,
+ "escapedName": "q",
+ "name": "q",
+ "rawSpec": "^1.4.1",
+ "spec": ">=1.4.1 <2.0.0",
+ "type": "range"
+ },
+ "d:\\cordova\\cordova-windows"
+ ]
+ ],
+ "_from": "q@>=1.4.1 <2.0.0",
+ "_id": "q@1.4.1",
+ "_inCache": true,
+ "_installable": true,
+ "_location": "/q",
+ "_nodeVersion": "1.8.1",
+ "_npmUser": {
+ "name": "kriskowal",
+ "email": "kris.kowal@cixar.com"
+ },
+ "_npmVersion": "2.8.3",
+ "_phantomChildren": {},
+ "_requested": {
+ "raw": "q@^1.4.1",
+ "scope": null,
+ "escapedName": "q",
+ "name": "q",
+ "rawSpec": "^1.4.1",
+ "spec": ">=1.4.1 <2.0.0",
+ "type": "range"
+ },
+ "_requiredBy": [
+ "/",
+ "/cordova-common"
+ ],
+ "_resolved": "https://registry.npmjs.org/q/-/q-1.4.1.tgz",
+ "_shasum": "55705bcd93c5f3673530c2c2cbc0c2b3addc286e",
+ "_shrinkwrap": null,
+ "_spec": "q@^1.4.1",
+ "_where": "d:\\cordova\\cordova-windows",
"author": {
"name": "Kris Kowal",
"email": "kris@cixar.com",
"url": "https://github.com/kriskowal"
},
- "keywords": [
- "q",
- "promise",
- "promises",
- "promises-a",
- "promises-aplus",
- "deferred",
- "future",
- "async",
- "flow control",
- "fluent",
- "browser",
- "node"
- ],
+ "bugs": {
+ "url": "http://github.com/kriskowal/q/issues"
+ },
"contributors": [
{
"name": "Kris Kowal",
@@ -39,28 +68,8 @@
"url": "http://domenicdenicola.com"
}
],
- "bugs": {
- "url": "http://github.com/kriskowal/q/issues"
- },
- "license": {
- "type": "MIT",
- "url": "http://github.com/kriskowal/q/raw/master/LICENSE"
- },
- "main": "q.js",
- "files": [
- "LICENSE",
- "q.js",
- "queue.js"
- ],
- "repository": {
- "type": "git",
- "url": "git://github.com/kriskowal/q.git"
- },
- "engines": {
- "node": ">=0.6.0",
- "teleport": ">=0.2.0"
- },
"dependencies": {},
+ "description": "A library for promises (CommonJS/Promises/A,B,D)",
"devDependencies": {
"cover": "*",
"grunt": "~0.4.1",
@@ -72,15 +81,55 @@
"opener": "*",
"promises-aplus-tests": "1.x"
},
- "scripts": {
- "test": "jasmine-node spec && promises-aplus-tests spec/aplus-adapter",
- "test-browser": "opener spec/q-spec.html",
- "benchmark": "matcha",
- "lint": "jshint q.js",
- "cover": "cover run jasmine-node spec && cover report html && opener cover_html/index.html",
- "minify": "grunt",
- "prepublish": "grunt"
+ "directories": {
+ "test": "./spec"
+ },
+ "dist": {
+ "shasum": "55705bcd93c5f3673530c2c2cbc0c2b3addc286e",
+ "tarball": "https://registry.npmjs.org/q/-/q-1.4.1.tgz"
+ },
+ "engines": {
+ "node": ">=0.6.0",
+ "teleport": ">=0.2.0"
+ },
+ "files": [
+ "LICENSE",
+ "q.js",
+ "queue.js"
+ ],
+ "gitHead": "d373079d3620152e3d60e82f27265a09ee0e81bd",
+ "homepage": "https://github.com/kriskowal/q",
+ "keywords": [
+ "q",
+ "promise",
+ "promises",
+ "promises-a",
+ "promises-aplus",
+ "deferred",
+ "future",
+ "async",
+ "flow control",
+ "fluent",
+ "browser",
+ "node"
+ ],
+ "license": {
+ "type": "MIT",
+ "url": "http://github.com/kriskowal/q/raw/master/LICENSE"
},
+ "main": "q.js",
+ "maintainers": [
+ {
+ "name": "kriskowal",
+ "email": "kris.kowal@cixar.com"
+ },
+ {
+ "name": "domenic",
+ "email": "domenic@domenicdenicola.com"
+ }
+ ],
+ "name": "q",
+ "optionalDependencies": {},
"overlay": {
"teleport": {
"dependencies": {
@@ -88,13 +137,19 @@
}
}
},
- "directories": {
- "test": "./spec"
+ "readme": "ERROR: No README data found!",
+ "repository": {
+ "type": "git",
+ "url": "git://github.com/kriskowal/q.git"
},
- "readme": "[](http://travis-ci.org/kriskowal/q)\n\n<a href=\"http://promises-aplus.github.com/promises-spec\">\n <img src=\"http://kriskowal.github.io/q/q.png\"\n align=\"right\" alt=\"Q logo\" />\n</a>\n\n*This is Q version 1, from the `v1` branch in Git. This documentation applies to\nthe latest of both the version 1 and version 0.9 release trains. These releases\nare stable. There will be no further releases of 0.9 after 0.9.7 which is nearly\nequivalent to version 1.0.0. All further releases of `q@~1.0` will be backward\ncompatible. The version 2 release train introduces significant and\nbackward-incompatible changes and is experimental at this time.*\n\nIf a function cannot return a value or throw an exception without\nblocking, it can return a promise instead. A promise is an object\nthat represents the return value or the thrown exception that the\nfunction may eventually provide. A prom
ise can also be used as a\nproxy for a [remote object][Q-Connection] to overcome latency.\n\n[Q-Connection]: https://github.com/kriskowal/q-connection\n\nOn the first pass, promises can mitigate the \u201c[Pyramid of\nDoom][POD]\u201d: the situation where code marches to the right faster\nthan it marches forward.\n\n[POD]: http://calculist.org/blog/2011/12/14/why-coroutines-wont-work-on-the-web/\n\n```javascript\nstep1(function (value1) {\n step2(value1, function(value2) {\n step3(value2, function(value3) {\n step4(value3, function(value4) {\n // Do something with value4\n });\n });\n });\n});\n```\n\nWith a promise library, you can flatten the pyramid.\n\n```javascript\nQ.fcall(promisedStep1)\n.then(promisedStep2)\n.then(promisedStep3)\n.then(promisedStep4)\n.then(function (value4) {\n // Do something with value4\n})\n.catch(function (error) {\n // Handle any error from all above steps\n})\n.done();\n```\n\nWith this approach
, you also get implicit error propagation, just like `try`,\n`catch`, and `finally`. An error in `promisedStep1` will flow all the way to\nthe `catch` function, where it\u2019s caught and handled. (Here `promisedStepN` is\na version of `stepN` that returns a promise.)\n\nThe callback approach is called an \u201cinversion of control\u201d.\nA function that accepts a callback instead of a return value\nis saying, \u201cDon\u2019t call me, I\u2019ll call you.\u201d. Promises\n[un-invert][IOC] the inversion, cleanly separating the input\narguments from control flow arguments. This simplifies the\nuse and creation of API\u2019s, particularly variadic,\nrest and spread arguments.\n\n[IOC]: http://www.slideshare.net/domenicdenicola/callbacks-promises-and-coroutines-oh-my-the-evolution-of-asynchronicity-in-javascript\n\n\n## Getting Started\n\nThe Q module can be loaded as:\n\n- A ``<script>`` tag (creating a ``Q`` global variable): ~2.5 KB minified and\n gzipped.\n- A Node.js and CommonJS module, avail
able in [npm](https://npmjs.org/) as\n the [q](https://npmjs.org/package/q) package\n- An AMD module\n- A [component](https://github.com/component/component) as ``microjs/q``\n- Using [bower](http://bower.io/) as `q#1.0.1`\n- Using [NuGet](http://nuget.org/) as [Q](https://nuget.org/packages/q)\n\nQ can exchange promises with jQuery, Dojo, When.js, WinJS, and more.\n\n## Resources\n\nOur [wiki][] contains a number of useful resources, including:\n\n- A method-by-method [Q API reference][reference].\n- A growing [examples gallery][examples], showing how Q can be used to make\n everything better. From XHR to database access to accessing the Flickr API,\n Q is there for you.\n- There are many libraries that produce and consume Q promises for everything\n from file system/database access or RPC to templating. For a list of some of\n the more popular ones, see [Libraries][].\n- If you want materials that introduce the promise concept generally, and the\n below tutorial is
n't doing it for you, check out our collection of\n [presentations, blog posts, and podcasts][resources].\n- A guide for those [coming from jQuery's `$.Deferred`][jquery].\n\nWe'd also love to have you join the Q-Continuum [mailing list][].\n\n[wiki]: https://github.com/kriskowal/q/wiki\n[reference]: https://github.com/kriskowal/q/wiki/API-Reference\n[examples]: https://github.com/kriskowal/q/wiki/Examples-Gallery\n[Libraries]: https://github.com/kriskowal/q/wiki/Libraries\n[resources]: https://github.com/kriskowal/q/wiki/General-Promise-Resources\n[jquery]: https://github.com/kriskowal/q/wiki/Coming-from-jQuery\n[mailing list]: https://groups.google.com/forum/#!forum/q-continuum\n\n\n## Tutorial\n\nPromises have a ``then`` method, which you can use to get the eventual\nreturn value (fulfillment) or thrown exception (rejection).\n\n```javascript\npromiseMeSomething()\n.then(function (value) {\n}, function (reason) {\n});\n```\n\nIf ``promiseMeSomething`` returns a promise that gets
fulfilled later\nwith a return value, the first function (the fulfillment handler) will be\ncalled with the value. However, if the ``promiseMeSomething`` function\ngets rejected later by a thrown exception, the second function (the\nrejection handler) will be called with the exception.\n\nNote that resolution of a promise is always asynchronous: that is, the\nfulfillment or rejection handler will always be called in the next turn of the\nevent loop (i.e. `process.nextTick` in Node). This gives you a nice\nguarantee when mentally tracing the flow of your code, namely that\n``then`` will always return before either handler is executed.\n\nIn this tutorial, we begin with how to consume and work with promises. We'll\ntalk about how to create them, and thus create functions like\n`promiseMeSomething` that return promises, [below](#the-beginning).\n\n\n### Propagation\n\nThe ``then`` method returns a promise, which in this example, I\u2019m\nassigning to ``outputPromise``.\n\n```javascript
\nvar outputPromise = getInputPromise()\n.then(function (input) {\n}, function (reason) {\n});\n```\n\nThe ``outputPromise`` variable becomes a new promise for the return\nvalue of either handler. Since a function can only either return a\nvalue or throw an exception, only one handler will ever be called and it\nwill be responsible for resolving ``outputPromise``.\n\n- If you return a value in a handler, ``outputPromise`` will get\n fulfilled.\n\n- If you throw an exception in a handler, ``outputPromise`` will get\n rejected.\n\n- If you return a **promise** in a handler, ``outputPromise`` will\n \u201cbecome\u201d that promise. Being able to become a new promise is useful\n for managing delays, combining results, or recovering from errors.\n\nIf the ``getInputPromise()`` promise gets rejected and you omit the\nrejection handler, the **error** will go to ``outputPromise``:\n\n```javascript\nvar outputPromise = getInputPromise()\n.then(function (value) {\n});\n```\n\nIf
the input promise gets fulfilled and you omit the fulfillment handler, the\n**value** will go to ``outputPromise``:\n\n```javascript\nvar outputPromise = getInputPromise()\n.then(null, function (error) {\n});\n```\n\nQ promises provide a ``fail`` shorthand for ``then`` when you are only\ninterested in handling the error:\n\n```javascript\nvar outputPromise = getInputPromise()\n.fail(function (error) {\n});\n```\n\nIf you are writing JavaScript for modern engines only or using\nCoffeeScript, you may use `catch` instead of `fail`.\n\nPromises also have a ``fin`` function that is like a ``finally`` clause.\nThe final handler gets called, with no arguments, when the promise\nreturned by ``getInputPromise()`` either returns a value or throws an\nerror. The value returned or error thrown by ``getInputPromise()``\npasses directly to ``outputPromise`` unless the final handler fails, and\nmay be delayed if the final handler returns a promise.\n\n```javascript\nvar outputPromise = getInputP
romise()\n.fin(function () {\n // close files, database connections, stop servers, conclude tests\n});\n```\n\n- If the handler returns a value, the value is ignored\n- If the handler throws an error, the error passes to ``outputPromise``\n- If the handler returns a promise, ``outputPromise`` gets postponed. The\n eventual value or error has the same effect as an immediate return\n value or thrown error: a value would be ignored, an error would be\n forwarded.\n\nIf you are writing JavaScript for modern engines only or using\nCoffeeScript, you may use `finally` instead of `fin`.\n\n### Chaining\n\nThere are two ways to chain promises. You can chain promises either\ninside or outside handlers. The next two examples are equivalent.\n\n```javascript\nreturn getUsername()\n.then(function (username) {\n return getUser(username)\n .then(function (user) {\n // if we get here without an error,\n // the value returned here\n // or the exception
thrown here\n // resolves the promise returned\n // by the first line\n })\n});\n```\n\n```javascript\nreturn getUsername()\n.then(function (username) {\n return getUser(username);\n})\n.then(function (user) {\n // if we get here without an error,\n // the value returned here\n // or the exception thrown here\n // resolves the promise returned\n // by the first line\n});\n```\n\nThe only difference is nesting. It\u2019s useful to nest handlers if you\nneed to capture multiple input values in your closure.\n\n```javascript\nfunction authenticate() {\n return getUsername()\n .then(function (username) {\n return getUser(username);\n })\n // chained because we will not need the user name in the next event\n .then(function (user) {\n return getPassword()\n // nested because we need both user and password next\n .then(function (password) {\n if (user.passwordHash !== hash(password)) {\n
throw new Error(\"Can't authenticate\");\n }\n });\n });\n}\n```\n\n\n### Combination\n\nYou can turn an array of promises into a promise for the whole,\nfulfilled array using ``all``.\n\n```javascript\nreturn Q.all([\n eventualAdd(2, 2),\n eventualAdd(10, 20)\n]);\n```\n\nIf you have a promise for an array, you can use ``spread`` as a\nreplacement for ``then``. The ``spread`` function \u201cspreads\u201d the\nvalues over the arguments of the fulfillment handler. The rejection handler\nwill get called at the first sign of failure. That is, whichever of\nthe received promises fails first gets handled by the rejection handler.\n\n```javascript\nfunction eventualAdd(a, b) {\n return Q.spread([a, b], function (a, b) {\n return a + b;\n })\n}\n```\n\nBut ``spread`` calls ``all`` initially, so you can skip it in chains.\n\n```javascript\nreturn getUsername()\n.then(function (username) {\n return [username, getUser(username)];\n})\n.spread(function (
username, user) {\n});\n```\n\nThe ``all`` function returns a promise for an array of values. When this\npromise is fulfilled, the array contains the fulfillment values of the original\npromises, in the same order as those promises. If one of the given promises\nis rejected, the returned promise is immediately rejected, not waiting for the\nrest of the batch. If you want to wait for all of the promises to either be\nfulfilled or rejected, you can use ``allSettled``.\n\n```javascript\nQ.allSettled(promises)\n.then(function (results) {\n results.forEach(function (result) {\n if (result.state === \"fulfilled\") {\n var value = result.value;\n } else {\n var reason = result.reason;\n }\n });\n});\n```\n\nThe ``any`` function accepts an array of promises and returns a promise that is\nfulfilled by the first given promise to be fulfilled, or rejected if all of the\ngiven promises are rejected.\n\n```javascript\nQ.any(promises)\n.then(fun
ction (first) {\n // Any of the promises was fulfilled.\n}, function (error) {\n // All of the promises were rejected.\n});\n```\n\n### Sequences\n\nIf you have a number of promise-producing functions that need\nto be run sequentially, you can of course do so manually:\n\n```javascript\nreturn foo(initialVal).then(bar).then(baz).then(qux);\n```\n\nHowever, if you want to run a dynamically constructed sequence of\nfunctions, you'll want something like this:\n\n```javascript\nvar funcs = [foo, bar, baz, qux];\n\nvar result = Q(initialVal);\nfuncs.forEach(function (f) {\n result = result.then(f);\n});\nreturn result;\n```\n\nYou can make this slightly more compact using `reduce`:\n\n```javascript\nreturn funcs.reduce(function (soFar, f) {\n return soFar.then(f);\n}, Q(initialVal));\n```\n\nOr, you could use the ultra-compact version:\n\n```javascript\nreturn funcs.reduce(Q.when, Q(initialVal));\n```\n\n### Handling Errors\n\nOne sometimes-unintuive aspect of promises is tha
t if you throw an\nexception in the fulfillment handler, it will not be caught by the error\nhandler.\n\n```javascript\nreturn foo()\n.then(function (value) {\n throw new Error(\"Can't bar.\");\n}, function (error) {\n // We only get here if \"foo\" fails\n});\n```\n\nTo see why this is, consider the parallel between promises and\n``try``/``catch``. We are ``try``-ing to execute ``foo()``: the error\nhandler represents a ``catch`` for ``foo()``, while the fulfillment handler\nrepresents code that happens *after* the ``try``/``catch`` block.\nThat code then needs its own ``try``/``catch`` block.\n\nIn terms of promises, this means chaining your rejection handler:\n\n```javascript\nreturn foo()\n.then(function (value) {\n throw new Error(\"Can't bar.\");\n})\n.fail(function (error) {\n // We get here with either foo's error or bar's error\n});\n```\n\n### Progress Notification\n\nIt's possible for promises to report their progress, e.g. for tasks that take a\nlong time lik
e a file upload. Not all promises will implement progress\nnotifications, but for those that do, you can consume the progress values using\na third parameter to ``then``:\n\n```javascript\nreturn uploadFile()\n.then(function () {\n // Success uploading the file\n}, function (err) {\n // There was an error, and we get the reason for error\n}, function (progress) {\n // We get notified of the upload's progress as it is executed\n});\n```\n\nLike `fail`, Q also provides a shorthand for progress callbacks\ncalled `progress`:\n\n```javascript\nreturn uploadFile().progress(function (progress) {\n // We get notified of the upload's progress\n});\n```\n\n### The End\n\nWhen you get to the end of a chain of promises, you should either\nreturn the last promise or end the chain. Since handlers catch\nerrors, it\u2019s an unfortunate pattern that the exceptions can go\nunobserved.\n\nSo, either return it,\n\n```javascript\nreturn foo()\n.then(function () {\n return \"bar\";\n});\n`
``\n\nOr, end it.\n\n```javascript\nfoo()\n.then(function () {\n return \"bar\";\n})\n.done();\n```\n\nEnding a promise chain makes sure that, if an error doesn\u2019t get\nhandled before the end, it will get rethrown and reported.\n\nThis is a stopgap. We are exploring ways to make unhandled errors\nvisible without any explicit handling.\n\n\n### The Beginning\n\nEverything above assumes you get a promise from somewhere else. This\nis the common case. Every once in a while, you will need to create a\npromise from scratch.\n\n#### Using ``Q.fcall``\n\nYou can create a promise from a value using ``Q.fcall``. This returns a\npromise for 10.\n\n```javascript\nreturn Q.fcall(function () {\n return 10;\n});\n```\n\nYou can also use ``fcall`` to get a promise for an exception.\n\n```javascript\nreturn Q.fcall(function () {\n throw new Error(\"Can't do it\");\n});\n```\n\nAs the name implies, ``fcall`` can call functions, or even promised\nfunctions. This uses the ``eventualAdd``
function above to add two\nnumbers.\n\n```javascript\nreturn Q.fcall(eventualAdd, 2, 2);\n```\n\n\n#### Using Deferreds\n\nIf you have to interface with asynchronous functions that are callback-based\ninstead of promise-based, Q provides a few shortcuts (like ``Q.nfcall`` and\nfriends). But much of the time, the solution will be to use *deferreds*.\n\n```javascript\nvar deferred = Q.defer();\nFS.readFile(\"foo.txt\", \"utf-8\", function (error, text) {\n if (error) {\n deferred.reject(new Error(error));\n } else {\n deferred.resolve(text);\n }\n});\nreturn deferred.promise;\n```\n\nNote that a deferred can be resolved with a value or a promise. The\n``reject`` function is a shorthand for resolving with a rejected\npromise.\n\n```javascript\n// this:\ndeferred.reject(new Error(\"Can't do it\"));\n\n// is shorthand for:\nvar rejection = Q.fcall(function () {\n throw new Error(\"Can't do it\");\n});\ndeferred.resolve(rejection);\n```\n\nThis is a simplified
implementation of ``Q.delay``.\n\n```javascript\nfunction delay(ms) {\n var deferred = Q.defer();\n setTimeout(deferred.resolve, ms);\n return deferred.promise;\n}\n```\n\nThis is a simplified implementation of ``Q.timeout``\n\n```javascript\nfunction timeout(promise, ms) {\n var deferred = Q.defer();\n Q.when(promise, deferred.resolve);\n delay(ms).then(function () {\n deferred.reject(new Error(\"Timed out\"));\n });\n return deferred.promise;\n}\n```\n\nFinally, you can send a progress notification to the promise with\n``deferred.notify``.\n\nFor illustration, this is a wrapper for XML HTTP requests in the browser. Note\nthat a more [thorough][XHR] implementation would be in order in practice.\n\n[XHR]: https://github.com/montagejs/mr/blob/71e8df99bb4f0584985accd6f2801ef3015b9763/browser.js#L29-L73\n\n```javascript\nfunction requestOkText(url) {\n var request = new XMLHttpRequest();\n var deferred = Q.defer();\n\n request.open(\"GET\", url,
true);\n request.onload = onload;\n request.onerror = onerror;\n request.onprogress = onprogress;\n request.send();\n\n function onload() {\n if (request.status === 200) {\n deferred.resolve(request.responseText);\n } else {\n deferred.reject(new Error(\"Status code was \" + request.status));\n }\n }\n\n function onerror() {\n deferred.reject(new Error(\"Can't XHR \" + JSON.stringify(url)));\n }\n\n function onprogress(event) {\n deferred.notify(event.loaded / event.total);\n }\n\n return deferred.promise;\n}\n```\n\nBelow is an example of how to use this ``requestOkText`` function:\n\n```javascript\nrequestOkText(\"http://localhost:3000\")\n.then(function (responseText) {\n // If the HTTP response returns 200 OK, log the response text.\n console.log(responseText);\n}, function (error) {\n // If there's an error or a non-200 status code, log the error.\n console.error(error);\n}, fu
nction (progress) {\n // Log the progress as it comes in.\n console.log(\"Request progress: \" + Math.round(progress * 100) + \"%\");\n});\n```\n\n#### Using `Q.Promise`\n\nThis is an alternative promise-creation API that has the same power as\nthe deferred concept, but without introducing another conceptual entity.\n\nRewriting the `requestOkText` example above using `Q.Promise`:\n\n```javascript\nfunction requestOkText(url) {\n return Q.Promise(function(resolve, reject, notify) {\n var request = new XMLHttpRequest();\n\n request.open(\"GET\", url, true);\n request.onload = onload;\n request.onerror = onerror;\n request.onprogress = onprogress;\n request.send();\n\n function onload() {\n if (request.status === 200) {\n resolve(request.responseText);\n } else {\n reject(new Error(\"Status code was \" + request.status));\n }\n }\n\n function onerror()
{\n reject(new Error(\"Can't XHR \" + JSON.stringify(url)));\n }\n\n function onprogress(event) {\n notify(event.loaded / event.total);\n }\n });\n}\n```\n\nIf `requestOkText` were to throw an exception, the returned promise would be\nrejected with that thrown exception as the rejection reason.\n\n### The Middle\n\nIf you are using a function that may return a promise, but just might\nreturn a value if it doesn\u2019t need to defer, you can use the \u201cstatic\u201d\nmethods of the Q library.\n\nThe ``when`` function is the static equivalent for ``then``.\n\n```javascript\nreturn Q.when(valueOrPromise, function (value) {\n}, function (error) {\n});\n```\n\nAll of the other methods on a promise have static analogs with the\nsame name.\n\nThe following are equivalent:\n\n```javascript\nreturn Q.all([a, b]);\n```\n\n```javascript\nreturn Q.fcall(function () {\n return [a, b];\n})\n.all();\n```\n\nWhen working with promises provided by other lib
raries, you should\nconvert it to a Q promise. Not all promise libraries make the same\nguarantees as Q and certainly don\u2019t provide all of the same methods.\nMost libraries only provide a partially functional ``then`` method.\nThis thankfully is all we need to turn them into vibrant Q promises.\n\n```javascript\nreturn Q($.ajax(...))\n.then(function () {\n});\n```\n\nIf there is any chance that the promise you receive is not a Q promise\nas provided by your library, you should wrap it using a Q function.\nYou can even use ``Q.invoke`` as a shorthand.\n\n```javascript\nreturn Q.invoke($, 'ajax', ...)\n.then(function () {\n});\n```\n\n\n### Over the Wire\n\nA promise can serve as a proxy for another object, even a remote\nobject. There are methods that allow you to optimistically manipulate\nproperties or call functions. All of these interactions return\npromises, so they can be chained.\n\n```\ndirect manipulation using a promise as a proxy\n-------------------------- -
------------------------------\nvalue.foo promise.get(\"foo\")\nvalue.foo = value promise.put(\"foo\", value)\ndelete value.foo promise.del(\"foo\")\nvalue.foo(...args) promise.post(\"foo\", [args])\nvalue.foo(...args) promise.invoke(\"foo\", ...args)\nvalue(...args) promise.fapply([args])\nvalue(...args) promise.fcall(...args)\n```\n\nIf the promise is a proxy for a remote object, you can shave\nround-trips by using these functions instead of ``then``. To take\nadvantage of promises for remote objects, check out [Q-Connection][].\n\n[Q-Connection]: https://github.com/kriskowal/q-connection\n\nEven in the case of non-remote objects, these methods can be used as\nshorthand for particularly-simple fulfillment handlers. For example, you\ncan replace\n\n```javascript\nreturn Q.fcall(function () {\n return [{ foo: \"bar\" }, { foo: \"baz\" }];\n})\n.then(function (value) {\n return value[0].foo;\n})
;\n```\n\nwith\n\n```javascript\nreturn Q.fcall(function () {\n return [{ foo: \"bar\" }, { foo: \"baz\" }];\n})\n.get(0)\n.get(\"foo\");\n```\n\n\n### Adapting Node\n\nIf you're working with functions that make use of the Node.js callback pattern,\nwhere callbacks are in the form of `function(err, result)`, Q provides a few\nuseful utility functions for converting between them. The most straightforward\nare probably `Q.nfcall` and `Q.nfapply` (\"Node function call/apply\") for calling\nNode.js-style functions and getting back a promise:\n\n```javascript\nreturn Q.nfcall(FS.readFile, \"foo.txt\", \"utf-8\");\nreturn Q.nfapply(FS.readFile, [\"foo.txt\", \"utf-8\"]);\n```\n\nIf you are working with methods, instead of simple functions, you can easily\nrun in to the usual problems where passing a method to another function\u2014like\n`Q.nfcall`\u2014\"un-binds\" the method from its owner. To avoid this, you can either\nuse `Function.prototype.bind` or some nice shortcut methods we provide
:\n\n```javascript\nreturn Q.ninvoke(redisClient, \"get\", \"user:1:id\");\nreturn Q.npost(redisClient, \"get\", [\"user:1:id\"]);\n```\n\nYou can also create reusable wrappers with `Q.denodeify` or `Q.nbind`:\n\n```javascript\nvar readFile = Q.denodeify(FS.readFile);\nreturn readFile(\"foo.txt\", \"utf-8\");\n\nvar redisClientGet = Q.nbind(redisClient.get, redisClient);\nreturn redisClientGet(\"user:1:id\");\n```\n\nFinally, if you're working with raw deferred objects, there is a\n`makeNodeResolver` method on deferreds that can be handy:\n\n```javascript\nvar deferred = Q.defer();\nFS.readFile(\"foo.txt\", \"utf-8\", deferred.makeNodeResolver());\nreturn deferred.promise;\n```\n\n### Long Stack Traces\n\nQ comes with optional support for \u201clong stack traces,\u201d wherein the `stack`\nproperty of `Error` rejection reasons is rewritten to be traced along\nasynchronous jumps instead of stopping at the most recent one. As an example:\n\n```js\nfunction theDepthsOfMyProgram() {\n Q.dela
y(100).done(function explode() {\n throw new Error(\"boo!\");\n });\n}\n\ntheDepthsOfMyProgram();\n```\n\nusually would give a rather unhelpful stack trace looking something like\n\n```\nError: boo!\n at explode (/path/to/test.js:3:11)\n at _fulfilled (/path/to/test.js:q:54)\n at resolvedValue.promiseDispatch.done (/path/to/q.js:823:30)\n at makePromise.promise.promiseDispatch (/path/to/q.js:496:13)\n at pending (/path/to/q.js:397:39)\n at process.startup.processNextTick.process._tickCallback (node.js:244:9)\n```\n\nBut, if you turn this feature on by setting\n\n```js\nQ.longStackSupport = true;\n```\n\nthen the above code gives a nice stack trace to the tune of\n\n```\nError: boo!\n at explode (/path/to/test.js:3:11)\nFrom previous event:\n at theDepthsOfMyProgram (/path/to/test.js:2:16)\n at Object.<anonymous> (/path/to/test.js:7:1)\n```\n\nNote how you can see the function that triggered the async operation in the\nstack trace! This is very helpful
for debugging, as otherwise you end up getting\nonly the first line, plus a bunch of Q internals, with no sign of where the\noperation started.\n\nIn node.js, this feature can also be enabled through the Q_DEBUG environment\nvariable:\n\n```\nQ_DEBUG=1 node server.js\n```\n\nThis will enable long stack support in every instance of Q.\n\nThis feature does come with somewhat-serious performance and memory overhead,\nhowever. If you're working with lots of promises, or trying to scale a server\nto many users, you should probably keep it off. But in development, go for it!\n\n## Tests\n\nYou can view the results of the Q test suite [in your browser][tests]!\n\n[tests]: https://rawgithub.com/kriskowal/q/v1/spec/q-spec.html\n\n## License\n\nCopyright 2009\u20132015 Kristopher Michael Kowal and contributors\nMIT License (enclosed)\n\n",
- "readmeFilename": "README.md",
- "_id": "q@1.4.1",
- "_shasum": "55705bcd93c5f3673530c2c2cbc0c2b3addc286e",
- "_resolved": "https://registry.npmjs.org/q/-/q-1.4.1.tgz",
- "_from": "q@>=1.4.1 <2.0.0"
+ "scripts": {
+ "benchmark": "matcha",
+ "cover": "cover run jasmine-node spec && cover report html && opener cover_html/index.html",
+ "lint": "jshint q.js",
+ "minify": "grunt",
+ "prepublish": "grunt",
+ "test": "jasmine-node spec && promises-aplus-tests spec/aplus-adapter",
+ "test-browser": "opener spec/q-spec.html"
+ },
+ "version": "1.4.1"
}
http://git-wip-us.apache.org/repos/asf/cordova-windows/blob/3aca1d87/node_modules/sax/AUTHORS
----------------------------------------------------------------------
diff --git a/node_modules/sax/AUTHORS b/node_modules/sax/AUTHORS
new file mode 100644
index 0000000..26d8659
--- /dev/null
+++ b/node_modules/sax/AUTHORS
@@ -0,0 +1,9 @@
+# contributors sorted by whether or not they're me.
+Isaac Z. Schlueter <i...@izs.me>
+Stein Martin Hustad <st...@hustad.com>
+Mikeal Rogers <mi...@gmail.com>
+Laurie Harper <la...@holoweb.net>
+Jann Horn <ja...@Jann-PC.fritz.box>
+Elijah Insua <tm...@gmail.com>
+Henry Rawas <he...@schakra.com>
+Justin Makeig <jm...@makeig.com>
http://git-wip-us.apache.org/repos/asf/cordova-windows/blob/3aca1d87/node_modules/sax/LICENSE
----------------------------------------------------------------------
diff --git a/node_modules/sax/LICENSE b/node_modules/sax/LICENSE
new file mode 100644
index 0000000..05a4010
--- /dev/null
+++ b/node_modules/sax/LICENSE
@@ -0,0 +1,23 @@
+Copyright 2009, 2010, 2011 Isaac Z. Schlueter.
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
http://git-wip-us.apache.org/repos/asf/cordova-windows/blob/3aca1d87/node_modules/sax/README.md
----------------------------------------------------------------------
diff --git a/node_modules/sax/README.md b/node_modules/sax/README.md
new file mode 100644
index 0000000..9c63dc4
--- /dev/null
+++ b/node_modules/sax/README.md
@@ -0,0 +1,213 @@
+# sax js
+
+A sax-style parser for XML and HTML.
+
+Designed with [node](http://nodejs.org/) in mind, but should work fine in
+the browser or other CommonJS implementations.
+
+## What This Is
+
+* A very simple tool to parse through an XML string.
+* A stepping stone to a streaming HTML parser.
+* A handy way to deal with RSS and other mostly-ok-but-kinda-broken XML
+ docs.
+
+## What This Is (probably) Not
+
+* An HTML Parser - That's a fine goal, but this isn't it. It's just
+ XML.
+* A DOM Builder - You can use it to build an object model out of XML,
+ but it doesn't do that out of the box.
+* XSLT - No DOM = no querying.
+* 100% Compliant with (some other SAX implementation) - Most SAX
+ implementations are in Java and do a lot more than this does.
+* An XML Validator - It does a little validation when in strict mode, but
+ not much.
+* A Schema-Aware XSD Thing - Schemas are an exercise in fetishistic
+ masochism.
+* A DTD-aware Thing - Fetching DTDs is a much bigger job.
+
+## Regarding `<!DOCTYPE`s and `<!ENTITY`s
+
+The parser will handle the basic XML entities in text nodes and attribute
+values: `& < > ' "`. It's possible to define additional
+entities in XML by putting them in the DTD. This parser doesn't do anything
+with that. If you want to listen to the `ondoctype` event, and then fetch
+the doctypes, and read the entities and add them to `parser.ENTITIES`, then
+be my guest.
+
+Unknown entities will fail in strict mode, and in loose mode, will pass
+through unmolested.
+
+## Usage
+
+ var sax = require("./lib/sax"),
+ strict = true, // set to false for html-mode
+ parser = sax.parser(strict);
+
+ parser.onerror = function (e) {
+ // an error happened.
+ };
+ parser.ontext = function (t) {
+ // got some text. t is the string of text.
+ };
+ parser.onopentag = function (node) {
+ // opened a tag. node has "name" and "attributes"
+ };
+ parser.onattribute = function (attr) {
+ // an attribute. attr has "name" and "value"
+ };
+ parser.onend = function () {
+ // parser stream is done, and ready to have more stuff written to it.
+ };
+
+ parser.write('<xml>Hello, <who name="world">world</who>!</xml>').close();
+
+ // stream usage
+ // takes the same options as the parser
+ var saxStream = require("sax").createStream(strict, options)
+ saxStream.on("error", function (e) {
+ // unhandled errors will throw, since this is a proper node
+ // event emitter.
+ console.error("error!", e)
+ // clear the error
+ this._parser.error = null
+ this._parser.resume()
+ })
+ saxStream.on("opentag", function (node) {
+ // same object as above
+ })
+ // pipe is supported, and it's readable/writable
+ // same chunks coming in also go out.
+ fs.createReadStream("file.xml")
+ .pipe(saxStream)
+ .pipe(fs.createReadStream("file-copy.xml"))
+
+
+
+## Arguments
+
+Pass the following arguments to the parser function. All are optional.
+
+`strict` - Boolean. Whether or not to be a jerk. Default: `false`.
+
+`opt` - Object bag of settings regarding string formatting. All default to `false`.
+
+Settings supported:
+
+* `trim` - Boolean. Whether or not to trim text and comment nodes.
+* `normalize` - Boolean. If true, then turn any whitespace into a single
+ space.
+* `lowercasetags` - Boolean. If true, then lowercase tags in loose mode,
+ rather than uppercasing them.
+* `xmlns` - Boolean. If true, then namespaces are supported.
+
+## Methods
+
+`write` - Write bytes onto the stream. You don't have to do this all at
+once. You can keep writing as much as you want.
+
+`close` - Close the stream. Once closed, no more data may be written until
+it is done processing the buffer, which is signaled by the `end` event.
+
+`resume` - To gracefully handle errors, assign a listener to the `error`
+event. Then, when the error is taken care of, you can call `resume` to
+continue parsing. Otherwise, the parser will not continue while in an error
+state.
+
+## Members
+
+At all times, the parser object will have the following members:
+
+`line`, `column`, `position` - Indications of the position in the XML
+document where the parser currently is looking.
+
+`startTagPosition` - Indicates the position where the current tag starts.
+
+`closed` - Boolean indicating whether or not the parser can be written to.
+If it's `true`, then wait for the `ready` event to write again.
+
+`strict` - Boolean indicating whether or not the parser is a jerk.
+
+`opt` - Any options passed into the constructor.
+
+`tag` - The current tag being dealt with.
+
+And a bunch of other stuff that you probably shouldn't touch.
+
+## Events
+
+All events emit with a single argument. To listen to an event, assign a
+function to `on<eventname>`. Functions get executed in the this-context of
+the parser object. The list of supported events are also in the exported
+`EVENTS` array.
+
+When using the stream interface, assign handlers using the EventEmitter
+`on` function in the normal fashion.
+
+`error` - Indication that something bad happened. The error will be hanging
+out on `parser.error`, and must be deleted before parsing can continue. By
+listening to this event, you can keep an eye on that kind of stuff. Note:
+this happens *much* more in strict mode. Argument: instance of `Error`.
+
+`text` - Text node. Argument: string of text.
+
+`doctype` - The `<!DOCTYPE` declaration. Argument: doctype string.
+
+`processinginstruction` - Stuff like `<?xml foo="blerg" ?>`. Argument:
+object with `name` and `body` members. Attributes are not parsed, as
+processing instructions have implementation dependent semantics.
+
+`sgmldeclaration` - Random SGML declarations. Stuff like `<!ENTITY p>`
+would trigger this kind of event. This is a weird thing to support, so it
+might go away at some point. SAX isn't intended to be used to parse SGML,
+after all.
+
+`opentag` - An opening tag. Argument: object with `name` and `attributes`.
+In non-strict mode, tag names are uppercased, unless the `lowercasetags`
+option is set. If the `xmlns` option is set, then it will contain
+namespace binding information on the `ns` member, and will have a
+`local`, `prefix`, and `uri` member.
+
+`closetag` - A closing tag. In loose mode, tags are auto-closed if their
+parent closes. In strict mode, well-formedness is enforced. Note that
+self-closing tags will have `closeTag` emitted immediately after `openTag`.
+Argument: tag name.
+
+`attribute` - An attribute node. Argument: object with `name` and `value`,
+and also namespace information if the `xmlns` option flag is set.
+
+`comment` - A comment node. Argument: the string of the comment.
+
+`opencdata` - The opening tag of a `<![CDATA[` block.
+
+`cdata` - The text of a `<![CDATA[` block. Since `<![CDATA[` blocks can get
+quite large, this event may fire multiple times for a single block, if it
+is broken up into multiple `write()`s. Argument: the string of random
+character data.
+
+`closecdata` - The closing tag (`]]>`) of a `<![CDATA[` block.
+
+`opennamespace` - If the `xmlns` option is set, then this event will
+signal the start of a new namespace binding.
+
+`closenamespace` - If the `xmlns` option is set, then this event will
+signal the end of a namespace binding.
+
+`end` - Indication that the closed stream has ended.
+
+`ready` - Indication that the stream has reset, and is ready to be written
+to.
+
+`noscript` - In non-strict mode, `<script>` tags trigger a `"script"`
+event, and their contents are not checked for special xml characters.
+If you pass `noscript: true`, then this behavior is suppressed.
+
+## Reporting Problems
+
+It's best to write a failing test if you find an issue. I will always
+accept pull requests with failing tests if they demonstrate intended
+behavior, but it is very hard to figure out what issue you're describing
+without a test. Writing a test is also the best way for you yourself
+to figure out if you really understand the issue you think you have with
+sax-js.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org