XProc 3.0: Exec

Editor's Draft

This Version:
https://xproc.github.io/3.0-specification/revert-362-fix-361/head/exec/
Latest Version:
http://spec.xproc.org/master/head/exec/
Editors:
Achim Berndzen
Gerrit Imsieke
Erik Siegel
Norman Walsh
Repository:
This specification on GitHub
Report an issue
Changes:
Commits for this specification

This document is also available in these non-normative formats: XML.


Abstract

This specification describes the p:validate-with-relax-ng step for XProc 3.0: An XML Pipeline Language.

Status of this Document

This document is an editor's draft that has no official standing.

This section describes the status of this document at the time of its publication. Other documents may supersede this document.

This document is derived from XProc: An XML Pipeline Language published by the W3C.


1 Introduction

This specification describes the p:exec XProc step. A machine-readable description of these steps may be found in steps.xpl.

Familarity with the general nature of [XProc 3.0] steps is assumed; for background details, see [XProc 3.0 Steps].

2 p:exec

The p:exec step runs an external command passing the input that arrives on its source port as standard input, reading result from standard output, and errors from standard error.

<p:declare-step type="p:exec">
     <p:input port="source" primary="true" sequence="true" content-types="*/*"/>
     <p:output port="result" primary="true" content-types="*/*"/>
     <p:output port="errors"/>
     <p:output port="exit-status"/>
     <p:option name="command" required="true" as="xs:string"/>     
     <p:option name="args" select="''" as="xs:string"/>            
     <p:option name="cwd" as="xs:string"/>                         
     <p:option name="source-is-xml" select="true()" as="xs:boolean"/>
     <p:option name="result-is-xml" select="true()" as="xs:boolean"/>
     <p:option name="wrap-result-lines" select="false()" as="xs:boolean"/>
     <p:option name="errors-is-xml" select="false()" as="xs:boolean"/>
     <p:option name="wrap-error-lines" select="false()" as="xs:boolean"/>
     <p:option name="path-separator" as="xs:string"/>              
     <p:option name="failure-threshold" as="xs:integer"/>          
     <p:option name="arg-separator" select="' '" as="xs:string"/>  
     <p:option name="serialization" as="map(xs:string,xs:anyAtomicValue)"/>
</p:declare-step>

The values of the command, args, cwd, path-separator, and arg-separator options must be strings.

The values of the source-is-xml, result-is-xml, errors-is-xml, and fix-slashes options must be boolean.

The p:exec step executes the command passed on command with the arguments passed on args. The processor does not interpolate the values of the command or args (for example, expanding references to environment variables). It is a dynamic error (err:XC0033) if the command cannot be run.

If cwd is specified, then the current working directory is changed to the value of that option before execution begins. It is a dynamic error (err:XC0034) if the current working directory cannot be changed to the value of the cwd option. If cwd is not specified, the current working directory is implementation-defined.

If the path-separator option is specified, every occurrence of the character identified as the path-separator character that occurs in the command, args, or cwd will be replaced by the platform-specific path separator character. It is a dynamic error (err:XC0063) if the path-separator option is specified and is not exactly one character long.

The value of the args option is a string. In order to support passing more than one argument to a command, the args string is broken into a sequence of values. The arg-separator option specifies the character that is used to separate values; by default it is a single space It is a dynamic error (err:XC0066) if the arg-separator option is specified and is not exactly one character long.

The following examples of p:exec are equivalent. The first uses the default arg-separator:

<p:exec command="someCommand" args="arg1 arg2 arg3"/>

The second specifies an alternate separator:

<p:exec command="someCommand" args="arg1,arg2,arg3"
	arg-separator=","/>

If one of the arguments contains a space (e.g., a filename that contains a space), then you must specify an alternate separator.

The source port is declared to accept a sequence so that it can be empty. If no document appears on the source port, then the command receives nothing on standard input. If a document does arrive on the source port, it will be passed to the command as its standard input. It is a dynamic error (err:XD0006) if more than one document appears on the source port of the p:exec step. If source-is-xml is true, the value of the serialization option is used to convert the input into serialized XML which is passed to the command, otherwise the XPath string-value of the document is passed. Serialization is described in [XProc 3.0].

