From 1e7d8ecd576d1d8acde74cbfdcf3751582bc391e Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Sat, 27 Jul 2013 19:58:44 -0700 Subject: [PATCH] big README revamp --- README.md | 114 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 68 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 1a3f9f0..5940c90 100644 --- a/README.md +++ b/README.md @@ -2,72 +2,94 @@ JSON to YAML === The purpose of this utility is to pretty-print JSON in the human-readable YAML object notation -(ignore the misnomer, it's not a markup language at all) +(ignore the misnomer, YAML is not a Markup Language at all). -You see, JSON is a proper subset of YAML, The difference is that YAML can use whitespace instead of syntax, which is more human-readable. -Also, YAML supports comments. +Installation +=== -So, for all the times you want to turn JSON int YAML (YML): +```bash +npm install -g json2yaml +``` - { - "foo": "bar", - "baz": [ - "qux", - "quxx" - ], - "corge": null, - "grault": 1, - "garply": true, - "waldo": "false", - "fred": "undefined" - } - -becomes - - --- - foo: "bar" - baz: - - "qux" - - "quxx" - corge: null - grault: 1 - garply: true - waldo: "false" - fred: "undefined" +*Note*: To use `npm` and `json2yaml` you must have installed [NodeJS](http://nodejs.org#download). Usage --- Specify a file: - json2yaml ./example.json +```bash +json2yaml ./example.json > ./example.yml - yaml2json ./example.kml | json2yaml +yaml2json ./example.yml | json2yaml > ./example.yml +``` Or pipe from stdin: - curl -s http://foobar3000.com/echo/echo.json | json2yaml +```bash +curl -s http://foobar3000.com/echo/echo.json | json2yaml - wget -qO- http://foobar3000.com/echo/echo.json | json2yaml +wget -qO- http://foobar3000.com/echo/echo.json | json2yaml +``` Or require: - (function () { - "use strict"; +```javascript +(function () { + "use strict"; - var YAML = require('json2yaml') - , ymlText - ; + var YAML = require('json2yaml') + , ymlText + ; - ymlText = YAML.stringify({ - "foo": "bar" - , "baz": "corge" - }); + ymlText = YAML.stringify({ + "foo": "bar" + , "baz": "corge" + }); - console.log(ymlText); - }()); + console.log(ymlText); +}()); +``` -Installation +Example +=== + +So, for all the times you want to turn JSON int YAML (YML): + +```javascript +{ "foo": "bar" +, "baz": [ + "qux" + , "quxx" + ] +, "corge": null +, "grault": 1 +, "garply": true +, "waldo": "false" +, "fred": "undefined" +} +``` + +becomes + +```yaml --- + foo: "bar" + baz: + - "qux" + - "quxx" + corge: null + grault: 1 + garply: true + waldo: "false" + fred: "undefined" +``` - npm install -g json2yaml +*Note*: In fact, both of those Object Notations qualify as YAML +because JSON technically *is* a proper subset of YAML. +That is to say that all proper YAML parsers parse proper JSON. + +YAML can use either *whitespace and dashes* or *brackets and commas*. + +For human readability, the whitespace-based YAML is preferrable. +For compression and computer readability, the syntax-based YAML is preferrable.