diff options
Diffstat (limited to 'tools/doc/node_modules/js-yaml/README.md')
| -rw-r--r-- | tools/doc/node_modules/js-yaml/README.md | 313 |
1 files changed, 0 insertions, 313 deletions
diff --git a/tools/doc/node_modules/js-yaml/README.md b/tools/doc/node_modules/js-yaml/README.md deleted file mode 100644 index c165c3576a..0000000000 --- a/tools/doc/node_modules/js-yaml/README.md +++ /dev/null @@ -1,313 +0,0 @@ -JS-YAML - YAML 1.2 parser / writer for JavaScript -================================================= - -[](https://travis-ci.org/nodeca/js-yaml) -[](https://www.npmjs.org/package/js-yaml) - -__[Online Demo](http://nodeca.github.com/js-yaml/)__ - - -This is an implementation of [YAML](http://yaml.org/), a human-friendly data -serialization language. Started as [PyYAML](http://pyyaml.org/) port, it was -completely rewritten from scratch. Now it's very fast, and supports 1.2 spec. - - -Installation ------------- - -### YAML module for node.js - -``` -npm install js-yaml -``` - - -### CLI executable - -If you want to inspect your YAML files from CLI, install js-yaml globally: - -``` -npm install -g js-yaml -``` - -#### Usage - -``` -usage: js-yaml [-h] [-v] [-c] [-t] file - -Positional arguments: - file File with YAML document(s) - -Optional arguments: - -h, --help Show this help message and exit. - -v, --version Show program's version number and exit. - -c, --compact Display errors in compact mode - -t, --trace Show stack trace on error -``` - - -### Bundled YAML library for browsers - -``` html -<!-- esprima required only for !!js/function --> -<script src="esprima.js"></script> -<script src="js-yaml.min.js"></script> -<script type="text/javascript"> -var doc = jsyaml.load('greeting: hello\nname: world'); -</script> -``` - -Browser support was done mostly for the online demo. If you find any errors - feel -free to send pull requests with fixes. Also note, that IE and other old browsers -needs [es5-shims](https://github.com/kriskowal/es5-shim) to operate. - -Notes: - -1. We have no resources to support browserified version. Don't expect it to be - well tested. Don't expect fast fixes if something goes wrong there. -2. `!!js/function` in browser bundle will not work by default. If you really need - it - load `esprima` parser first (via amd or directly). -3. `!!bin` in browser will return `Array`, because browsers do not support - node.js `Buffer` and adding Buffer shims is completely useless on practice. - - -API ---- - -Here we cover the most 'useful' methods. If you need advanced details (creating -your own tags), see [wiki](https://github.com/nodeca/js-yaml/wiki) and -[examples](https://github.com/nodeca/js-yaml/tree/master/examples) for more -info. - -``` javascript -yaml = require('js-yaml'); -fs = require('fs'); - -// Get document, or throw exception on error -try { - var doc = yaml.safeLoad(fs.readFileSync('/home/ixti/example.yml', 'utf8')); - console.log(doc); -} catch (e) { - console.log(e); -} -``` - - -### safeLoad (string [ , options ]) - -**Recommended loading way.** Parses `string` as single YAML document. Returns a JavaScript -object or throws `YAMLException` on error. By default, does not support regexps, -functions and undefined. This method is safe for untrusted data. - -options: - -- `filename` _(default: null)_ - string to be used as a file path in - error/warning messages. -- `onWarning` _(default: null)_ - function to call on warning messages. - Loader will throw on warnings if this function is not provided. -- `schema` _(default: `DEFAULT_SAFE_SCHEMA`)_ - specifies a schema to use. - - `FAILSAFE_SCHEMA` - only strings, arrays and plain objects: - http://www.yaml.org/spec/1.2/spec.html#id2802346 - - `JSON_SCHEMA` - all JSON-supported types: - http://www.yaml.org/spec/1.2/spec.html#id2803231 - - `CORE_SCHEMA` - same as `JSON_SCHEMA`: - http://www.yaml.org/spec/1.2/spec.html#id2804923 - - `DEFAULT_SAFE_SCHEMA` - all supported YAML types, without unsafe ones - (`!!js/undefined`, `!!js/regexp` and `!!js/function`): - http://yaml.org/type/ - - `DEFAULT_FULL_SCHEMA` - all supported YAML types. -- `json` _(default: false)_ - compatibility with JSON.parse behaviour. If true, then duplicate keys in a mapping will override values rather than throwing an error. - -NOTE: This function **does not** understand multi-document sources, it throws -exception on those. - -NOTE: JS-YAML **does not** support schema-specific tag resolution restrictions. -So, the JSON schema is not as strictly defined in the YAML specification. -It allows numbers in any notation, use `Null` and `NULL` as `null`, etc. -The core schema also has no such restrictions. It allows binary notation for integers. - - -### load (string [ , options ]) - -**Use with care with untrusted sources**. The same as `safeLoad()` but uses -`DEFAULT_FULL_SCHEMA` by default - adds some JavaScript-specific types: -`!!js/function`, `!!js/regexp` and `!!js/undefined`. For untrusted sources, you -must additionally validate object structure to avoid injections: - -``` javascript -var untrusted_code = '"toString": !<tag:yaml.org,2002:js/function> "function (){very_evil_thing();}"'; - -// I'm just converting that string, what could possibly go wrong? -require('js-yaml').load(untrusted_code) + '' -``` - - -### safeLoadAll (string [, iterator] [, options ]) - -Same as `safeLoad()`, but understands multi-document sources. Applies -`iterator` to each document if specified, or returns array of documents. - -``` javascript -var yaml = require('js-yaml'); - -yaml.safeLoadAll(data, function (doc) { - console.log(doc); -}); -``` - - -### loadAll (string [, iterator] [ , options ]) - -Same as `safeLoadAll()` but uses `DEFAULT_FULL_SCHEMA` by default. - - -### safeDump (object [ , options ]) - -Serializes `object` as a YAML document. Uses `DEFAULT_SAFE_SCHEMA`, so it will -throw an exception if you try to dump regexps or functions. However, you can -disable exceptions by setting the `skipInvalid` option to `true`. - -options: - -- `indent` _(default: 2)_ - indentation width to use (in spaces). -- `skipInvalid` _(default: false)_ - do not throw on invalid types (like function - in the safe schema) and skip pairs and single values with such types. -- `flowLevel` (default: -1) - specifies level of nesting, when to switch from - block to flow style for collections. -1 means block style everwhere -- `styles` - "tag" => "style" map. Each tag may have own set of styles. -- `schema` _(default: `DEFAULT_SAFE_SCHEMA`)_ specifies a schema to use. -- `sortKeys` _(default: `false`)_ - if `true`, sort keys when dumping YAML. If a - function, use the function to sort the keys. -- `lineWidth` _(default: `80`)_ - set max line width. -- `noRefs` _(default: `false`)_ - if `true`, don't convert duplicate objects into references -- `noCompatMode` _(default: `false`)_ - if `true` don't try to be compatible with older - yaml versions. Currently: don't quote "yes", "no" and so on, as required for YAML 1.1 -- `condenseFlow` _(default: `false`)_ - if `true` flow sequences will be condensed, omitting the space between `a, b`. Eg. `'[a,b]'`, and omitting the space between `key: value` and quoting the key. Eg. `'{"a":b}'` Can be useful when using yaml for pretty URL query params as spaces are %-encoded. - -The following table show availlable styles (e.g. "canonical", -"binary"...) available for each tag (.e.g. !!null, !!int ...). Yaml -output is shown on the right side after `=>` (default setting) or `->`: - -``` none -!!null - "canonical" -> "~" - "lowercase" => "null" - "uppercase" -> "NULL" - "camelcase" -> "Null" - -!!int - "binary" -> "0b1", "0b101010", "0b1110001111010" - "octal" -> "01", "052", "016172" - "decimal" => "1", "42", "7290" - "hexadecimal" -> "0x1", "0x2A", "0x1C7A" - -!!bool - "lowercase" => "true", "false" - "uppercase" -> "TRUE", "FALSE" - "camelcase" -> "True", "False" - -!!float - "lowercase" => ".nan", '.inf' - "uppercase" -> ".NAN", '.INF' - "camelcase" -> ".NaN", '.Inf' -``` - -Example: - -``` javascript -safeDump (object, { - 'styles': { - '!!null': 'canonical' // dump null as ~ - }, - 'sortKeys': true // sort object keys -}); -``` - -### dump (object [ , options ]) - -Same as `safeDump()` but without limits (uses `DEFAULT_FULL_SCHEMA` by default). - - -Supported YAML types --------------------- - -The list of standard YAML tags and corresponding JavaScipt types. See also -[YAML tag discussion](http://pyyaml.org/wiki/YAMLTagDiscussion) and -[YAML types repository](http://yaml.org/type/). - -``` -!!null '' # null -!!bool 'yes' # bool -!!int '3...' # number -!!float '3.14...' # number -!!binary '...base64...' # buffer -!!timestamp 'YYYY-...' # date -!!omap [ ... ] # array of key-value pairs -!!pairs [ ... ] # array or array pairs -!!set { ... } # array of objects with given keys and null values -!!str '...' # string -!!seq [ ... ] # array -!!map { ... } # object -``` - -**JavaScript-specific tags** - -``` -!!js/regexp /pattern/gim # RegExp -!!js/undefined '' # Undefined -!!js/function 'function () {...}' # Function -``` - -Caveats -------- - -Note, that you use arrays or objects as key in JS-YAML. JS does not allow objects -or arrays as keys, and stringifies (by calling `toString()` method) them at the -moment of adding them. - -``` yaml ---- -? [ foo, bar ] -: - baz -? { foo: bar } -: - baz - - baz -``` - -``` javascript -{ "foo,bar": ["baz"], "[object Object]": ["baz", "baz"] } -``` - -Also, reading of properties on implicit block mapping keys is not supported yet. -So, the following YAML document cannot be loaded. - -``` yaml -&anchor foo: - foo: bar - *anchor: duplicate key - baz: bat - *anchor: duplicate key -``` - - -Breaking changes in 2.x.x -> 3.x.x ----------------------------------- - -If you have not used __custom__ tags or loader classes and not loaded yaml -files via `require()`, no changes are needed. Just upgrade the library. - -Otherwise, you should: - -1. Replace all occurrences of `require('xxxx.yml')` by `fs.readFileSync()` + - `yaml.safeLoad()`. -2. rewrite your custom tags constructors and custom loader - classes, to conform the new API. See - [examples](https://github.com/nodeca/js-yaml/tree/master/examples) and - [wiki](https://github.com/nodeca/js-yaml/wiki) for details. - - -License -------- - -View the [LICENSE](https://github.com/nodeca/js-yaml/blob/master/LICENSE) file -(MIT). |