#xpath methods

This page details the methods exposed on the `xpath` object.

### `xpath.select(expression[, node[, single]])`

Evaluates an XPath expression and returns the result. The return value is determined based on the result type of the expression (which can always be predicted ahead of time):

- A boolean value if the expression evaluates to a boolean value.
- A number if the expression evaluates to a numeric value.
- A string if the expression evaluates to a string.
- If the expression evaluates to a nodeset:
  - An array of nodes if `single` is unspecified or falsy
  - A single node (the first node in document order) or `undefined` if `single` is truthy
  
`node` is optional and if specified, is used as the context node for evaluating the expression. (It is necessary if the expression includes any node tests.)

`single` is optional and is ignored if the expression evaluates to anything other than a nodeset.

### `xpath.useNamespaces(mappings)`

Produces a function with the signature `func(expression, node)` that evaluates the provided xpath expression with the XML namespace definitions provided in `mapppings`.

`mappings` should be an object with namespace prefixes as its property names and namespace URIs as its property values.

Example usage:

```js
var expr = xpath.useNamespaces({ hp: 'http://www.example.com/harryPotter', bk: 'http://www.example.com/books' });
var result = expr('/bk:books/bk:book[@name = "Harry Potter and the Half-Blood Prince"]/hp:characters', myBooks);
```

### `xpath.select1(expression[, node])`

Alias for [`xpath.select(expression, node, true)`](#xpathselectexpression-node-single). Selects a single node or value.

### `xpath.parse(expression)`

Creates a parsed expression. See the [documentation page](parsed expressions.md) for details.