Skip to content

Update README #43

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update README #43

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
259 changes: 128 additions & 131 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,168 +1,165 @@
node-xml
===================

# node-xml
(C) Rob Righter (@robrighter) 2009 - 2010, Licensed under the MIT-LICENSE
Contributions from David Joham

node-xml is an xml parser for node.js written in javascript.

# Install

npm install node-xml

API
---


SaxParser
---------

Node-xml provides a SAX2 parser interface that can take a string, file. The parser can take characters from the document in chunks. To send chunks of the document to the parser use 'parseString(xml)'
## Install
npm install node-xml
## API

#SAX Parser#
### SaxParser
Node-xml provides a SAX2 parser interface that can take a string, file. The parser can take characters from the document in chunks. To send chunks of the document to the parser use `parseString(xml)`
```js
new xml.SaxParser()
```
* Instantiate a new SaxParser
* returns: a SaxParser object

##new xml.SaxParser()##
* Instantiate a new SaxParser
* returns: a SaxParser object

##new xml.SaxParser(callback)##
* Instantiate a new SaxParser
* returns: a SaxParser object
* Arguments
*callback - a function that accepts the new sax parser as an argument
```js
new xml.SaxParser(callback)
```
* Instantiate a new SaxParser
* returns: a SaxParser object
* Arguments
* `callback` - a function that accepts the new sax parser as an argument

#Parse#

##parser.parseString(string)##

### Parse
```js
parser.parseString(string)
```
Parse an in memory string
* return: boolean. true if no errors, false otherwise
* Arguments
* string - a string representing the document to parse

##parser.parseFile(filename)##

* `string` - a string representing the document to parse
```js
parser.parseFile(filename)
```
Parse a file
* return: boolean. true if no errors, false otherwise
* Arguments
* filename - a string representing the file to be parsed
* `filename` - a string representing the file to be parsed

##parser.pause()##
```js
parser.pause()
```
pauses parsing of the document

##parser.resume()##
```js
parser.resume()
```
resumes parsing of the document

#Callbacks#

##parser.onStartDocument(function() {})##

### Callbacks
```js
parser.onStartDocument(function() {})
```
Called at the start of a document

##parse.onEndDocument(function() {})##

Called at the end of the document parse

##parser.onStartElementNS(function(elem, attrs, prefix, uri, namespaces) {})##

```js
parse.onEndDocument(function() {})
```
Called at the end of the document parse
```js
parser.onStartElementNS(function(elem, attrs, prefix, uri, namespaces) {})
```
Called on an open element tag
* Arguments
* elem - a string representing the element name
* attrs - an array of arrays: [[key, value], [key, value]]
* prefix - a string representing the namespace prefix of the element
* uri - the namespace URI of the element
* namespaces - an array of arrays: [[prefix, uri], [prefix, uri]]

##parser.onEndElementNS(function(elem, prefix, uri) {})##

* `elem` - a string representing the element name
* `attrs` - an array of arrays: `[[key, value]`, `[key, value]]`
* `prefix` - a string representing the namespace prefix of the element
* `uri` - the namespace URI of the element
* `namespaces` - an array of arrays: `[[prefix, uri], [prefix, uri]]`
```js
parser.onEndElementNS(function(elem, prefix, uri) {})
```
Called at the close of an element
* Arguments
* elem - a string representing the element name
* prefix - a string representing the namespace prefix of the element
* uri - the namespace URI of the element

##parser.onCharacters(function(chars) {})##

* `elem` - a string representing the element name
* `prefix` - a string representing the namespace prefix of the element
* `uri` - the namespace URI of the element
```js
parser.onCharacters(function(chars) {})
```
Called when a set of content characters is encountered
* Arguments
* chars - a string of characters

##parser.onCdata(function(cdata) {})##

* `chars` - a string of characters
```js
parser.onCdata(function(cdata) {})
```
Called when a CDATA is encountered
* Arguments
* cdata - a string representing the CDATA

##parser.onComment(function(msg) {})##

