simple-xpath-position/README.md

Create and evaluate simple XPath position expressions.

# Simple XPath Position

[![Build Status](https://travis-ci.org/tilgovi/simple-xpath-position.svg?branch=master)](https://travis-ci.org/tilgovi/simple-xpath-position)
[![NPM Package](https://img.shields.io/npm/v/simple-xpath-position.svg)](https://www.npmjs.com/package/simple-xpath-position)
[![Coverage](https://img.shields.io/codecov/c/github/tilgovi/simple-xpath-position/master.svg)](https://codecov.io/gh/tilgovi/simple-xpath-position)

Create and evaluate simple XPath position expressions.

## Installation

Using npm:

    npm install simple-xpath-position

## Usage

The module provides functions for describing and locating a DOM Node using
an XPath expression.

### API

#### `fromNode(node, [root])`

Convert a `Node` to an XPath expression.

If the optional parameter `root` is supplied, the computed XPath expression will
be relative to it.  Otherwise, the root of the document to which `node` belongs
is used as the root.

Returns a string.

#### `toNode(path, root, [resolver])`

Locate a single `Node` that matches the given XPath expression. The XPath
expressions are evaluated relative to the Node argument `root`.

If the optional parameter `resolver` is supplied, it will be used to resolve
any namespaces within the XPath expression.

Returns a `Node` or `null`.

## Compatibility

This library should work with any browser.

The presence of a working XPath evaluator is not strictly required. Without it,
the library will only support XPath expressions that use a child axis and
node names with number literal positions. All XPath expressions generated by
this library fit this description. For instance, the library can generate and
consume an expression such as `/html/body/article/p[3]`.

For better XPath support, consider bundling an implementation such as the
[Wicked Good XPath](https://github.com/google/wicked-good-xpath) library.

### Internet Explorer version 8

- There is no support for namespaces in X(HT)ML documents.

## Community

Originally, this code was part of the
[Annotator](http://annotatorjs.org/) project.

Any discussion should happen on the
[annotator-dev](https://lists.okfn.org/mailman/listinfo/annotator-dev) mailing
list.

## Development

To contribute, fork this repository and send a pull request with your changes,
including any necessary test and documentation updates.

## Testing

You can run the command-line test suite by executing `npm test`.

To run the test suite, install the karma test runner with the command
`npm install -g karma-cli` and then run `karma start`. Karma will print
instructions for debugging the tests in a browser.