XProc steps

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

p:exec

<p:declare-step type="p:exec">
   <p:input port="source" primary="true" sequence="true"/>
   <p:output port="result" primary="true"/>
   <p:output port="errors"/>
   <p:output port="exit-status"/>
   <p:option name="command" required="true"/> <!-- string -->
   <p:option name="args" select="''"/> <!-- string -->
   <p:option name="cwd"/> <!-- string -->
   <p:option name="source-is-xml" select="'true'"/> <!-- boolean -->
   <p:option name="result-is-xml" select="'true'"/> <!-- boolean -->
   <p:option name="wrap-result-lines" select="'false'"/> <!-- boolean -->
   <p:option name="errors-is-xml" select="'false'"/> <!-- boolean -->
   <p:option name="wrap-error-lines" select="'false'"/> <!-- boolean -->
   <p:option name="path-separator"/> <!-- string -->
   <p:option name="failure-threshold"/> <!-- integer -->
   <p:option name="arg-separator" select="' '"/> <!-- string -->
   <p:option name="byte-order-mark"/> <!-- boolean -->
   <p:option name="cdata-section-elements" select="''"/> <!-- ListOfQNames -->
   <p:option name="doctype-public"/> <!-- string -->
   <p:option name="doctype-system"/> <!-- anyURI -->
   <p:option name="encoding"/> <!-- string -->
   <p:option name="escape-uri-attributes" select="'false'"/> <!-- boolean -->
   <p:option name="include-content-type" select="'true'"/> <!-- boolean -->
   <p:option name="indent" select="'false'"/> <!-- boolean -->
   <p:option name="media-type"/> <!-- string -->
   <p:option name="method" select="'xml'"/> <!-- QName -->
   <p:option name="normalization-form" select="'none'"/> <!-- NormalizationForm -->
   <p:option name="omit-xml-declaration" select="'true'"/> <!-- boolean -->
   <p:option name="standalone" select="'omit'"/> <!-- "true" | "false" | "omit" -->
   <p:option name="undeclare-prefixes"/> <!-- boolean -->
   <p:option name="version" select="'1.0'"/> <!-- string -->
</p:declare-step>

With the help of the <p:exec> step, external commands/programmes can be executed on the command line of the respective operating system. The contents at the input port (“source“) are passed on to the respective call. The programme to be executed is defined by the “command“ option. The option expects a string which contains the command call.

Under the “args“ option, parameters can be indicated which may influence the behaviour of the programme to be called up. A classical parameter is for example “-h“ which usually outputs the help. Several parameters are indicated by a space character. This space character can also be freely defined under “arg-separator“. With the help of the “cwd“ (“Current Working Directory“) option, the user can indicate the path in the file system where the programme to be called up can be found. If the programme cannot be found, a dynamic error will be outputted. If this option is not used, the value is standardly the place in the file system where the programme to be executed is located.

The Boolean options “source-is-xml“ and “result-is-xml“ inform the processor whether the input information or output information are XML-based or not. If the options “wrap-result-lines“ or/and “wrap-error-lines“ are set to "true", all lines of the output information will be enclosed with a <c:line> element. If the “output-is-xml“ option is also set to “true“, a dynamic error will be outputted.

The “path-separator“ option indicates how the character for the separation of paths in the file system has to look like. If this character is used when indicating “command“, “args“ or “cwd“, it will be replaced by the path separation character attached to the respective operating system.

Further options are available which enable more detailed specifications regarding the nature of the data to be read in (e.g. under the “media-type“ option) and their processing guidelines (e.g. whether the output data shall be indented under “indent“).

Since this option is strongly case-based and irrelevant for the primary significance of the step, they are not discussed further in the following.

Furthermore, the step has three output ports. The primary “result“ output port outputs the result of the executed programme. In the “errors“ output port any errors that occur are listed, which means the outputs which are written on the command line on the standard error output. The “exit-status“ port always outputs an integer value which allows conclusions about the successful execution of the command. So, in the event of a success, the value <c:result>0</result> can be read and in the event of errors, <c:result>1</c:result>.

Example

In the following example the “cat“ Unix command shall be executed. It shall output the “FilmCollection.xml“ document.

<?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" name="testpipe">
   <p:input port="source">
      <p:document href="FilmCollection.xml"/>
   </p:input>
   <p:output port="result" sequence="true">
      <p:empty/>
   </p:output>
   <p:exec command="cat" result-is-xml="true" name="exec"/>
   <p:identity>
      <p:input port="source">
         <p:pipe port="errors" step="exec"/>
      </p:input>
    </p:identity>
    <p:store href="error.xml"/>
    <p:identity>
       <p:input port="source">
          <p:pipe port="exit-status" step="exec"/>
       </p:input>
    </p:identity>
    <p:store href="exit_status.xml"/>
    <p:identity>
       <p:input port="source">
          <p:pipe port="result" step="exec"/>
       </p:input>
    </p:identity>
    <p:store href="result.xml"/>
</p:declare-step>

Each of the three output ports is caught by a <p:identity> step and stored in a file via <p:store>. The result is as follows (excerpt):

<c:result>
 <FilmCollection>
    <Film>
       <Title>Star Wars: Episode IV - A New Hope</Title>
       <Year>1978</Year>
       <Genre>SciFi</Genre>
[...]

Since the process was successfully performed, no output occurs at the “errors“ port. Therefore, the created file “error.xml“ has no content. Accordingly, <c:result>0</c:result> is outputted in the “exit-status“ port (which corresponds to the content of “exit-status.xml“).