Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 207 lines (150 sloc) 5.393 kb
866f44e4 »
2012-03-21 Initial commit
1
62f9a09d »
2012-03-21 rename eson
2 # eson
866f44e4 »
2012-03-21 Initial commit
3
419846e0 »
2012-03-21 docs
4 Extended JSON for node.
21df55b0 »
2012-03-21 removed routes examples
5
7dcc19b7 »
2012-03-21 docs
6 ## Installation
7
8 ```
62f9a09d »
2012-03-21 rename eson
9 $ npm install eson
7dcc19b7 »
2012-03-21 docs
10 ```
11
21df55b0 »
2012-03-21 removed routes examples
12 ## Parser
13
14 Currently only the parser portion is implemented, useful for configuration files.
419846e0 »
2012-03-21 docs
15 For example a typical configuration file might look something like the following:
16
ceceeee1 »
2012-03-21 docs
17 ```js
419846e0 »
2012-03-21 docs
18 {
19 "views": "/www/example.com/views",
20 "view engine": "jade",
21 "poll interval": 5000,
22 "canvas size": { "width": 800, "height": 600 }
23 }
24 ```
25
26 With Extended JSON you can define plugin functions, or use ones
62f9a09d »
2012-03-21 rename eson
27 bundled with eson to transform the input, allowing for more
419846e0 »
2012-03-21 docs
28 declarative configurations as shown here:
29
ceceeee1 »
2012-03-21 docs
30 ```js
419846e0 »
2012-03-21 docs
31 {
32 "views": "{root}/views",
33 "view engine": "jade",
34 "poll interval": "5 seconds",
35 "canvas size": "800x600"
36 }
37 ```
38
39 ### Writing plugins
40
41 Writing a plugin is simple, it's a function which takes the signature `(key, val, parser)`. Let's write one that transforms every value to "foo":
42
43 ```js
44 function foo(key, val, parser) {
45 return 'foo';
46 }
47 ```
48
49 Then use the plugin like so:
50
51 ```js
62f9a09d »
2012-03-21 rename eson
52 var eson = require('eson');
419846e0 »
2012-03-21 docs
53
62f9a09d »
2012-03-21 rename eson
54 var conf = eson()
419846e0 »
2012-03-21 docs
55 .use(foo)
56 .read('path/to/config.json');
57 ```
58
59 Now suppose `path/to/config.json` contained `{ "foo": "bar", "bar": "baz" }`,
60 the `foo()` plugin would yield `{ "foo": "foo", "bar": "foo" }`. So you get the picture,
61 with this we can accept arbitrary strings such as "5 seconds" and transform
62 it to the more useful `5000` milliseconds representation.
866f44e4 »
2012-03-21 Initial commit
63
99410cc1 »
2012-03-21 docs for plugins
64 Many plugins may of course be used, and _all_ will be executed regardless, so if necessary
ef668e3d »
2012-03-21 docs
65 subsequent plugins may still make modifications. Depending on what the plugins the order used _may_ have an effect on the JSON.
99410cc1 »
2012-03-21 docs for plugins
66
67 ```js
62f9a09d »
2012-03-21 rename eson
68 eson()
69 .use(eson.ms)
70 .use(eson.include)
71 .use(eson.dimensions)
72 .use(eson.replace('{root}', '/www/example.com'))
99410cc1 »
2012-03-21 docs for plugins
73 .parse('{ "interval": "15 minutes" }');
74 ```
62f9a09d »
2012-03-21 rename eson
75 ### eson.ms
99410cc1 »
2012-03-21 docs for plugins
76
77 The milliseconds plugin supports strings like "5s", "5 seconds", "3 days", etc:
78
79 ```js
62f9a09d »
2012-03-21 rename eson
80 eson()
81 .use(eson.ms)
99410cc1 »
2012-03-21 docs for plugins
82 .parse('{ "interval": "15 minutes" }');
83 ```
84
85 yields:
86
87 ```js
88 { interval: 900000 }
89 ```
90
62f9a09d »
2012-03-21 rename eson
91 ### eson.include
99410cc1 »
2012-03-21 docs for plugins
92
93 The include plugin allows you to literally include other JSON files. This works in
94 both arrays and object literals, and loads relative to the callee's file. For example:
95
96 ```js
62f9a09d »
2012-03-21 rename eson
97 eson()
98 .use(eson.include)
99410cc1 »
2012-03-21 docs for plugins
99 .parse('{ "prod": "include config/production" }');
100 ```
101
102 yields:
103
104 ```js
105 { prod: { whatever: 'is', within: 'config/production.json' }}
106 ```
107
1fd1cdc2 »
2012-06-28 add bools()
108 ### eson.bools
109
4458f1c9 »
2012-07-19 add on / off to .bools
110 Convert "yes", "no", "on", "off", "enabled", "disabled" into booleans.
1fd1cdc2 »
2012-06-28 add bools()
111
b3278fd1 »
2012-06-28 add env(prefix) support
112 ### eson.env([prefix])
113
584d873d »
2012-06-28 add env docs
114 Allow environment variables to define config values. If you have the following:
115
116 ```js
117 {
118 "upload path": "/data/uploads"
119 }
120 ```
121
122 You could then export `UPLOAD_PATH=/tmp` to change this value. Optionally when
123 a `prefix` is given such as "MYAPP_" then you must prefix such as `MYAPP_UPLOAD_PATH=/tmp`.
124
62f9a09d »
2012-03-21 rename eson
125 ### eson.replace(str, val)
99410cc1 »
2012-03-21 docs for plugins
126
127 The replace plugin allows you to replace arbitrary substrings, useful
128 for constants such as the application's root directory etc.
129
130 ```js
62f9a09d »
2012-03-21 rename eson
131 eson()
132 .use(eson.replace('{root}', '/www/example.com'))
99410cc1 »
2012-03-21 docs for plugins
133 .parse('{ "upload path": "{root}/tmp" }');
134 ```
135
136 yields:
137
138 ```js
139 { "upload path": "/www/example.com/tmp" }
140 ```
141
5eaeaed3 »
2012-06-28 add args() plugin
142 ### eson.args([args])
143
144 Parse from the given `args` or __ARGV__. For example if you have a setting
145 named "dev ui" with a default value of `false`, `--dev-ui` would enable it,
146 or `--dev-ui yes` would provide the value "yes" which is of course also truthy.
147
148 To compliment `--NAME` you may also negate this, if "dev ui" is enabled by default
149 then you may use `--no-dev-ui` to disable it.
150
62f9a09d »
2012-03-21 rename eson
151 ### eson.glob
99410cc1 »
2012-03-21 docs for plugins
152
153 The glob plugin allows you to specify glob strings, prefixed by "glob":
154
155 ```js
62f9a09d »
2012-03-21 rename eson
156 eson()
157 .use(eson.glob)
99410cc1 »
2012-03-21 docs for plugins
158 .parse('{ "js": "glob public/{js,vendor}/*.js" }');
159 ```
160
161 yields:
162
163 ```js
164 { js: ["public/js/app.js", "public/js/user.js", "public/vendor/jquery.js"] }
165 ```
166
a2c2a247 »
2012-03-21 docs
167 ## moar!
168
169 That's it for now, just experimenting with it, feel free to send me a PR
170 or open and issue if you have some ideas. I'd like to keep everything
171 valid JSON, for example you can use the `include` plugin to include
172 env-specific config into package.json, and package.json remains a
173 valid JSON document.
174
62f9a09d »
2012-03-21 rename eson
175 For addition documentation view the [test markdown](https://github.com/visionmedia/eson/blob/master/tests.md).
9d926887 »
2012-03-21 docs
176
a2c2a247 »
2012-03-21 docs
177 ## Running tests
178
179 ```
180 $ npm install
181 $ make test
182 ```
183
866f44e4 »
2012-03-21 Initial commit
184 ## License
185
186 (The MIT License)
187
d18a5508 »
2012-03-21 misc
188 Copyright (c) 2012 TJ Holowaychuk <tj@vision-media.ca>
866f44e4 »
2012-03-21 Initial commit
189
190 Permission is hereby granted, free of charge, to any person obtaining
191 a copy of this software and associated documentation files (the
192 'Software'), to deal in the Software without restriction, including
193 without limitation the rights to use, copy, modify, merge, publish,
194 distribute, sublicense, and/or sell copies of the Software, and to
195 permit persons to whom the Software is furnished to do so, subject to
196 the following conditions:
197
198 The above copyright notice and this permission notice shall be
199 included in all copies or substantial portions of the Software.
200
201 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
202 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
203 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
204 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
205 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
206 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
207 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.