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 portPrimarySequenceContent types
result✔  application/xml 
Option nameTypeDefault valueRequired
pathxs:anyURI ✔ 
detailedxs:booleanfalse() 
exclude-filterxs:string*() 
grepxs:string*() 
include-filterxs:string*() 
jsonpathxs:string*() 
max-depthxs:string?'unbounded' 
override-content-typesarray(array(xs:string))?() 
xpathxs:string*() 
This is an extension step; to use it, your pipeline must include its declaration. For example, by including the extension library with an import at the top of your pipeline:
<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
CodeDescription
cxerr:XC0039It is a dynamic error (cxerr:XC0039) if any of the JSONPath expressions is not valid.
cxerr:XC0040It is a dynamic error (cxerr:XC0040) if any of the regular expressions is not valid.
cxerr:XC0041It is a dynamic error (cxerr:XC0041) if any of the XPath expressions is not valid.
cxerr:XC0042It 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.