xmldoc

What is xmldoc?

The xmldoc npm package is a lightweight XML parser that provides an easy and manageable way to parse XML documents and navigate their structures in Node.js applications. It allows users to load XML documents as objects and access their attributes, child elements, and text content programmatically.

What are xmldoc's main functionalities?

Parsing XML

This feature allows the parsing of XML strings into a manageable object structure, enabling easy access to different parts of the XML document.

var XmlDocument = require('xmldoc').XmlDocument;
var xml = new XmlDocument('<root><child foo="bar">Hello, world!</child></root>');
console.log(xml.firstChild.attr.foo); // outputs: bar

Navigating Nodes

This feature enables navigation to specific nodes by their names and retrieval of their text content.

var child = xml.childNamed('child');
console.log(child.val); // outputs: Hello, world!

Accessing Attributes

This feature allows access to the attributes of XML nodes, making it easy to retrieve values associated with different attributes in an element.

console.log(xml.firstChild.attr.foo); // outputs: bar

Other packages similar to xmldoc

libxmljs

libxmljs is a more feature-rich XML parsing library that provides bindings to the libxml C library. It offers faster parsing and XPath support, making it suitable for more complex XML processing tasks compared to xmldoc.

xml2js

xml2js is another popular XML parsing library that, unlike xmldoc, converts XML documents into JSON format. This can be particularly useful when the end goal is to work with JSON objects instead of navigating XML nodes directly.

README

Introduction

xmldoc lets you parse XML documents with ease. It's a pure-JavaScript, one-file XML document class with a single dependency on the excellent sax parser.

For more on why I wrote this class, see the blog post.

Installation

npm install xmldoc

Or just download the repository and include it in your node_modules directly. Or just download the single JS file!

Usage

var xmldoc = require('../lib/xmldoc');

var document = new xmldoc.XmlDocument("<some>xml</some>");

... do things

Classes

The primary exported class is XmlDocument, which you'll use to consume your XML text. XmlDocument contains a hierarchy of XmlElement instances representing the XML structure.

Both XmlElement and XmlDocument contain the same members and methods you can call to traverse the document or a subtree.

Members

• name - the node name, like "tat" for <tat>.
• attr - an object dict containing attribute properties, like bookNode.attr.title for <book title="...">.
• val - the string "value" of the node, if any, like "world" for <hello>world</hello>.
• children - an array of XmlElement children of the node.

Each member defaults to a sensible "empty" value like {} for attr, [] for children, and "" for val.

Methods

All methods with child in the name operate only on direct children; they do not do a deep/recursive search.

• eachChild(func) - similar to underscore's each method, it will call func(child, index, array) for each child of the given node.

• childNamed(name) - pass it the name of a child node and it will search for and return the first one found, or undefined.

• childrenNamed(name) - like childNamed but returns all matching children in an array, or [].

• childWithAttribute(name,value) - searches for the first child with the given attribute value. You can omit value to just find the first node with the given attribute defined at all.

• descendantWithPath(path) - searches for a specific "path" uses dot notation.

Example:

<book>
  <author>
    <name isProper="true">George R. R. Martin</name>
    ...
  </author>
  ...
</book>

If you just want the <name> node and you have the XmlElement for the <book> node, you can say:

var nameNode = bookNode.descendantWithPath("author.name"); // return <name> node

• valueWithPath(path) - just like descendantWithPath, but goes deeper and extracts the val of the node.

Example:

var authorName = bookNode.valueWithPath("author.name"); // return "George R. R. Martin"

You can also use the @ character to request the value of a particular attribute instead:

var authorIsProper = bookNode.valueWithPath("author.name@isProper"); // return "true"

This is not XPath! It's just a thing I made up, OK?

• toString() - this is just an override of the standard JavaScript method, it will give you the pretty-printed string representation of your XML document or element. Note that this is for debugging only! It will truncate any long node values.

Feedback

Feel free to file issues or hit me up on Twitter.