ecomp-portal-FE/client/bower_components/json3/README.md

   1 # JSON 3 #
   2
   3 ![JSON 3 Logo](http://bestiejs.github.io/json3/page/logo.png)
   4
   5 [![Build Status](https://secure.travis-ci.org/bestiejs/json3.png?branch=gh-pages)](http://travis-ci.org/bestiejs/json3)
   6
   7 **JSON 3** is a modern JSON implementation compatible with a variety of JavaScript platforms, including Internet Explorer 6, Opera 7, Safari 2, and Netscape 6. The current version is **3.3.2**.
   8
   9 - [Development Version](http://cdnjs.cloudflare.com/ajax/libs/json3/3.3.2/json3.js) *(43 KB; uncompressed with comments)*
  10 - [Production Version](http://cdnjs.cloudflare.com/ajax/libs/json3/3.3.2/json3.min.js) *(3.5 KB; compressed and `gzip`-ped)*
  11
  12 Special thanks to [cdnjs](http://cdnjs.com/libraries/json3/) and [jsDelivr](http://www.jsdelivr.com/#!json3) for hosting CDN copies of JSON 3.
  13
  14 [JSON](http://json.org/) is a language-independent data interchange format based on a loose subset of the JavaScript grammar. Originally popularized by [Douglas Crockford](http://www.crockford.com/), the format was standardized in the [fifth edition](http://es5.github.com/) of the ECMAScript specification. The 5.1 edition, ratified in June 2011, incorporates several modifications to the grammar pertaining to the serialization of dates.
  15
  16 JSON 3 exposes two functions: `stringify()` for [serializing](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/JSON/stringify) a JavaScript value to JSON, and `parse()` for [producing](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/JSON/parse) a JavaScript value from a JSON source string. It is a **drop-in replacement** for [JSON 2](http://json.org/js). The functions behave exactly as described in the ECMAScript spec, **except** for the date serialization discrepancy noted below.
  17
  18 The JSON 3 parser does **not** use `eval` or regular expressions. This provides security and performance benefits in obsolete and mobile environments, where the margin is particularly significant. The complete [benchmark suite](http://jsperf.com/json3) is available on [jsPerf](http://jsperf.com/).
  19
  20 The project is [hosted on GitHub](http://git.io/json3), along with the [unit tests](http://bestiejs.github.io/json3/test/test_browser.html). It is part of the [BestieJS](https://github.com/bestiejs) family, a collection of best-in-class JavaScript libraries that promote cross-platform support, specification precedents, unit testing, and plenty of documentation.
  21
  22 # Changes from JSON 2 #
  23
  24 JSON 3...
  25
  26 * Correctly serializes primitive wrapper objects.
  27 * Throws a `TypeError` when serializing cyclic structures (JSON 2 recurses until the call stack overflows).
  28 * Utilizes **feature tests** to detect broken or incomplete *native* JSON implementations (JSON 2 only checks for the presence of the native functions). The tests are only executed once at runtime, so there is no additional performance cost when parsing or serializing values.
  29
  30 **As of v3.2.3**, JSON 3 is compatible with [Prototype](http://prototypejs.org) 1.6.1 and older.
  31
  32 In contrast to JSON 2, JSON 3 **does not**...
  33
  34 * Add `toJSON()` methods to the `Boolean`, `Number`, and `String` prototypes. These are not part of any standard, and are made redundant by the design of the `stringify()` implementation.
  35 * Add `toJSON()` or `toISOString()` methods to `Date.prototype`. See the note about date serialization below.
  36
  37 ## Date Serialization
  38
  39 **JSON 3 deviates from the specification in one important way**: it does not define `Date#toISOString()` or `Date#toJSON()`. This preserves CommonJS compatibility and avoids polluting native prototypes. Instead, date serialization is performed internally by the `stringify()` implementation: if a date object does not define a custom `toJSON()` method, it is serialized as a [simplified ISO 8601 date-time string](http://es5.github.com/#x15.9.1.15).
  40
  41 **Several native `Date#toJSON()` implementations produce date time strings that do *not* conform to the grammar outlined in the spec**. For instance, all versions of Safari 4, as well as JSON 2, fail to serialize extended years correctly. Furthermore, JSON 2 and older implementations omit the milliseconds from the date-time string (optional in ES 5, but required in 5.1). Finally, in all versions of Safari 4 and 5, serializing an invalid date will produce the string `"Invalid Date"`, rather than `null`. Because these environments exhibit other serialization bugs, however, JSON 3 will override the native `stringify()` implementation.
  42
  43 Portions of the date serialization code are adapted from the [`date-shim`](https://github.com/Yaffle/date-shim) project.
  44
  45 # Usage #
  46
  47 ## Web Browsers
  48
  49     <script src="//cdnjs.cloudflare.com/ajax/libs/json3/3.3.2/json3.min.js"></script>
  50     <script>
  51       JSON.stringify({"Hello": 123});
  52       // => '{"Hello":123}'
  53       JSON.parse("[[1, 2, 3], 1, 2, 3, 4]", function (key, value) {
  54         if (typeof value == "number") {
  55           value = value % 2 ? "Odd" : "Even";
  56         }
  57         return value;
  58       });
  59       // => [["Odd", "Even", "Odd"], "Odd", "Even", "Odd", "Even"]
  60     </script>
  61
  62 **When used in a web browser**, JSON 3 exposes an additional `JSON3` object containing the `noConflict()` and `runInContext()` functions, as well as aliases to the `stringify()` and `parse()` functions.
  63
  64 ### `noConflict` and `runInContext`
  65
  66 * `JSON3.noConflict()` restores the original value of the global `JSON` object and returns a reference to the `JSON3` object.
  67 * `JSON3.runInContext([context, exports])` initializes JSON 3 using the given `context` object (e.g., `window`, `global`, etc.), or the global object if omitted. If an `exports` object is specified, the `stringify()`, `parse()`, and `runInContext()` functions will be attached to it instead of a new object.
  68
  69 ### Asynchronous Module Loaders
  70
  71 JSON 3 is defined as an [anonymous module](https://github.com/amdjs/amdjs-api/wiki/AMD#define-function-) for compatibility with [RequireJS](http://requirejs.org/), [`curl.js`](https://github.com/cujojs/curl), and other asynchronous module loaders.
  72
  73     <script src="//cdnjs.cloudflare.com/ajax/libs/require.js/2.1.10/require.js"></script>
  74     <script>
  75       require({
  76         "paths": {
  77           "json3": "./path/to/json3"
  78         }
  79       }, ["json3"], function (JSON) {
  80         JSON.parse("[1, 2, 3]");
  81         // => [1, 2, 3]
  82       });
  83     </script>
  84
  85 To avoid issues with third-party scripts, **JSON 3 is exported to the global scope even when used with a module loader**. If this behavior is undesired, `JSON3.noConflict()` can be used to restore the global `JSON` object to its original value.
  86
  87 ## CommonJS Environments
  88
  89     var JSON3 = require("./path/to/json3");
  90     JSON3.parse("[1, 2, 3]");
  91     // => [1, 2, 3]
  92
  93 ## JavaScript Engines
  94
  95     load("path/to/json3.js");
  96     JSON.stringify({"Hello": 123, "Good-bye": 456}, ["Hello"], "\t");
  97     // => '{\n\t"Hello": 123\n}'
  98
  99 # Compatibility #
 100
 101 JSON 3 has been **tested** with the following web browsers, CommonJS environments, and JavaScript engines.
 102
 103 ## Web Browsers
 104
 105 - Windows [Internet Explorer](http://www.microsoft.com/windows/internet-explorer), version 6.0 and higher
 106 - Mozilla [Firefox](http://www.mozilla.com/firefox), version 1.0 and higher
 107 - Apple [Safari](http://www.apple.com/safari), version 2.0 and higher
 108 - [Opera](http://www.opera.com) 7.02 and higher
 109 - [Mozilla](http://sillydog.org/narchive/gecko.php) 1.0, [Netscape](http://sillydog.org/narchive/) 6.2.3, and [SeaMonkey](http://www.seamonkey-project.org/) 1.0 and higher
 110
 111 ## CommonJS Environments
 112
 113 - [Node](http://nodejs.org/) 0.2.6 and higher
 114 - [RingoJS](http://ringojs.org/) 0.4 and higher
 115 - [Narwhal](http://narwhaljs.org/) 0.3.2 and higher
 116
 117 ## JavaScript Engines
 118
 119 - Mozilla [Rhino](http://www.mozilla.org/rhino) 1.5R5 and higher
 120 - WebKit [JSC](https://trac.webkit.org/wiki/JSC)
 121 - Google [V8](http://code.google.com/p/v8)
 122
 123 ## Known Incompatibilities
 124
 125 * Attempting to serialize the `arguments` object may produce inconsistent results across environments due to specification version differences. As a workaround, please convert the `arguments` object to an array first: `JSON.stringify([].slice.call(arguments, 0))`.
 126
 127 ## Required Native Methods
 128
 129 JSON 3 assumes that the following methods exist and function as described in the ECMAScript specification:
 130
 131 - The `Number`, `String`, `Array`, `Object`, `Date`, `SyntaxError`, and `TypeError` constructors.
 132 - `String.fromCharCode`
 133 - `Object#toString`
 134 - `Function#call`
 135 - `Math.floor`
 136 - `Number#toString`
 137 - `Date#valueOf`
 138 - `String.prototype`: `indexOf`, `charCodeAt`, `charAt`, `slice`.
 139 - `Array.prototype`: `push`, `pop`, `join`.
 140
 141 # Contribute #
 142
 143 Check out a working copy of the JSON 3 source code with [Git](http://git-scm.com/):
 144
 145     $ git clone git://github.com/bestiejs/json3.git
 146     $ cd json3
 147
 148 If you'd like to contribute a feature or bug fix, you can [fork](http://help.github.com/fork-a-repo/) JSON 3, commit your changes, and [send a pull request](http://help.github.com/send-pull-requests/). Please make sure to update the unit tests in the `test` directory as well.
 149
 150 Alternatively, you can use the [GitHub issue tracker](https://github.com/bestiejs/json3/issues) to submit bug reports, feature requests, and questions, or send tweets to [@kitcambridge](http://twitter.com/kitcambridge).
 151
 152 JSON 3 is released under the [MIT License](http://kit.mit-license.org/).