Extension Steps

Calabash implements a number of extension steps defined in a pipeline library at: http://xmlcalabash.com/extension/steps/library-1.0.xpl.

These steps are in the “Calabash extension namespace”, http://xmlcalabash.com/ns/extensions, identified by the prefix “cx” or the “MarkLogic extension namespace”, http://xmlcalabash.com/ns/extensions/marklogic, identified by the prefix “ml”.

cx:collection-manager

The cx:collection-manager step associates a set of documents with a collection URI.

<p:declare-step type="cx:collection-manager">
     <p:input port="source" sequence="true"/>
     <p:output port="result" sequence="true" primary="false"/>
     <p:option name="href" required="true"/>                       
</p:declare-step>

If at least one document appears on the source port, the sequence of documents that appears on that port is associated with the specified collection URI. It may subsequently be accessed in an XSLT 2.0 or XQuery step using the XPath 2.0 collection function. The source documents are copied to the result port.

If an empty sequence of documents appears on the source port, the previously stored collection associated with the specified collation URI is retrieved and that set of documents appears on the result port. If no collection is associated with the URI, the empty sequence is returned.

cx:delta-xml

The cx:delta-xml step invokes the Delta XML XML “diff” library.

<p:declare-step type="cx:delta-xml">
     <p:input port="source"/>
     <p:input port="alternate"/>
     <p:input port="dxp"/>
     <p:output port="result"/>
</p:declare-step>

To use this step, you must have a valid license for the Delta XML product and the Delta XML jar files on your class path.

cx:eval

The cx:eval step takes a pipeline document as input and runs it as an XProc pipeline.

<p:declare-step type="cx:eval">
     <p:input port="source" sequence="true" primary="true"/>
     <p:input port="pipeline"/>
     <p:input port="parameters" kind="parameter"/>
     <p:input port="options" sequence="true"/>
     <p:output port="result" sequence="true"/>
     <p:option name="detailed" select="'false'"/>                  
     <p:option name="step"/>                                       
</p:declare-step>

In the simplest case, where the specified pipeline has a single input and a single output, the document(s) on the source port are passed to the pipeline, processed, and the results are passed back on the result port.

If the pipeline specified has multiple inputs or outputs, then the inputs and outputs have to be “multiplexed” on the single port. If this is the case, you must specify that the detailed option is “true”, and encode the input using cx:document. Each input must be wrapped in cx:document with a port attribute that identifies the port to which that document is to be sent. Each output will be wrapped in a cx:document element identifying the port from which it came.

If the pipeline has options, they are passed to the options port. Each options document must have cx:options as its document element and consist entirely of cx:option elements with name and value attributes that specify options and their values.

If the pipeline is a p:library, then the step to evaluate may be specified using the step option. If the pipeline is a library and no step option is specified, the first step in the library will be selected.

cx:message

The cx:message writes a message to the console.

<p:declare-step type="cx:message">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="message" required="true"/>                    
</p:declare-step>

This step is mostly for debugging. It performs the identity step with the side-effect of writing a message to the console.

cx:nvdl

A step for performing NVDL (Namespace-based Validation Dispatching Language) validation over mixed-namespace documents.

<p:declare-step type="pxp:nvdl">
     <p:input port="source" primary="true"/>
     <p:input port="nvdl"/>
     <p:input port="schemas" sequence="true"/>
     <p:output port="result"/>
     <p:option name="assert-valid" select="'true'"/>               
</p:declare-step>

The cx:nvdl step is defined at http://exproc.org/.

The names cx:nvdl and pxp:nvdl are synonymous. The latter is preferred.

cx:unzip

A step for extracting information out of ZIP archives.

<p:declare-step type="pxp:unzip">
     <p:output port="result"/>
     <p:option name="href" required="true"/>                       
     <p:option name="file"/>                                       
     <p:option name="content-type"/>                               
</p:declare-step>

The cx:unzip step is defined at http://exproc.org/.

The names cx:unzip and pxp:unzip are synonymous. The latter is preferred.

ml:adhoc-query

The ml:adhoc-query step performs an adhoc query on a Mark Logic Server.

<p:declare-step type="ml:adhoc-query">
     <p:input port="source" sequence="true" primary="true"/>
     <p:input port="parameters" kind="parameter"/>
     <p:output port="result" sequence="true"/>
     <p:option name="host"/>                                       
     <p:option name="port"/>                                       
     <p:option name="user"/>                                       
     <p:option name="password"/>                                   
     <p:option name="content-base"/>                               
     <p:option name="wrapper"/>                                    
</p:declare-step>

To use this step you must have a Mark Logic Server and the Java XCC libraries.

ml:insert-document

The ml:insert-document step inserts a document into a Mark Logic Server.

<p:declare-step type="ml:insert-document">
     <p:input port="source"/>
     <p:output port="result" primary="false"/>
     <p:option name="host"/>                                       
     <p:option name="port"/>                                       
     <p:option name="user"/>                                       
     <p:option name="password"/>                                   
     <p:option name="content-base"/>                               
     <p:option name="uri" required="true"/>                        
     <p:option name="buffer-size"/>                                
     <p:option name="collections"/>                                
     <p:option name="format"/>                                     
     <p:option name="language"/>                                   
     <p:option name="locale"/>                                     
</p:declare-step>

To use this step you must have a Mark Logic Server and the Java XCC libraries.

ml:invoke-module

The ml:invoke-module step invokes a module on a Mark Logic Server, as its name implies.

<p:declare-step type="ml:invoke-module">
     <p:input port="parameters" kind="parameter"/>
     <p:output port="result" sequence="true"/>
     <p:option name="module" required="true"/>                     
     <p:option name="host"/>                                       
     <p:option name="port"/>                                       
     <p:option name="user"/>                                       
     <p:option name="password"/>                                   
     <p:option name="content-base"/>                               
     <p:option name="wrapper"/>                                    
</p:declare-step>

To use this step you must have a Mark Logic Server and the Java XCC libraries.

Because the results of a module invocation may not be a single, well formed XML document (for example, it could be a single atomic value), the results are wrapped in the specified wrapper element.