p:unarchive

[mkraetke]

p:unarchive is a step to extract primarily zip archives.

The option href is considered mandatory and specifies an URI or path to the zip file.

The file option, if specified, must be the path to a file in the archive. If this option is set, only the file is extracted.

The option list-only is not required and expects the values true and false (default). If this option is set to true, the result output is empty (e.g. no files are extracted) and the file-list output port provides just an XML list of the files in the archive.

The option parameters expects a map with additional implementation-defined paramters, e.g. for passing a password to unencrypt an archive.

In contrast to pxp:unzip, p:unarchive should allow to extract an archive at once. In this sense, the result output port should provide a sequence of documents.

Zip should be specified as default format. The support of other compression formats is not mandatory, but the XProc processor might implement these. However, the use of another compression format should be stated with the format option.

The file-list port provides always an XML document which specifies the contents of the Zip file.

The report port gives either no result or a c:errors document.

<p:unarchive>
  <p:output port="result"/>         <!-- zip with c:document-properties -->
  <p:output port="report"/>         <!-- c:errors -->
  <p:output port="file-list"/>      <!-- c:errors -->
  <p:option name="href"/>           <!-- anyURI -->
  <p:option name="file"/>           <!-- path -->
  <p:option name="format" select="'zip'"/><!-- other formats are implementation-defined -->
  <p:option name="parameters"/>     <!-- map(xs:string, xs:string) -->
</p:unarchive>

[xml-project]

One question and one remark:
Question: What is the "file" option for?
Remark: I do not like the option "href". It was necessary in XProc 1.0 but since we have binary documents in XProc 3.0 I think the archive should be on an input port. Doing it this way, one could e.g. connect the output of a p:http-request to p:unarchive.
If you have an URI for the zip, you can still say p:with-input href="my-uri".

[mkraetke]

Agree, let's replace href with an appropriate input port.

[mkraetke]

file is needed to select a specific file from the zip to be unzipped. Use case: sometimes you just want to extract a small XML metadata file from a large EPUB file.

[xml-project]

May be we should replace the name "file" with "extract-only" and apply the new globbing feature also inside zips.

[xatapult]

There is now a skeleton unarchive step with PR #55. This needs to be discussed and enhanced.

[ndw]

Overtaken by events; now part of the steps spec.