The standard output of the command is read and returned on result; the standard error output is read and returned on errors. In order to assure that the result will be an XML document, each of the results will be wrapped in a c:result element.

If result-is-xml is true, the standard output of the program is assumed to be XML and will be parsed as a single document. If it is false, the output is assumed not to be XML and will be returned as escaped text.

If wrap-result-lines is true, a c:line element will be wrapped around each line of output.

<c:line>
    string
</c:line>

It is a dynamic error (err:XC0035) to specify both result-is-xml and wrap-result-lines.

The same rules apply to the standard error output of the program, with the errors-is-xml and wrap-error-lines options, respectively.

If either of the results are XML, they must be parsed with namespaces enabled and validation turned off, just like p:document.

The exit-status port always returns a single c:result element which contains the system exit status that the process returned. The specific exit status values returned by a process invoked with p:exec are implementation-dependent.

If a failure-threshold value is supplied, and the exit status is greater than that threshold, then the p:exec step must fail. It is a dynamic error (err:XC0064) if the exit code from the command is greater than the specified failure-threshold value. This failure, like any step failure, can be captured with a p:try.

2.1 Document properties

No document properties are preserved.

3 Step Errors

This step can raise dynamic errors.

[Definition: A dynamic error is one which occurs while a pipeline is being evaluated.] Examples of dynamic errors include references to URIs that cannot be resolved, steps which fail, and pipelines that exhaust the capacity of an implementation (such as memory or disk space). For a more complete discussion of dynamic errors, see Dynamic Errors in XProc 3.0: An XML Pipeline Language.

If a step fails due to a dynamic error, failure propagates upwards until either a p:try is encountered or the entire pipeline fails. In other words, outside of a p:try, step failure causes the entire pipeline to fail.

The following errors can be raised by this step:

err:XC0033

It is a dynamic error if the command cannot be run.

See: p:exec

err:XC0034

It is a dynamic error if the current working directory cannot be changed to the value of the cwd option.

See: p:exec

err:XC0035

It is a dynamic error to specify both result-is-xml and wrap-result-lines.

See: p:exec

err:XC0063

It is a dynamic error if the path-separator option is specified and is not exactly one character long.

See: p:exec

err:XC0064

It is a dynamic error if the exit code from the command is greater than the specified failure-threshold value.

See: p:exec

err:XC0066

It is a dynamic error if the arg-separator option is specified and is not exactly one character long.

See: p:exec

A Conformance

Conformant processors must implement all of the features described in this specification except those that are explicitly identified as optional.

Some aspects of processor behavior are not completely specified; those features are either implementation-dependent or implementation-defined.

[Definition: An implementation-dependent feature is one where the implementation has discretion in how it is performed. Implementations are not required to document or explain how implementation-dependent features are performed.]

[Definition: An implementation-defined feature is one where the implementation has discretion in how it is performed. Conformant implementations must document how implementation-defined features are performed.]

A.1 Implementation-defined features

The following features are implementation-defined:

  1. If cwd is not specified, the current working directory is implementation-defined. See Section 2, “p:exec”.

A.2 Implementation-dependent features

The following features are implementation-dependent:

  1. The specific exit status values returned by a process invoked with p:exec are implementation-dependent. See Section 2, “p:exec”.

B References

[XProc 3.0] XProc 3.0: An XML Pipeline Language. Achim Berndzen, Gerrit Imsieke, Erik Siegel and Norman Walsh, editors.

[XProc 3.0 Steps] XProc 3.0 Steps: An Introduction. Achim Berndzen, Gerrit Imsieke, Erik Siegel and Norman Walsh, editors.

C Glossary

dynamic error

A dynamic error is one which occurs while a pipeline is being evaluated.

implementation-defined

An implementation-defined feature is one where the implementation has discretion in how it is performed. Conformant implementations must document how implementation-defined features are performed.

implementation-dependent

An implementation-dependent feature is one where the implementation has discretion in how it is performed. Implementations are not required to document or explain how implementation-dependent features are performed.