<?xml version="1.0"?>
<tool id="xpath" name="XPath" version="@WRAPPER_VERSION@.0">
  <description>compute xpath expressions on XML data</description>
  <macros>
    <import>macros.xml</import>
  </macros>
  <expand macro="requirements"/>
  <expand macro="stdio"/>
  <command><![CDATA[perl $__tool_directory__/xpath -q -e '$expression' $input > $output]]></command>
  <inputs>
    <param name="input" type="data" format="xml" label="Input XML data"/>
    <param name="expression" type="text" label="XPath Query">
      <sanitizer>
        <valid>
          <add value="&quot;"/>
          <add value="["/>
          <add value="]"/>
          <add value="@"/>
        </valid>
      </sanitizer>
    </param>
  </inputs>
  <outputs>
      <!-- TODO: sometimes there's text output (e.g. text() queries) -->
    <data format="xml" name="output" label="XPath expression on $input.name"/>
  </outputs>
  <tests>
    <test>
      <param name="input" value="test.xml"/>
      <param name="expression" value="//b[@attr=&quot;value&quot;]" />
      <output name="output" file="1.xml"/>
    </test>
    <test>
      <param name="input" value="test.xml"/>
      <param name="expression" value="//b[@attr]" />
      <output name="output" file="2.xml"/>
    </test>
    <test>
      <param name="input" value="test.xml"/>
      <param name="expression" value="//b/text()" />
      <output name="output" file="3.xml"/>
    </test>
  </tests>
  <help><![CDATA[
**What it does**

Query XML files with XPath expressions.

For an example input file::

    <root>
        <IdList>
            <Id>1234</Id>
            <Id>1235</Id>
            <Id>1236</Id>
            <Id>1237</Id>
        </IdList>
    </root>

One could query out the IDs specifically with a query like::

    //Id/text()

**XPath Expressions**

There are many helpful tutorials on the internet for XPath expressions.
`Wikipedia <https://en.wikipedia.org/wiki/XPath>`__ has a number of good
examples.

**Some More Examples**

For an XML document like the following::

    <root>
        <a>
            <b attr="value">1</b>
            <b attr="none">2</b>
            <b>3</b>
        </a>
        <c>
            <d>4</d>
            <e>5</e>
        </c>
    </root>

Here are some example queries and their outputs:

+--------------------+---------------------------------------------------+
| Query              | Result                                            |
+====================+===================================================+
| //b[@attr="value"] | <b attr="value">1</b>                             |
+--------------------+---------------------------------------------------+
| //b[@attr]         | <b attr="value">1</b><b attr="none">2</b>         |
+--------------------+---------------------------------------------------+
| //b                | <b attr="value">1</b><b attr="none">2</b><b>3</b> |
+--------------------+---------------------------------------------------+
| //b/text()         | 1\n2\n3                                           |
+--------------------+---------------------------------------------------+
| /root/*/*/text()   | 1\n2\n3\n4\n5                                     |
+--------------------+---------------------------------------------------+




@ATTRIBUTION@
]]></help>
  <citations>
  </citations>
</tool>