Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 215 lines (154 sloc) 7.266 kB
e1b22ec @dscape [readme] first try
authored
1 # clarinet
2
4443293 @dscape Update README.md
authored
3 ![NPM Downloads](http://img.shields.io/npm/dm/clarinet.svg?style=flat) ![NPM Version](http://img.shields.io/npm/v/clarinet.svg?style=flat)
4
bc0a328 @dscape [docs] small bump to get to top of github
authored
5 `clarinet` is a sax-like streaming parser for JSON. works in the browser and node.js. `clarinet` is inspired (and forked) from [sax-js][saxjs]. just like you shouldn't use `sax` when you need `dom` you shouldn't use `clarinet` when you need `JSON.parse`. for a more detailed introduction and a performance study please refer to this [article][blog].
e1b22ec @dscape [readme] first try
authored
6
7 # design goals
8
9 `clarinet` is very much like [yajl] but written in javascript:
10
11 * written in javascript
12 * portable
13 * robust (~110 tests pass before even announcing the project)
14 * data representation independent
15 * fast
16 * generates verbose, useful error messages including context of where
17 the error occurs in the input text.
18 * can parse json data off a stream, incrementally
19 * simple to use
20 * tiny
21
22 # motivation
23
24 the reason behind this work was to create better full text support in node. creating indexes out of large (or many) json files doesn't require a full understanding of the json file, but it does require something like `clarinet`.
25
26 # installation
27
28 ## node.js
29
30 1. install [npm]
31 2. `npm install clarinet`
ac51260 @dscape [readme] first try
authored
32 3. `var clarinet = require('clarinet');`
e1b22ec @dscape [readme] first try
authored
33
34 ## browser
35
36 1. minimize clarinet.js
37 2. load it into your webpage
38
39 # usage
40
41 ## basics
42
43 ``` js
44 var clarinet = require("clarinet")
45 , parser = clarinet.parser()
46 ;
47
48 parser.onerror = function (e) {
49 // an error happened. e is the error.
50 };
51 parser.onvalue = function (v) {
f506f00 @brettz9 Update README.md
brettz9 authored
52 // got some value. v is the value. can be string, double, bool, or null.
e1b22ec @dscape [readme] first try
authored
53 };
54 parser.onopenobject = function (key) {
55 // opened an object. key is the first key.
56 };
57 parser.onkey = function (key) {
58 // got a key in an object.
59 };
60 parser.oncloseobject = function () {
61 // closed an object.
62 };
63 parser.onopenarray = function () {
64 // opened an array.
65 };
66 parser.onclosearray = function () {
67 // closed an array.
68 };
69 parser.onend = function () {
70 // parser stream is done, and ready to have more stuff written to it.
71 };
72
73 parser.write('{"foo": "bar"}').close();
74 ```
75
76 ``` js
77 // stream usage
78 // takes the same options as the parser
79 var stream = require("clarinet").createStream(options);
80 stream.on("error", function (e) {
81 // unhandled errors will throw, since this is a proper node
82 // event emitter.
83 console.error("error!", e)
84 // clear the error
85 this._parser.error = null
86 this._parser.resume()
87 })
88 stream.on("openobject", function (node) {
89 // same object as above
90 })
91 // pipe is supported, and it's readable/writable
92 // same chunks coming in also go out.
93 fs.createReadStream("file.json")
94 .pipe(stream)
95 .pipe(fs.createReadStream("file-altered.json"))
96 ```
97
98 ## arguments
99
100 pass the following arguments to the parser function. all are optional.
101
102 `opt` - object bag of settings regarding string formatting. all default to `false`.
103
104 settings supported:
105
106 * `trim` - boolean. whether or not to trim text and comment nodes.
107 * `normalize` - boolean. if true, then turn any whitespace into a single
4000360 @isaacs Document namespace stuff.
isaacs authored
108 space.
6ce93ba @isaacs Put the uppercasing of tags back, and make it configurable.
isaacs authored
109
e1b22ec @dscape [readme] first try
authored
110 ## methods
d90ce62 @isaacs For the readings.
isaacs authored
111
e1b22ec @dscape [readme] first try
authored
112 `write` - write bytes onto the stream. you don't have to do this all at
113 once. you can keep writing as much as you want.
d90ce62 @isaacs For the readings.
isaacs authored
114
e1b22ec @dscape [readme] first try
authored
115 `close` - close the stream. once closed, no more data may be written until
4000360 @isaacs Document namespace stuff.
isaacs authored
116 it is done processing the buffer, which is signaled by the `end` event.
d90ce62 @isaacs For the readings.
isaacs authored
117
e1b22ec @dscape [readme] first try
authored
118 `resume` - to gracefully handle errors, assign a listener to the `error`
119 event. then, when the error is taken care of, you can call `resume` to
120 continue parsing. otherwise, the parser will not continue while in an error
4000360 @isaacs Document namespace stuff.
isaacs authored
121 state.
335cda6 @isaacs Add resume function doc
isaacs authored
122
e1b22ec @dscape [readme] first try
authored
123 ## members
6ce93ba @isaacs Put the uppercasing of tags back, and make it configurable.
isaacs authored
124
e1b22ec @dscape [readme] first try
authored
125 at all times, the parser object will have the following members:
6ce93ba @isaacs Put the uppercasing of tags back, and make it configurable.
isaacs authored
126
e1b22ec @dscape [readme] first try
authored
127 `line`, `column`, `position` - indications of the position in the json
4000360 @isaacs Document namespace stuff.
isaacs authored
128 document where the parser currently is looking.
6ce93ba @isaacs Put the uppercasing of tags back, and make it configurable.
isaacs authored
129
589fb00 @dscape [readme] fixes some small issues with readme
authored
130 `closed` - boolean indicating whether or not the parser can be written to.
131 if it's `true`, then wait for the `ready` event to write again.
6ce93ba @isaacs Put the uppercasing of tags back, and make it configurable.
isaacs authored
132
589fb00 @dscape [readme] fixes some small issues with readme
authored
133 `opt` - any options passed into the constructor.
6ce93ba @isaacs Put the uppercasing of tags back, and make it configurable.
isaacs authored
134
e1b22ec @dscape [readme] first try
authored
135 and a bunch of other stuff that you probably shouldn't touch.
6ce93ba @isaacs Put the uppercasing of tags back, and make it configurable.
isaacs authored
136
e1b22ec @dscape [readme] first try
authored
137 ## events
d90ce62 @isaacs For the readings.
isaacs authored
138
e1b22ec @dscape [readme] first try
authored
139 all events emit with a single argument. to listen to an event, assign a
140 function to `on<eventname>`. functions get executed in the this-context of
141 the parser object. the list of supported events are also in the exported
4000360 @isaacs Document namespace stuff.
isaacs authored
142 `EVENTS` array.
d90ce62 @isaacs For the readings.
isaacs authored
143
e1b22ec @dscape [readme] first try
authored
144 when using the stream interface, assign handlers using the `EventEmitter`
10dede4 @isaacs Document Stream interface
isaacs authored
145 `on` function in the normal fashion.
146
e1b22ec @dscape [readme] first try
authored
147 `error` - indication that something bad happened. the error will be hanging
148 out on `parser.error`, and must be deleted before parsing can continue. by
149 listening to this event, you can keep an eye on that kind of stuff. note:
150 this happens *much* more in strict mode. argument: instance of `Error`.
d90ce62 @isaacs For the readings.
isaacs authored
151
e1b22ec @dscape [readme] first try
authored
152 `value` - a json value. argument: value, can be a bool, null, string on number
d90ce62 @isaacs For the readings.
isaacs authored
153
e1b22ec @dscape [readme] first try
authored
154 `openobject` - object was opened. argument: key, a string with the first key of the object (if any)
4e0e18b @isaacs Add support for DOCTYPE and straighten out some comment bugs.
isaacs authored
155
e1b22ec @dscape [readme] first try
authored
156 `key` - an object key: argument: key, a string with the current key
d90ce62 @isaacs For the readings.
isaacs authored
157
e1b22ec @dscape [readme] first try
authored
158 `closeobject` - indication that an object was closed
6ce93ba @isaacs Put the uppercasing of tags back, and make it configurable.
isaacs authored
159
e1b22ec @dscape [readme] first try
authored
160 `openarray` - indication that an array was opened
d90ce62 @isaacs For the readings.
isaacs authored
161
e1b22ec @dscape [readme] first try
authored
162 `closearray` - indication that an array was closed
d90ce62 @isaacs For the readings.
isaacs authored
163
e1b22ec @dscape [readme] first try
authored
164 `end` - indication that the closed stream has ended.
d90ce62 @isaacs For the readings.
isaacs authored
165
e1b22ec @dscape [readme] first try
authored
166 `ready` - indication that the stream has reset, and is ready to be written
167 to.
d90ce62 @isaacs For the readings.
isaacs authored
168
e1b22ec @dscape [readme] first try
authored
169 ## samples
321b285 @laurie71 Add `opencdata` and `closecdata` events
laurie71 authored
170
589fb00 @dscape [readme] fixes some small issues with readme
authored
171 some [samples] are available to help you get started. one that creates a list of top npm contributors, and another that gets a bunch of data from twitter and generates valid json.
6ce93ba @isaacs Put the uppercasing of tags back, and make it configurable.
isaacs authored
172
e1b22ec @dscape [readme] first try
authored
173 # roadmap
321b285 @laurie71 Add `opencdata` and `closecdata` events
laurie71 authored
174
e1b22ec @dscape [readme] first try
authored
175 check [issues]
4000360 @isaacs Document namespace stuff.
isaacs authored
176
e1b22ec @dscape [readme] first try
authored
177 # contribute
4000360 @isaacs Document namespace stuff.
isaacs authored
178
e1b22ec @dscape [readme] first try
authored
179 everyone is welcome to contribute. patches, bug-fixes, new features
6ce93ba @isaacs Put the uppercasing of tags back, and make it configurable.
isaacs authored
180
e1b22ec @dscape [readme] first try
authored
181 1. create an [issue][issues] so the community can comment on your idea
ac51260 @dscape [readme] first try
authored
182 2. fork `clarinet`
e1b22ec @dscape [readme] first try
authored
183 3. create a new branch `git checkout -b my_branch`
184 4. create tests for the changes you made
185 5. make sure you pass both existing and newly inserted tests
186 6. commit your changes
187 7. push to your branch `git push origin my_branch`
188 8. create an pull request
189
190 helpful tips:
191
192 check `index.html`. there's two env vars you can set, `CRECORD` and `CDEBUG`.
193
194 * `CRECORD` allows you to `record` the event sequence from a new json test so you don't have to write everything.
195 * `CDEBUG` can be set to `info` or `debug`. `info` will `console.log` all emits, `debug` will `console.log` what happens to each char.
196
197 in `test/clarinet.js` there's two lines you might want to change. `#8` where you define `seps`, if you are isolating a test you probably just want to run one sep, so change this array to `[undefined]`. `#718` which says `for (var key in docs) {` is where you can change the docs you want to run. e.g. to run `foobar` i would do something like `for (var key in {foobar:''}) {`.
198
199 # meta
4000360 @isaacs Document namespace stuff.
isaacs authored
200
e1b22ec @dscape [readme] first try
authored
201 * code: `git clone git://github.com/dscape/clarinet.git`
202 * home: <http://github.com/dscape/clarinet>
203 * bugs: <http://github.com/dscape/clarinet/issues>
204 * build: [![build status](https://secure.travis-ci.org/dscape/clarinet.png)](http://travis-ci.org/dscape/clarinet)
0ae7456 @isaacs document noscript
isaacs authored
205
e1b22ec @dscape [readme] first try
authored
206 `(oO)--',-` in [caos]
4000360 @isaacs Document namespace stuff.
isaacs authored
207
e1b22ec @dscape [readme] first try
authored
208 [npm]: http://npmjs.org
209 [issues]: http://github.com/dscape/clarinet/issues
210 [caos]: http://caos.di.uminho.pt/
211 [saxjs]: http://github.com/isaacs/sax-js
212 [yajl]: https://github.com/lloyd/yajl
589fb00 @dscape [readme] fixes some small issues with readme
authored
213 [samples]: https://github.com/dscape/clarinet/tree/master/samples
4443293 @dscape Update README.md
authored
214 [blog]: http://writings.nunojob.com/2011/12/clarinet-sax-based-evented-streaming-json-parser-in-javascript-for-the-browser-and-nodejs.html
Something went wrong with that request. Please try again.