Initial import
[darksolar] / node_modules / everyauth / node_modules / xml2js / node_modules / sax / README.md
1 # sax js
2
3 A sax-style parser for XML and HTML.
4
5 Designed with [node](http://nodejs.org/) in mind, but should work fine in
6 the browser or other CommonJS implementations.
7
8 ## What This Is
9
10 * A very simple tool to parse through an XML string.
11 * A stepping stone to a streaming HTML parser.
12 * A handy way to deal with RSS and other mostly-ok-but-kinda-broken XML 
13   docs.
14
15 ## What This Is (probably) Not
16
17 * An HTML Parser - That's a fine goal, but this isn't it.  It's just
18   XML.
19 * A DOM Builder - You can use it to build an object model out of XML,
20   but it doesn't do that out of the box.
21 * XSLT - No DOM = no querying.
22 * 100% Compliant with (some other SAX implementation) - Most SAX
23   implementations are in Java and do a lot more than this does.
24 * An XML Validator - It does a little validation when in strict mode, but
25   not much.
26 * A Schema-Aware XSD Thing - Schemas are an exercise in fetishistic 
27   masochism.
28 * A DTD-aware Thing - Fetching DTDs is a much bigger job.
29
30 ## Regarding `<!DOCTYPE`s and `<!ENTITY`s
31
32 The parser will handle the basic XML entities in text nodes and attribute
33 values: `&amp; &lt; &gt; &apos; &quot;`. It's possible to define additional
34 entities in XML by putting them in the DTD. This parser doesn't do anything
35 with that. If you want to listen to the `ondoctype` event, and then fetch
36 the doctypes, and read the entities and add them to `parser.ENTITIES`, then
37 be my guest.
38
39 Unknown entities will fail in strict mode, and in loose mode, will pass
40 through unmolested.
41
42 ## Usage
43
44     var sax = require("./lib/sax"),
45       strict = true, // set to false for html-mode
46       parser = sax.parser(strict);
47
48     parser.onerror = function (e) {
49       // an error happened.
50     };
51     parser.ontext = function (t) {
52       // got some text.  t is the string of text.
53     };
54     parser.onopentag = function (node) {
55       // opened a tag.  node has "name" and "attributes"
56     };
57     parser.onattribute = function (attr) {
58       // an attribute.  attr has "name" and "value"
59     };
60     parser.onend = function () {
61       // parser stream is done, and ready to have more stuff written to it.
62     };
63
64     parser.write('<xml>Hello, <who name="world">world</who>!</xml>').close();
65
66     // stream usage
67     // takes the same options as the parser
68     var saxStream = require("sax").createStream(strict, options)
69     saxStream.on("error", function (e) {
70       // unhandled errors will throw, since this is a proper node
71       // event emitter.
72       console.error("error!", e)
73       // clear the error
74       this._parser.error = null
75       this._parser.resume()
76     })
77     saxStream.on("opentag", function (node) {
78       // same object as above
79     })
80     // pipe is supported, and it's readable/writable
81     // same chunks coming in also go out.
82     fs.createReadStream("file.xml")
83       .pipe(saxStream)
84       .pipe(fs.createReadStream("file-copy.xml"))
85
86
87
88 ## Arguments
89
90 Pass the following arguments to the parser function.  All are optional.
91
92 `strict` - Boolean. Whether or not to be a jerk. Default: `false`.
93
94 `opt` - Object bag of settings regarding string formatting.  All default to `false`.
95
96 Settings supported:
97
98 * `trim` - Boolean. Whether or not to trim text and comment nodes.
99 * `normalize` - Boolean. If true, then turn any whitespace into a single
100   space.
101 * `lowercase` - Boolean. If true, then lowercase tag names and attribute names
102   in loose mode, rather than uppercasing them.
103 * `xmlns` - Boolean. If true, then namespaces are supported.
104
105 ## Methods
106
107 `write` - Write bytes onto the stream. You don't have to do this all at
108 once. You can keep writing as much as you want.
109
110 `close` - Close the stream. Once closed, no more data may be written until
111 it is done processing the buffer, which is signaled by the `end` event.
112
113 `resume` - To gracefully handle errors, assign a listener to the `error`
114 event. Then, when the error is taken care of, you can call `resume` to
115 continue parsing. Otherwise, the parser will not continue while in an error
116 state.
117
118 ## Members
119
120 At all times, the parser object will have the following members:
121
122 `line`, `column`, `position` - Indications of the position in the XML
123 document where the parser currently is looking.
124
125 `startTagPosition` - Indicates the position where the current tag starts.
126
127 `closed` - Boolean indicating whether or not the parser can be written to.
128 If it's `true`, then wait for the `ready` event to write again.
129
130 `strict` - Boolean indicating whether or not the parser is a jerk.
131
132 `opt` - Any options passed into the constructor.
133
134 `tag` - The current tag being dealt with.
135
136 And a bunch of other stuff that you probably shouldn't touch.
137
138 ## Events
139
140 All events emit with a single argument. To listen to an event, assign a
141 function to `on<eventname>`. Functions get executed in the this-context of
142 the parser object. The list of supported events are also in the exported
143 `EVENTS` array.
144
145 When using the stream interface, assign handlers using the EventEmitter
146 `on` function in the normal fashion.
147
148 `error` - Indication that something bad happened. The error will be hanging
149 out on `parser.error`, and must be deleted before parsing can continue. By
150 listening to this event, you can keep an eye on that kind of stuff. Note:
151 this happens *much* more in strict mode. Argument: instance of `Error`.
152
153 `text` - Text node. Argument: string of text.
154
155 `doctype` - The `<!DOCTYPE` declaration. Argument: doctype string.
156
157 `processinginstruction` - Stuff like `<?xml foo="blerg" ?>`. Argument:
158 object with `name` and `body` members. Attributes are not parsed, as
159 processing instructions have implementation dependent semantics.
160
161 `sgmldeclaration` - Random SGML declarations. Stuff like `<!ENTITY p>`
162 would trigger this kind of event. This is a weird thing to support, so it
163 might go away at some point. SAX isn't intended to be used to parse SGML,
164 after all.
165
166 `opentag` - An opening tag. Argument: object with `name` and `attributes`.
167 In non-strict mode, tag names are uppercased, unless the `lowercase`
168 option is set.  If the `xmlns` option is set, then it will contain
169 namespace binding information on the `ns` member, and will have a
170 `local`, `prefix`, and `uri` member.
171
172 `closetag` - A closing tag. In loose mode, tags are auto-closed if their
173 parent closes. In strict mode, well-formedness is enforced. Note that
174 self-closing tags will have `closeTag` emitted immediately after `openTag`.
175 Argument: tag name.
176
177 `attribute` - An attribute node.  Argument: object with `name` and `value`.
178 In non-strict mode, attribute names are uppercased, unless the `lowercase`
179 option is set.  If the `xmlns` option is set, it will also contains namespace
180 information.
181
182 `comment` - A comment node.  Argument: the string of the comment.
183
184 `opencdata` - The opening tag of a `<![CDATA[` block.
185
186 `cdata` - The text of a `<![CDATA[` block. Since `<![CDATA[` blocks can get
187 quite large, this event may fire multiple times for a single block, if it
188 is broken up into multiple `write()`s. Argument: the string of random
189 character data.
190
191 `closecdata` - The closing tag (`]]>`) of a `<![CDATA[` block.
192
193 `opennamespace` - If the `xmlns` option is set, then this event will
194 signal the start of a new namespace binding.
195
196 `closenamespace` - If the `xmlns` option is set, then this event will
197 signal the end of a namespace binding.
198
199 `end` - Indication that the closed stream has ended.
200
201 `ready` - Indication that the stream has reset, and is ready to be written
202 to.
203
204 `noscript` - In non-strict mode, `<script>` tags trigger a `"script"`
205 event, and their contents are not checked for special xml characters.
206 If you pass `noscript: true`, then this behavior is suppressed.
207
208 ## Reporting Problems
209
210 It's best to write a failing test if you find an issue.  I will always
211 accept pull requests with failing tests if they demonstrate intended
212 behavior, but it is very hard to figure out what issue you're describing
213 without a test.  Writing a test is also the best way for you yourself
214 to figure out if you really understand the issue you think you have with
215 sax-js.