# XPath Reference (version 3.12)

#### Contents

- xpath
- xpath_save
- xpath_load

Browse through the topics in the contents list to the right.

## xpath

Selects nodes and attributes from a standard xpath expression.

### xpath(doc, step, set)

#### Parameters

Returns | The XML source of the selection. If the content was set to be modified the previous value will be returned.
doc | an xml object returned by xpath_load()
step | a valid XPath 2.0 expression
set | (optional)text content to replace the current selection

#### Remarks

Since multiple return values are seperated with a comma, any found within the text content will be entity escaped as &#44;.
To get or set the text content of a node use the text function, e.g. ``/root/node/text()``; this behaviour is always assumed within predicates.
For performance reasons `count()` and `last()` do not update with the creation of new nodes so you may need to alter the results accordingly.

Only the following functions are currently supported:

Function | Description | Example
--- | --- | ---
`text()` | Returns the text content. | `version := xpath(feed, `"/rss/@version/text()"`)`
`remove()` | Removes the entire selection. | `new := xpath(feed, `"/rss/channel/item[1]/remove()"`)`
`position()` | Gives the position of the currently selected object. | `top := xpath(feed, `"/rss/channel/item[position()<=3]"`)`
`last()` | Returns the last found object. | `oldest := xpath(feed, `"/rss/channel/item/last()/pubDate"`)`
`count()` | Returns the total number of selected elements. | `entries := xpath(feed, `"/rss/channel/item/count()"`)`

#### Examples

    #Include xpath.ahk ; include functions (only required if it is not in your standard library)

    ; parsing documents:
    xml := xpath_load("books.xml") ; load an XML document
    titles := xpath(xml, "/bookstore/books[price>35]/title/text()") ; get book titles with a cost greater than 35

    ; combining functions and using variables:
    firstShow := xpath(xml := xpath_load("listings.xml"), "/tv/programme[@starts>=" . A_Now . "]/title[1]/text()")

    x = <root><element var="test"/></root>
    xpath_load(x) ; XML content can be loaded in-place directly
    xpath(x, "element/text()", "new content")
    MsgBox, % xpath_save(x) ; show the new source without having to save it

    ; creating documents:
    xpath(feed, "/rss[+1]/@version", "2.0") ; create 'rss' node with attribute 'version'
    xpath(feed, "/rss/channel[+1]/title[+1]", "second") ; rss > channel > title
    xpath(feed, "/rss/channel/title[-1]", "first") ; '-1' puts this node before the last
    xpath_save("\Inetpub\wwwroot\test.xml", feed) ; write XML

## xpath_save

Saves an XML document to file or returns the source.

### xpath_save(doc, src)

#### Parameters

Returns | False if there was an error in saving the document, true otherwise. If the src parameter is left blank the source code of the document is returned instead.
doc | an xml object returned by xpath_load()
src | (optional)a path to a file where the XML document should be saved; if the file already exists it will be replaced

## xpath_load

Loads an XML document.

### xpath_load(doc, src)

#### Parameters

Returns | False if there was an error in loading the document, true otherwise.
doc | a reference to the loaded XML file as a variable, to be used in other functions
src | (optional)the document to load, this can be a file name or a string, if omitted the first paramter is used as the source

Version 3.12; Copyright © Titan - GNU General Public License 3.0 or higher