Options

Nearly every step has options. They are realised via attributes of the respective element and they influence the behaviour of the step.

p:option

<p:option
  name = QName
  required? = boolean
  select = XPathExpression/>

An option always has a name. If the Boolean flag “required“ is set to “true“, the indication is obligatory (otherwise a Static Error will be generated). Some options have so-called “default“ values, which means predefined specifications. These are defined by an appropriate XPath expression.

Example

In the following example an option is shown by the means of the Atomic Step <p:delete>.

<p:declare-step type="p:delete">
   <p:input port="source"/>
   <p:output port="result"/>
   <p:option name="match" required="true"/> <!-- XSLTMatchPattern -->
</p:declare-step>

<p:delete> requires an option with the name “match“. This can be seen because the Boolean flag "required" is set to “true“.

<?xml version="1.0" encoding="UTF-8"?>
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" xmlns:c="http://www.w3.org/ns/xproc-step" version="1.0">
  <p:input port="source">
    <p:document href="FilmCollection.xml"/>
  </p:input>
  <p:output port="result"/>
  <p:delete match="/FilmCollection/Film/Cast"/>
</p:declare-step>

If no value is indicated in the “match“ attribute, this woluld lead to a static error.

p:with-option

<p:with-option
  name = QName
  select = XPathExpression>
   ((p:empty |
   p:pipe |
   p:document |
   p:inline |
   p:data)? &
  p:namespaces*)
</p:with-option>

With the help of <p:with-option> options can be assigned within a step. The desired option is assigned to the “name“ attribute and the corresponding value is assigned to “select“. Since a XPath expression is required in this example, a pipeline may become increasingly dynamic.

Example

In the following example the <p:filter> step is operated by <p:with-option>.

<?xml version="1.0" encoding="UTF-8"?>
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" xmlns:c="http://www.w3.org/ns/xproc-step" version="1.0">
  <p:input port="source">
    <p:document href="FilmCollection.xml"/>
  </p:input>
  <p:output port="result" sequence="true"/>
  <p:filter>
     <p:with-option name="select" select="'/FilmCollection/Film/Title'">
  </p:with-option>
  </p:filter>
</p:declare-step>

In order to make sure that the XPath expression will not be resolved in the "select" attribute, because <p:filter> itself expects a XPath expression, in this example the expression is masked by appropriate ‘ ‘ characters. So, the XProc processor is being informed that it must not treat the entered value as XPath expression, but only as character string.

<< back

next >>