View Old View New View Both View Only Previous Next

XProc 3.0: operating system steps

Draft Community Group Report

Editor's Draft at (build 910)
Latest editor’s draft:
https://spec.xproc.org/master/head/os/
Editors:
Norman Walsh
Achim Berndzen
Gerrit Imsieke
Erik Siegel
Participate:
GitHub xproc/3.0-steps
Report an issue
Changes:
Diff against current “status quo” draft
Commits for this specification

This document is also available in these non-normative formats: XML and HTML with automatic change markup courtesy of DeltaXML.


Abstract

This specification describes the p:os-exec and p:os-info steps 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 specification was published by the XProc Next Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

If you wish to make comments regarding this document, please send them to xproc-dev@w3.org. (subscribe, archives).

1. Introduction

This specification describes the p:os-info and p:os-exec XProc steps. 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:os-info

The p:os-info step returns information about the operating system on which the processor is running.

<p:declare-steptype="p:os-info">
     <p:outputport="result"content-types="application/xml"primary="true"/>
</p:declare-step>

The step returns a c:result element with attributes describing properties of the system. It must include the following properties. The attribute can be an empty string if they do not apply to the runtime environment. For example cwd will be an empty string on systems which have no concept of a working directory the value of the attribute will be empty.

file-separator

The file separator; usually "/" on Unix, "\" on Windows.

path-separator

The path separator; usually ":" on Unix, ";" on Windows.

os-architecture

The operating system architecture, for example "i386".

os-name

The name of the operating system, for example "Mac OS X".

os-version

The version of the operating system, for example "10.5.6".

cwd

The current working directory.

user-name

The login name of the effective user, for example "ndw".

user-home

The home directory of the effective user, for example "/home/ndw".

The c:result element can contain zero or more c:environment elements that identify the environment variables available. These elements have a mandatory name and value attribute, reflecting name and value of the environment variable. Implementations should include all available operating system environment variables.

The exact set of properties returned is implementation-defined. Additional attributes must be in a namespace.

Document properties

The resulting document has no properties apart from content-type. In particular, it has no base-uri.

3. p:os-exec

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

<p:declare-steptype="p:os-exec">
     <p:inputport="source"sequence="true"content-types="any"/>
     <p:outputport="result"primary="true"sequence="true"content-types="any"/>
     <p:outputport="error"sequence="true"content-types="any"/>
     <p:outputport="exit-status"content-types="application/xml"/>
     <p:optionname="command"required="true"as="xs:string"/>     
     <p:optionname="args"select="()"as="xs:string*"/>           
     <p:optionname="cwd"as="xs:string?"/>                        
     <p:optionname="result-content-type"select="'text/plain'"as="xs:string"/>
     <p:optionname="error-content-type"select="'text/plain'"as="xs:string"/>
     <p:optionname="path-separator"as="xs:string?"/>             
     <p:optionname="failure-threshold"as="xs:integer?"/>         
     <p:optionname="serialization"as="map(xs:QName,item()*)?"/>  
</p:declare-step>

The p:os-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 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:XC0032) if more than one document appears on the source port of the p:os-exec step. The serialization option is used to control the serialization of the document before passing it to the standard input. If a document has a “serialization” document property, the effective value of the serialization options is the union of the two maps, where the entries in the “serialization” document property take precedence. Serialization is described in [XProc 3.0].

If there is content on standard output, it is read and processed as described in p:load with result-content-type taken as value for p:load's content-type option. The created document is returned on result. Otherwise result will be empty.

If there is content on standard error, it is read and processed as described in p:load with error-content-type taken as value for p:load's content-type option. The created document is returned on error. Otherwise error will be empty.

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:os-exec are implementation-dependent.

If a failure-threshold value is supplied, and the exit status is greater than that threshold, then the p:os-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.

Document properties

No document properties are preserved.

4. Step Errors

These steps 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 these steps:

err:XC0032

It is a dynamic error if more than one document appears on the source port of the p:os-exec step.

See: p:os-exec

err:XC0033

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

See: p:os-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:os-exec

err:XC0063

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

See: p:os-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:os-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. The exact set of properties returned is implementation-defined. See Section 2, “p:os-info”.
  2. If cwd is not specified, the current working directory is implementation-defined. See Section 3, “p:os-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:os-exec are implementation-dependent. See Section 3, “p:os-exec”.

B. References

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

[XProc 3.0 Steps] XProc 3.0 Steps: An Introduction. Norman Walsh, Achim Berndzen, Gerrit Imsieke and Erik Siegel, 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.

D. Ancillary files

This specification includes by reference a number of ancillary files.

steps.xpl

An XProc step library for the declared steps.