A sax-\/style parser for XML and HTML.

Designed with \href{http://nodejs.org/}{\texttt{ node}} in mind, but should work fine in the browser or other Common\+JS implementations.\hypertarget{md_sfcode_node_modules_sax_README_autotoc_md26250}{}\doxysection{What This Is}\label{md_sfcode_node_modules_sax_README_autotoc_md26250}

\begin{DoxyItemize}
\item A very simple tool to parse through an XML string.
\item A stepping stone to a streaming HTML parser.
\item A handy way to deal with RSS and other mostly-\/ok-\/but-\/kinda-\/broken XML docs.
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_sax_README_autotoc_md26251}{}\doxysection{What This Is (probably) Not}\label{md_sfcode_node_modules_sax_README_autotoc_md26251}

\begin{DoxyItemize}
\item An HTML Parser -\/ That\textquotesingle{}s a fine goal, but this isn\textquotesingle{}t it. It\textquotesingle{}s just XML.
\item A DOM Builder -\/ You can use it to build an object model out of XML, but it doesn\textquotesingle{}t do that out of the box.
\item XSLT -\/ No DOM = no querying.
\item 100\% Compliant with (some other SAX implementation) -\/ Most SAX implementations are in Java and do a lot more than this does.
\item An XML Validator -\/ It does a little validation when in strict mode, but not much.
\item A Schema-\/\+Aware XSD Thing -\/ Schemas are an exercise in fetishistic masochism.
\item A DTD-\/aware Thing -\/ Fetching DTDs is a much bigger job.
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_sax_README_autotoc_md26252}{}\doxysection{Regarding $<$tt$>$$<$!\+DOCTYPE$<$/tt$>$s and $<$tt$>$$<$!\+ENTITY$<$/tt$>$s}\label{md_sfcode_node_modules_sax_README_autotoc_md26252}
The parser will handle the basic XML entities in text nodes and attribute values\+: {\ttfamily \& $<$ $>$ \textquotesingle{} "{}}. It\textquotesingle{}s possible to define additional entities in XML by putting them in the DTD. This parser doesn\textquotesingle{}t do anything with that. If you want to listen to the {\ttfamily ondoctype} event, and then fetch the doctypes, and read the entities and add them to {\ttfamily parser.\+ENTITIES}, then be my guest.

Unknown entities will fail in strict mode, and in loose mode, will pass through unmolested.\hypertarget{md_sfcode_node_modules_sax_README_autotoc_md26253}{}\doxysection{Usage}\label{md_sfcode_node_modules_sax_README_autotoc_md26253}

\begin{DoxyCode}{0}
\DoxyCodeLine{var sax = require("{}./lib/sax"{}),}
\DoxyCodeLine{  strict = true, // set to false for html-\/mode}
\DoxyCodeLine{  parser = sax.parser(strict);}
\DoxyCodeLine{}
\DoxyCodeLine{parser.onerror = function (e) \{}
\DoxyCodeLine{  // an error happened.}
\DoxyCodeLine{\};}
\DoxyCodeLine{parser.ontext = function (t) \{}
\DoxyCodeLine{  // got some text.  t is the string of text.}
\DoxyCodeLine{\};}
\DoxyCodeLine{parser.onopentag = function (node) \{}
\DoxyCodeLine{  // opened a tag.  node has "{}name"{} and "{}attributes"{}}
\DoxyCodeLine{\};}
\DoxyCodeLine{parser.onattribute = function (attr) \{}
\DoxyCodeLine{  // an attribute.  attr has "{}name"{} and "{}value"{}}
\DoxyCodeLine{\};}
\DoxyCodeLine{parser.onend = function () \{}
\DoxyCodeLine{  // parser stream is done, and ready to have more stuff written to it.}
\DoxyCodeLine{\};}
\DoxyCodeLine{}
\DoxyCodeLine{parser.write('<xml>Hello, <who name="{}world"{}>world</who>!</xml>').close();}
\DoxyCodeLine{}
\DoxyCodeLine{// stream usage}
\DoxyCodeLine{// takes the same options as the parser}
\DoxyCodeLine{var saxStream = require("{}sax"{}).createStream(strict, options)}
\DoxyCodeLine{saxStream.on("{}error"{}, function (e) \{}
\DoxyCodeLine{  // unhandled errors will throw, since this is a proper node}
\DoxyCodeLine{  // event emitter.}
\DoxyCodeLine{  console.error("{}error!"{}, e)}
\DoxyCodeLine{  // clear the error}
\DoxyCodeLine{  this.\_parser.error = null}
\DoxyCodeLine{  this.\_parser.resume()}
\DoxyCodeLine{\})}
\DoxyCodeLine{saxStream.on("{}opentag"{}, function (node) \{}
\DoxyCodeLine{  // same object as above}
\DoxyCodeLine{\})}
\DoxyCodeLine{// pipe is supported, and it's readable/writable}
\DoxyCodeLine{// same chunks coming in also go out.}
\DoxyCodeLine{fs.createReadStream("{}file.xml"{})}
\DoxyCodeLine{  .pipe(saxStream)}
\DoxyCodeLine{  .pipe(fs.createWriteStream("{}file-\/copy.xml"{})) }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_sax_README_autotoc_md26254}{}\doxysection{Arguments}\label{md_sfcode_node_modules_sax_README_autotoc_md26254}
Pass the following arguments to the parser function. All are optional.

{\ttfamily strict} -\/ Boolean. Whether or not to be a jerk. Default\+: {\ttfamily false}.

{\ttfamily opt} -\/ Object bag of settings regarding string formatting. All default to {\ttfamily false}.

Settings supported\+:


\begin{DoxyItemize}
\item {\ttfamily trim} -\/ Boolean. Whether or not to trim text and comment nodes.
\item {\ttfamily normalize} -\/ Boolean. If true, then turn any whitespace into a single space.
\item {\ttfamily lowercase} -\/ Boolean. If true, then lowercase tag names and attribute names in loose mode, rather than uppercasing them.
\item {\ttfamily xmlns} -\/ Boolean. If true, then namespaces are supported.
\item {\ttfamily position} -\/ Boolean. If false, then don\textquotesingle{}t track line/col/position.
\item {\ttfamily strict\+Entities} -\/ Boolean. If true, only parse \href{http://www.w3.org/TR/REC-xml/\#sec-predefined-ent}{\texttt{ predefined XML entities}} ({\ttfamily \&}, {\ttfamily \textquotesingle{}}, {\ttfamily $>$}, {\ttfamily $<$}, and {\ttfamily "{}})
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_sax_README_autotoc_md26255}{}\doxysection{Methods}\label{md_sfcode_node_modules_sax_README_autotoc_md26255}
{\ttfamily write} -\/ Write bytes onto the stream. You don\textquotesingle{}t have to do this all at once. You can keep writing as much as you want.

{\ttfamily close} -\/ Close the stream. Once closed, no more data may be written until it is done processing the buffer, which is signaled by the {\ttfamily end} event.

{\ttfamily resume} -\/ To gracefully handle errors, assign a listener to the {\ttfamily error} event. Then, when the error is taken care of, you can call {\ttfamily resume} to continue parsing. Otherwise, the parser will not continue while in an error state.\hypertarget{md_sfcode_node_modules_sax_README_autotoc_md26256}{}\doxysection{Members}\label{md_sfcode_node_modules_sax_README_autotoc_md26256}
At all times, the parser object will have the following members\+:

{\ttfamily line}, {\ttfamily column}, {\ttfamily position} -\/ Indications of the position in the XML document where the parser currently is looking.

{\ttfamily start\+Tag\+Position} -\/ Indicates the position where the current tag starts.

{\ttfamily closed} -\/ Boolean indicating whether or not the parser can be written to. If it\textquotesingle{}s {\ttfamily true}, then wait for the {\ttfamily ready} event to write again.

{\ttfamily strict} -\/ Boolean indicating whether or not the parser is a jerk.

{\ttfamily opt} -\/ Any options passed into the constructor.

{\ttfamily tag} -\/ The current tag being dealt with.

And a bunch of other stuff that you probably shouldn\textquotesingle{}t touch.\hypertarget{md_sfcode_node_modules_sax_README_autotoc_md26257}{}\doxysection{Events}\label{md_sfcode_node_modules_sax_README_autotoc_md26257}
All events emit with a single argument. To listen to an event, assign a function to {\ttfamily on$<$eventname$>$}. Functions get executed in the this-\/context of the parser object. The list of supported events are also in the exported {\ttfamily EVENTS} array.

When using the stream interface, assign handlers using the Event\+Emitter {\ttfamily on} function in the normal fashion.

{\ttfamily error} -\/ Indication that something bad happened. The error will be hanging out on {\ttfamily parser.\+error}, and must be deleted before parsing can continue. By listening to this event, you can keep an eye on that kind of stuff. Note\+: this happens {\itshape much} more in strict mode. Argument\+: instance of {\ttfamily Error}.

{\ttfamily text} -\/ Text node. Argument\+: string of text.

{\ttfamily doctype} -\/ The {\ttfamily $<$!\+DOCTYPE} declaration. Argument\+: doctype string.

{\ttfamily processinginstruction} -\/ Stuff like {\ttfamily $<$?xml foo=\char`\"{}blerg\char`\"{} ?$>$}. Argument\+: object with {\ttfamily name} and {\ttfamily body} members. Attributes are not parsed, as processing instructions have implementation dependent semantics.

{\ttfamily sgmldeclaration} -\/ Random SGML declarations. Stuff like {\ttfamily $<$!\+ENTITY p$>$} would trigger this kind of event. This is a weird thing to support, so it might go away at some point. SAX isn\textquotesingle{}t intended to be used to parse SGML, after all.

{\ttfamily opentagstart} -\/ Emitted immediately when the tag name is available, but before any attributes are encountered. Argument\+: object with a {\ttfamily name} field and an empty {\ttfamily attributes} set. Note that this is the same object that will later be emitted in the {\ttfamily opentag} event.

{\ttfamily opentag} -\/ An opening tag. Argument\+: object with {\ttfamily name} and {\ttfamily attributes}. In non-\/strict mode, tag names are uppercased, unless the {\ttfamily lowercase} option is set. If the {\ttfamily xmlns} option is set, then it will contain namespace binding information on the {\ttfamily ns} member, and will have a {\ttfamily local}, {\ttfamily prefix}, and {\ttfamily uri} member.

{\ttfamily closetag} -\/ A closing tag. In loose mode, tags are auto-\/closed if their parent closes. In strict mode, well-\/formedness is enforced. Note that self-\/closing tags will have {\ttfamily close\+Tag} emitted immediately after {\ttfamily open\+Tag}. Argument\+: tag name.

{\ttfamily attribute} -\/ An attribute node. Argument\+: object with {\ttfamily name} and {\ttfamily value}. In non-\/strict mode, attribute names are uppercased, unless the {\ttfamily lowercase} option is set. If the {\ttfamily xmlns} option is set, it will also contains namespace information.

{\ttfamily comment} -\/ A comment node. Argument\+: the string of the comment.

{\ttfamily opencdata} -\/ The opening tag of a {\ttfamily $<$!\mbox{[}CDATA\mbox{[}} block.

{\ttfamily cdata} -\/ The text of a {\ttfamily $<$!\mbox{[}CDATA\mbox{[}} block. Since {\ttfamily $<$!\mbox{[}CDATA\mbox{[}} blocks can get quite large, this event may fire multiple times for a single block, if it is broken up into multiple {\ttfamily write()}s. Argument\+: the string of random character data.

{\ttfamily closecdata} -\/ The closing tag ({\ttfamily \mbox{]}\mbox{]}$>$}) of a {\ttfamily $<$!\mbox{[}CDATA\mbox{[}} block.

{\ttfamily opennamespace} -\/ If the {\ttfamily xmlns} option is set, then this event will signal the start of a new namespace binding.

{\ttfamily closenamespace} -\/ If the {\ttfamily xmlns} option is set, then this event will signal the end of a namespace binding.

{\ttfamily end} -\/ Indication that the closed stream has ended.

{\ttfamily ready} -\/ Indication that the stream has reset, and is ready to be written to.

{\ttfamily noscript} -\/ In non-\/strict mode, {\ttfamily $<$script$>$} tags trigger a {\ttfamily \char`\"{}script\char`\"{}} event, and their contents are not checked for special xml characters. If you pass {\ttfamily noscript\+: true}, then this behavior is suppressed.\hypertarget{md_sfcode_node_modules_sax_README_autotoc_md26258}{}\doxysection{Reporting Problems}\label{md_sfcode_node_modules_sax_README_autotoc_md26258}
It\textquotesingle{}s best to write a failing test if you find an issue. I will always accept pull requests with failing tests if they demonstrate intended behavior, but it is very hard to figure out what issue you\textquotesingle{}re describing without a test. Writing a test is also the best way for you yourself to figure out if you really understand the issue you think you have with sax-\/js. 