# docutils-parser

> Simple javascript parser for docutils xml documents

Latest version **1.0.0** (published 2020-03-25) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install docutils-parser
pnpm add docutils-parser
yarn add docutils-parser
bun add docutils-parser
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2020-03-25 |
| First published | 2019-03-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 11.7 KB |
| Known vulnerabilities | 0 (+3 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 3 |
| Author | Valentin Berlier |
| Maintainers | vberlier |
| Keywords | docutils, reStructuredText, xml, parser, sphinx |

## Links

- npm: https://www.npmjs.com/package/docutils-parser
- Repository: https://github.com/vberlier/docutils-parser
- Homepage: https://github.com/vberlier/docutils-parser#readme
- Issues: https://github.com/vberlier/docutils-parser/issues
- npm.io page: https://npm.io/package/docutils-parser

## Dependencies (1)

- [libxmljs](https://npm.io/package/libxmljs.md) ^0.19.7

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 1.0.0 (latest) — 2020-03-25
- 0.3.0 — 2019-10-22
- 0.2.0 — 2019-09-23
- 0.1.13 — 2019-08-22
- 0.1.12 — 2019-07-15
- 0.1.11 — 2019-03-12
- 0.1.10 — 2019-03-12
- 0.1.9 — 2019-03-12
- 0.1.8 — 2019-03-12
- 0.1.7 — 2019-03-12
- 0.1.6 — 2019-03-11
- 0.1.5 — 2019-03-11
- 0.1.4 — 2019-03-11
- 0.1.3 — 2019-03-10
- 0.1.2 — 2019-03-10
- … 1 more at https://npm.io/package/docutils-parser/versions

## README

# docutils-parser

[![Build Status](https://travis-ci.com/vberlier/docutils-parser.svg?branch=master)](https://travis-ci.com/vberlier/docutils-parser)
[![npm](https://img.shields.io/npm/v/docutils-parser.svg)](https://www.npmjs.com/package/docutils-parser)

> Simple javascript parser for docutils xml documents.

This package uses [libxmljs](https://github.com/libxmljs/libxmljs) to parse and turn [docutils xml documents](http://docutils.sourceforge.net/docs/ref/doctree.html) into digestible javascript objects. This can be useful for working with documentation generated by tools like [sphinx](http://www.sphinx-doc.org).

```js
const docutils = require('docutils-parser')

const document = docutils.parse(`
  <document source=".../hello.rst">
    <section ids="hello-world" names="hello,\\ world!">
      <title>Hello, world!</title>
    </section>
  </document>
`)

console.log(document.children[0].children[0])
// Output: { tag: 'title', attributes: {}, children: [ 'Hello, world!' ] }
```

## Installation

You can install `docutils-parser` with your `npm` client of choice.

```bash
$ 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.

```js
{
  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.

```js
try {
  docutils.parse('invalid document')
} catch (err) {
  console.log(err)
  // 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.

```js
const titleToUpperCase = parser => {
  parser.on('element:title', element => {
    element.children[0] = element.children[0].toUpperCase()
  })
}

const document = docutils.parse(string, [titleToUpperCase])

console.log(document.children[0].children[0])
// 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.

```js
const parser = new docutils.DocumentParser()
const document = parser.parse(string)
```

Most of the time, you'll only interact with the parser through plugins. The `docutils.DocumentParser` class inherits from the nodejs [`EventEmitter`](https://nodejs.org/api/events.html#events_class_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](https://jestjs.io/) for testing.

```bash
$ npm test
```

The code follows the [javascript standard](https://standardjs.com/) style guide.

```bash
$ npm run lint
```

---

License - [MIT](https://github.com/vberlier/docutils-parser/blob/master/LICENSE)

---
_Source: https://npm.io/package/docutils-parser · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._