Name
p:archive — The standard p:archive step.
Synopsis
The p:archive step outputs on its result port an archive (usually
binary) document, for instance a ZIP file. A specification of the contents of the archive may be
specified in a manifest XML document on the manifest port. The step produces a
report on the report port, which contains the manifest, amended with additional
information about the archiving.
| Input port | Primary | Sequence | Content types | Default binding |
|---|---|---|---|---|
| source | ✔ | ✔ | any | |
| manifest | ✔ | xml | p:empty | |
| archive | ✔ | any | p:empty |
| Output port | Primary | Sequence | Content types | Default binding |
|---|---|---|---|---|
| result | ✔ | any | ||
| report | application/xml |
| Option name | Type | Default value |
|---|---|---|
| format | xs:QName | 'zip' |
| parameters | map(xs:QName, item()*)? | () |
| relative-to | xs:anyURI? | () |
Declaration
1 |<p:declare-step xmlns:p="http://www.w3.org/ns/xproc">
| <p:input port="source"
| primary="true"
| content-types="any"
5 | sequence="true"/>
| <p:input port="manifest" content-types="xml" sequence="true">
| <p:empty/>
| </p:input>
| <p:input port="archive" content-types="any" sequence="true">
10 | <p:empty/>
| </p:input>
| <p:output port="result"
| primary="true"
| content-types="any"
15 | sequence="false"/>
| <p:output port="report" content-types="application/xml" sequence="false"/>
| <p:option name="format" as="xs:QName" select="'zip'"/>
| <p:option name="relative-to" as="xs:anyURI?"/>
| <p:option name="parameters" as="map(xs:QName, item()*)?"/>
20 |</p:declare-step>Errors
| Code | Description |
|---|---|
err:XC0079 | It is a dynamic error (err:XC0079) if the map
parameters contains an entry whose key is defined by the
implementation and whose value is not valid for that key. |
err:XC0080 | It is a dynamic error (err:XC0080) if the number of
documents on the archive does not match the expected number of archive input
documents for the given format and command. |
err:XC0081 | It is a dynamic error (err:XC0081) if the format of the
archive does not match the format as specified in the format
option. |
err:XC0084 | It is a
dynamic error (err:XC0084) if two or more documents appear on the p:archive
step's source port that have the same base URI or if any document that
appears on the source port has no base URI. |
err:XC0085 | It is a dynamic error (err:XC0085) if the format of the archive
cannot be understood, determined and/or processed. |
err:XC0100 | It is a dynamic error (err:XC0100) if the document on port
manifest does not conform to the given schema. |
err:XC0112 | It is a dynamic error (err:XC0112) if more than one
document appears on the port manifest. |
err:XD0011 | It is a dynamic error (err:XD0011)
if the resource referenced by the href option does not exist, cannot be
accessed or is not a file. |
err:XD0064 | It is a dynamic
error (err:XD0064) if the base URI is not both absolute and valid according to
RFC 3986. |
Implementation defined features
- The list of formats
supported by the
p:archivestep is implementation-defined. - The list of archive formats that can be modified by
p:archiveis implementation-defined. - The semantics of any additional attributes, elements and their values are implementation-defined.
- It is implementation-defined what other formats are supported.
- It is implementation-defined what other formats are supported.
- It is implementation-defined how the step determines the archive's format.
- The
c:archiveroot element may contain additional implementation-defined attributes. - The default compression method is implementation-defined.
- It is implementation-defined what other compression methods are supported.
- The default compression method is implementation-defined.
- It is implementation-defined what compression levels are supported.
- The
c:entryelements may contain additional implementation-defined attributes. - The
p:archivestep may support additional, implementation-defined commands for ZIP files. - The actual parameter names supported by
p:archivefor a particular format are implementation-defined.
Implementation dependent features
- If the format imposes constraints on the archive comment (character set or length, for example), how the processor coerces the attribute value to satisfy those constraints is implementation-dependent.
Description
The p:archive step is a
standard XProc 3.0 step.
It is also described on XProcRef.org.
Supported formats
The following formats are supported using the Apache Commons Compress™ library version 1.28.0.
| Archive format | Read? | Write? | format option | Content type | Common file extensions |
|---|---|---|---|---|---|
| 7z | ✔ | ✔ | sevenZ | application/x-7z-compressed | .7z |
| Ar | ✔ | ✔ | ar | application/x-archive | .a,
.lib,
.ar |
| Arj | ✔ | arj | application/x-arj | .arj | |
| Cpio | ✔ | ✔ | cpio | application/x-cpio | .cpio |
| Jar | ✔ | ✔ | jar | application/java-archive | .jar |
| Tar | ✔ | ✔ | tar | application/x-tar | .tar |
| Zip | ✔ | ✔ | zip | application/zip | .zip |
Some of these content types are non-standard or only de-facto standards.
If no format is provided, the format is
selected from the (first) archive on the archive port, if
there is one, or defaults to zip. The format of an
archive file is determined solely from its content type; no attempt is
made to inspect the content of the archive to determine its format.
Creating archives
If multiple documents are provided on the archive, they are merged together.
When merging archives, the cx:merge-duplicates parameter sets the
merging policy:
errorIt is an error if the same name occurs in two or more archives (unless that name is also being replaced by the step). This is the default value.
keep-firstThe first document encountered is kept, the rest are discarded.
keep-lastThe last document encountered is kept, the rest are discarded.
Updating archives
When updating archives, at most one archive may appear on the archive port. If no archives appear, a new archive will be created using only the files provided by the step.
Freshening archives
When freshening archives, at most one archive may appear on the archive port. If no archives appear, a new archive will be created using only the files provided by the step.
Deleting from archives
When deleting archives, exactly one archive must appear on the archive port.