* `cdata` - a string representing the CDATA
```js
parser.onComment(function(msg) {})
```
Called when a comment is encountered
* Arguments
* msg - a string representing the comment

##parser.onWarning(function(msg) {})##
* `msg` - a string representing the comment

```js
parser.onWarning(function(msg) {})
```
Called when a warning is encountered
* Arguments
* msg - a string representing the warning message

##parser.onError(function(msg) {})##
* `msg` - a string representing the warning message

```js
parser.onError(function(msg) {})
```
Called when an error is encountered
* Arguments
* msg - a string representing the error message

EXAMPLE USAGE
-------------

var util = require('util');
var xml = require("./lib/node-xml");
* Arguments
* `msg` - a string representing the error message
## Example usage
``` javascript
var util = require('util');
var xml = require("./lib/node-xml");

var parser = new xml.SaxParser(function(cb) {
cb.onStartDocument(function() {

var parser = new xml.SaxParser(function(cb) {
cb.onStartDocument(function() {

});
cb.onEndDocument(function() {

});
cb.onStartElementNS(function(elem, attrs, prefix, uri, namespaces) {
util.log("=> Started: " + elem + " uri="+uri +" (Attributes: " + JSON.stringify(attrs) + " )");
});
cb.onEndElementNS(function(elem, prefix, uri) {
util.log("<= End: " + elem + " uri="+uri + "\n");
parser.pause();// pause the parser
setTimeout(function (){parser.resume();}, 200); //resume the parser
});
cb.onCharacters(function(chars) {
//util.log('<CHARS>'+chars+"</CHARS>");
});
cb.onCdata(function(cdata) {
util.log('<CDATA>'+cdata+"</CDATA>");
});
cb.onComment(function(msg) {
util.log('<COMMENT>'+msg+"</COMMENT>");
});
cb.onWarning(function(msg) {
util.log('<WARNING>'+msg+"</WARNING>");
});
cb.onError(function(msg) {
util.log('<ERROR>'+JSON.stringify(msg)+"</ERROR>");
});
});
});
cb.onEndDocument(function() {


//example read from chunks
parser.parseString("<html><body>");
parser.parseString("<!-- This is the start");
parser.parseString(" and the end of a comment -->");
parser.parseString("and lots");
parser.parseString("and lots of text&am");
parser.parseString("p;some more.");
parser.parseString("<![CD");
parser.parseString("ATA[ this is");
parser.parseString(" cdata ]]>");
parser.parseString("</body");
parser.parseString("></html>");

//example read from file
parser.parseFile("sample.xml");
});
cb.onStartElementNS(function(elem, attrs, prefix, uri, namespaces) {
util.log("=> Started: " + elem + " uri="+uri +" (Attributes: " + JSON.stringify(attrs) + " )");
});
cb.onEndElementNS(function(elem, prefix, uri) {
util.log("<= End: " + elem + " uri="+uri + "\n");
parser.pause();// pause the parser
setTimeout(function (){parser.resume();}, 200); //resume the parser
});
cb.onCharacters(function(chars) {
//util.log('<CHARS>'+chars+"</CHARS>");
});
cb.onCdata(function(cdata) {
util.log('<CDATA>'+cdata+"</CDATA>");
});
cb.onComment(function(msg) {
util.log('<COMMENT>'+msg+"</COMMENT>");
});
cb.onWarning(function(msg) {
util.log('<WARNING>'+msg+"</WARNING>");
});
cb.onError(function(msg) {
util.log('<ERROR>'+JSON.stringify(msg)+"</ERROR>");
});
});


//example read from chunks
parser.parseString("<html><body>");
parser.parseString("<!-- This is the start");
parser.parseString(" and the end of a comment -->");
parser.parseString("and lots");
parser.parseString("and lots of text&am");
parser.parseString("p;some more.");
parser.parseString("<![CD");
parser.parseString("ATA[ this is");
parser.parseString(" cdata ]]>");
parser.parseString("</body");
parser.parseString("></html>");

//example read from file
parser.parseFile("sample.xml");
```