sax-js

For streaming data (e.g., reading from a file or network), use sax.createStream(strict, options). This returns a standard Node.js readable/writable stream that supports .pipe().

Note on Error Handling: Because the stream is a proper EventEmitter, unhandled errors will throw. You must listen to the error event. To continue parsing after an error, you must clear the error on the internal parser and call resume().

// stream usage
// takes the same options as the parser
var saxStream = require('sax').createStream(strict, options)

saxStream.on('error', function (e) {
  // unhandled errors will throw, since this is a proper node
  // event emitter.
  console.error('error!', e)
  // clear the error
  this._parser.error = null
  this._parser.resume()
})

saxStream.on('opentag', function (node) {
  // same object as above
})

// pipe is supported, and it's readable/writable
// same chunks coming in also go out.
fs.createReadStream('file.xml')
  .pipe(saxStream)
  .pipe(fs.createWriteStream('file-copy.xml'))

When creating a parser or stream, you can pass an opt object to customize behavior. All options default to false.

To use the parser directly, import the library and call sax.parser(strict). The strict argument is a boolean: set it to true for XML parsing (enforces well-formedness) or false for loose/HTML-style parsing.

To handle events, assign callback functions to the corresponding properties on the parser instance (e.g., parser.onopentag).

var sax = require('./lib/sax'),
  strict = true, // set to false for html-mode
  parser = sax.parser(strict)

parser.onerror = function (e) {
  // an error happened.
}
parser.ontext = function (t) {
  // got some text.  t is the string of text.
}
parser.onopentag = function (node) {
  // opened a tag.  node has "name" and "attributes"
}
parser.onattribute = function (attr) {
  // an attribute.  attr has "name" and "value"
}
parser.onend = function () {
  // parser stream is done, and ready to have more stuff written to it.
}

parser.write('<xml>Hello, <who name="world">world</who>!</xml>').close()

When initializing a parser via sax.parser(strict, opt) or sax.createStream(strict, opt), you can provide an opt object to customize behavior:

• lowercase: If true, tag names are converted to lowercase. (Also supports lowercasetags).
• xmlns: If true, enables namespace support.
• maxEntityCount: Maximum number of entities allowed (default: 512).
• maxEntityDepth: Maximum depth of entity nesting (default: 4).
• strictEntities: If true, uses sax.XML_ENTITIES for strict XML entity validation.
• unquotedAttributeValues: Controls whether unquoted attribute values are allowed (defaults to !strict).
• position: Boolean to enable/disable tracking of line and column numbers (default: true).
• noscript: If true (or if strict is true), the parser treats <script> tags differently.
• trim: (Used in text nodes) whether to trim whitespace.
• normalize: (Used in text nodes) whether to normalize whitespace sequences to a single space.

Events can be handled by assigning a function to on<eventname> (for the parser instance) or using .on('eventname', callback) (for the stream interface). All events emit a single argument.