Name
cx:find — Searches for matching files.
Synopsis
This step is the p:directory-list step with the added ability to
filter files from the list based on whether their content matches an expression.
| Output port | Primary | Sequence | Content types |
|---|---|---|---|
| result | ✔ | application/xml |
| Option name | Type | Default value | Required |
|---|---|---|---|
| path | xs:anyURI | ✔ | |
| detailed | xs:boolean | false() | |
| exclude-filter | xs:string* | () | |
| grep | xs:string* | () | |
| include-filter | xs:string* | () | |
| jsonpath | xs:string* | () | |
| max-depth | xs:string? | 'unbounded' | |
| override-content-types | array(array(xs:string))? | () | |
| xpath | xs:string* | () |
<p:import href="https://xmlcalabash.com/ext/library/find.xpl"/>Declaration
1 |<p:declare-step xmlns:p="http://www.w3.org/ns/xproc">
| <p:output port="result" content-types="application/xml"/>
| <p:option name="path" required="true" as="xs:anyURI"/>
| <p:option name="detailed" as="xs:boolean" select="false()"/>
5 | <p:option name="max-depth" as="xs:string?" select="'unbounded'"/>
| <p:option name="include-filter" as="xs:string*"/>
| <p:option name="exclude-filter" as="xs:string*"/>
| <p:option name="override-content-types" as="array(array(xs:string))?"/>
| <p:option name="xpath" as="xs:string*"/>
10 | <p:option name="grep" as="xs:string*"/>
| <p:option name="jsonpath" as="xs:string*"/>
|</p:declare-step>Errors
| Code | Description |
|---|---|
cxerr:XC0039 | It is a dynamic error (cxerr:XC0039) if
any of the JSONPath expressions is not valid. |
cxerr:XC0040 | It is a dynamic error (cxerr:XC0040) if
any of the regular expressions is not valid. |
cxerr:XC0041 | It is a dynamic error (cxerr:XC0041) if
any of the XPath expressions is not valid. |
cxerr:XC0042 | It is a dynamic error (cxerr:XC0042) if more than
one query option is provided. |
Description
This step works just like p:directory-list except that it defaults to
an unbounded depth and the resulting
list of files is filtered through a grep, jsonpath,
or xpath query option. At most one query option can be provided.
It is a dynamic error (cxerr:XC0042) if more than
one query option is provided.
Grep queries
A grep query is a list of regular expressions. In a grep query, each file
is read line-by-line and each line is tested against each regular expression (using the standard
XPath function
matches($line, $expression)). The file remains
in the list if any expression is matched on any line.
It is a dynamic error (cxerr:XC0040) if
any of the regular expressions is not valid.
JSONPath queries
A jsonpath query is a list of JSONPath expressions. In a
JSONPath query, each file is read as a JSON document. If the file isn’t a valid
JSON document, it is removed from the list. If it is valid, it is tested against
each JSONPath expression. The file remains in the list if any expression returns
a non-null result.
It is a dynamic error (cxerr:XC0039) if
any of the JSONPath expressions is not valid.
XPath queries
An xpath query is a list of XPath expressions. In an
XPath query, each file is read as an XML document. If the file isn’t well-formed
XML, it is removed from the list. If it is XML, it is tested against
each XPath expression. The file remains in the list if any expression returns
an effective boolean value of true.
It is a dynamic error (cxerr:XC0041) if
any of the XPath expressions is not valid.