XProc 3.0: operating system steps
Editor's Draft
- This Version:
- https://ndw.github.io/steps/master/head/os/
- Latest Version:
- http://spec.xproc.org/master/head/os/
- Editors:
- Norman Walsh
- Achim Berndzen
- Gerrit Imsieke
- Erik Siegel
- Repository:
- This specification on GitHub
- Report an issue
- Changes:
- Commits for this specification
This document is also available in these non-normative formats: XML.
Copyright © 2018 @@FIXME:
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 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.
Table of Contents
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-step
type
="
p:os-info
"
>
<p:output
port
="
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 should
include the following properties:
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. On systems which have no concept of a working directory the value of the attribute will be empty.
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"
.
FIXME: the c:result
element may contain zero or more
c:environment
elements that identify the environment variables
available.
The exact set of properties returned is implementation-dependent.
Document properties
No document properties are preserved.
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 errors
from standard error.
<p:declare-step
type
="
p:os-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: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 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:os-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:os-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: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
.
3.1 Document properties
No document properties are preserved.
4 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: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:XC0035
It is a dynamic error to specify both result-is-xml and wrap-result-lines.
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
err:XC0066
It is a dynamic error if the arg-separator option is specified and is not exactly one character long.
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:
- 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:
- 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.