docutils-parser
Simple javascript parser for docutils xml documents.
This package uses libxmljs to parse and turn docutils xml documents into digestible javascript objects. This can be useful for working with documentation generated by tools like sphinx.
const docutils = const document = docutils console// Output: { tag: 'title', attributes: {}, children: [ 'Hello, world!' ] }
Installation
You can install docutils-parser
with your npm
client of choice.
$ npm install docutils-parser
Usage
docutils.parse(string, plugins = [])
Parse the input string and return a hierarchy of plain javascript objects. The function will throw an error if the input string isn't valid xml.
Let's take a look at what the function returned in the previous example.
tag: 'document' attributes: source: '.../hello.rst' children: tag: 'section' attributes: ids: 'hello-world' names: 'hello, world!' children: tag: 'title' attributes: {} children: 'Hello, world!'
As you can see, each element is represented as a plain javascript object with a specific structure:
- The
tag
property is the name of the element - The
attributes
property is an object mapping each attribute name to its value - The
children
property is an array that can contain strings and other elements
Remember to catch parsing errors where appropriate.
try docutils catch err console // Error: Start tag expected, '<' not found
Plugins
The second argument of the docutils.parse()
function is an optional array of plugins. Plugins are simply functions that take an instance of docutils.DocumentParser
as parameter.
const titleToUpperCase = { parser} const document = docutils console// Output: { tag: 'title', attributes: {}, children: [ 'HELLO, WORLD!' ] }
docutils.DocumentParser({ plugins = [] } = {})
While you should probably always use the docutils.parse()
function directly, instantiating the parser yourself is also possible.
const parser = const document = parser
Most of the time, you'll only interact with the parser through plugins. The docutils.DocumentParser
class inherits from the nodejs EventEmitter
and lets you hook into various stages of the parsing process.
Event | Arguments | Description |
---|---|---|
document:start |
Emitted before parsing a document | |
document:end |
document |
Emitted after parsing a document |
element |
element |
Emitted after parsing an element |
element:TAG_NAME |
element |
Emitted after parsing a TAG_NAME element |
Contributing
Contributions are welcome. This project uses jest for testing.
$ npm test
The code follows the javascript standard style guide.
$ npm run lint
License - MIT