# xml-query

> Super small library to retrieve values and attributes from the XML AST generated by xml-reader

Latest version **1.5.0** (published 2018-09-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install xml-query
pnpm add xml-query
yarn add xml-query
bun add xml-query
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.5.0 |
| Published | 2018-09-29 |
| First published | 2016-06-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 15.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Pedro Ladaria |
| Maintainers | pladaria |
| Keywords | xml, ast, get, find, query, get, read, tags, values, attributes, find, children, nodes |

## Links

- npm: https://www.npmjs.com/package/xml-query
- Repository: https://github.com/pladaria/xml-query
- Homepage: https://github.com/pladaria/xml-query#readme
- Issues: https://github.com/pladaria/xml-query/issues
- npm.io page: https://npm.io/package/xml-query

## 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.5.0 (latest) — 2018-09-29
- 1.4.0 — 2016-10-03
- 1.3.2 — 2016-09-09
- 1.3.1 — 2016-08-21
- 1.3.0 — 2016-07-11
- 1.2.2 — 2016-06-28
- 1.2.1 — 2016-06-28
- 1.2.0 — 2016-06-28
- 1.1.0 — 2016-06-19
- 1.0.1 — 2016-06-19
- 1.0.0 — 2016-06-19

## README

<p align="center">
<img width="80%" src="https://raw.githubusercontent.com/pladaria/xml-query/master/logo.png" alt="XML-Query"/>
</p>
<p align="center">
Super small (~60 LOC) library for retrieving values and attributes<br>
from the XML AST generated by <a href="http://github.com/pladaria/xml-reader">xml-reader</a><br>
with an easy-to-use jQuery-like interface.
</p>
<p align="center">
<a href="https://travis-ci.org/pladaria/xml-query"><img src="https://travis-ci.org/pladaria/xml-query.svg" alt="Build Status"/></a>
<a href='https://coveralls.io/github/pladaria/xml-query?branch=master'><img src='https://coveralls.io/repos/github/pladaria/xml-query/badge.svg?branch=master' alt='Coverage Status' /></a>
</p>

## Install

```bash
npm install --save xml-query
```

## Usage

### Reading xml streams/strings

The following XML will be used to illustrate all examples

```xml
<message id="1001" date="2016-06-19">
    <from>Bob</from>
    <to>Alice</to>
    <subject>Hello</subject>
    <body>Bla bla bla</body>
</message>
```

Let's read the XML using [xml-reader](http://github.com/pladaria/xml-reader).

```javascript
const XmlReader = require('xml-reader');

const xml =
`<message id="1001" date="2016-06-19">
    <from>Bob</from>
    <to>Alice</to>
    <subject>Hello</subject>
    <body>Bla bla bla</body>
</message>`;

const ast = XmlReader.parseSync(xml);
```

### xmlQuery()

```javascript
const xmlQuery = require('xml-query');

// creating from single ast
const xq = xmlQuery(ast);

// creating from an array of asts
const xq = xmlQuery([ast, ...more]);
```

### .get()

Retrieve one of the elements.

```javascript
xmlQuery(ast).find('body').get(2); // returns the `subject` node
```

### .find()

Find by name. Including top level nodes and all its children.

```javascript
xmlQuery(ast).find('body'); // xmlQuery containing the body element
```

### .has()

Returns `true` if it has the given element. Faster than `find()` because it stops on first occurence.

```javascript
xmlQuery(ast).has('body'); // true
```

### .attr()

Get all attributes. If a name is provided, it returns the value for that key.

```javascript
xmlQuery(ast).attr(); // {id: '1001', date: '2016-06-19'}
xmlQuery(ast).attr('id'); // '1001'
```

### .children()

Returns a new xmlQuery object containing the children of the top level elements.

```javascript
xmlQuery(ast).children();
```

### .each()

Iterate over a xmlQuery object, executing a function for each element.

```javascript
xmlQuery(ast).each(node => console.log(node.name));
// from
// to
// subject
// body
```

### .map()

Iterate over a xmlQuery object, executing a function for each element. Returns the results in an array.

```javascript
xmlQuery(ast).map(node => node.name); // ['from', 'to', 'subject', 'body']
```

### .prop()

Get the value of a property for the first element in the set.

```javascript
xmlQuery(ast).prop('name'); // 'message'
```

### .text()

Get the combined text contents of each element, including their descendants

```javascript
xmlQuery(ast).find('subject').text(); // 'hello'
```

### .eq()

Returns a new XmlQuery object for the selected element by index

```javascript
xmlQuery(ast).children().eq(2); // xmlQuery containing the 'subject' node
```

### .first()

Returns a new XmlQuery object for the first element. Same as `.eq(0)`

```javascript
xmlQuery(ast).children().first(); // xmlQuery containing the 'from' node
```

### .last()

Returns a new XmlQuery object for the last element. Same as `.eq(length - 1)`

```javascript
xmlQuery(ast).children().last(); // xmlQuery containing the 'body' node
```

### .length

Number of elements. Returns the same result as `.size()`

```javascript
xmlQuery(ast).children().length; // 4
```

### .size()

Number of elements. Returns the same result as `.length`

```javascript
xmlQuery(ast).children().size(); // 4
```

## License

MIT

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