Skip to content
Permalink
Browse files

Merge pull request #212 from eriksiegel/Issue54

Moved p:directory-list to file steps
  • Loading branch information...
eriksiegel committed Sep 11, 2019
2 parents 72734e3 + 7321511 commit 4371d1f47f560a2baa2af86e57b2f02f5f46fcfb
@@ -62,7 +62,204 @@ steps is assumed; for background details, see
<biblioref linkend="xproc30-steps"/>.</para>
</section>

<section xml:id="c.file-copy">
<section xml:id="c.directory-list">
<title>p:directory-list</title>

<para>The <code>p:directory-list</code> step produces a list of the contents
of a specified directory.</para>

<p:declare-step type="p:directory-list">
<p:output port="result" content-type="application/xml"/>
<p:option name="path" required="true" as="xs:anyURI"/>
<p:option name="detailed" as="xs:boolean" select="false()"/>
<p:option name="max-depth" as="xs:string?" select="'1'"/>
<p:option name="include-filter" as="xs:string*"/>
<p:option name="exclude-filter" as="xs:string*"/>
</p:declare-step>

<para><impl>Conformant processors <rfc2119>must</rfc2119> support directory paths whose
scheme is <code>file</code>. It is
<glossterm>implementation-defined</glossterm> what other schemes are
supported by <tag>p:directory-list</tag>, and what the interpretation
of 'directory', 'file' and 'contents' is for those schemes.</impl>
<error code="C0102">It is a <glossterm>dynamic error</glossterm> if an
implementation does not support directory listing for a specified scheme.</error>
</para>

<para>If <option>path</option> is relative, it is made absolute against the
base URI of the element on which it is specified
(<tag>p:with-option</tag> or <tag>p:directory-list</tag> in the case of a
syntactic shortcut value). <error code="C0017">It is a
<glossterm>dynamic error</glossterm> if the absolute path does not
identify a directory.</error> <error code="C0012">It is a
<glossterm>dynamic error</glossterm> if the contents of the directory
path are not available to the step due to access restrictions in the
environment in which the pipeline is run.</error></para>

<para>If the <option>detailed</option> option is true, the pipeline
author is requesting additional information about the matching entries,
see <xref linkend="dir-list-details"/>.</para>

<para>The <option>max-depth</option> option may contain either the string “<literal>unbounded</literal>” or a string
that may be cast to a non-negative integer. An integer value of <literal>0</literal> means that only information
about the directory that is given in the <option>path</option> option is returned. A <option>max-depth</option> of
<literal>1</literal>, which is the default, will effect that also information about the top-level directory’s
immediate children will be included. For larger values of <option>max-depth</option>, also the content of
directories will be considered recursively up to the maximum depth, and it will be included as children of the
corresponding <tag>c:directory</tag> elements.</para>

<para>If present, the value of the <option>include-filter</option> or
<option>exclude-filter</option> option <rfc2119>must</rfc2119> be a sequence of strings, each
one representing a regular expressions as specified in <biblioref linkend="xpath31-functions"/>,
section 7.61 “<literal>Regular Expression Syntax</literal>”.</para>

<para>The regular expressions will be matched against an item’s file system path relative to the top-level path that was
given in the <option>path</option> option. If the item is a directory, a trailing slash will be appended.</para>
<para>Examples: A file <literal>file.txt</literal> in the directory specified by <option>path</option> will remain
<literal>file.txt</literal>, a relative path <literal>dir1/file.txt</literal> will remain
<literal>dir1/file.txt</literal>, while a relative path <literal>dir1/dir2</literal> will become
<literal>dir1/dir2/</literal> if <literal>dir2</literal> is a directory.</para>
<para>Regular expressions that match <literal>a/a/b/file.txt</literal> are, for example,
<literal>^/(\w+/){2,3}.+\.txt$</literal>, <literal>a/a/b/</literal>, or <literal>/file\.[^/]+$</literal>.</para>

<para>If any <option>include-filter</option> pattern matches the slash-augmented relative path, the entry is included in the output.
If a directory’s path matches the inclusion regex, the directory’s content will not automatically be included, too.
They need to match, the regular expression, too. So the filter regex <literal>^dir/</literal> will match the directory
content but <literal>^dir/$</literal> won’t, and as a consequence the directory’s content will not be included in the result.</para>
<para>If a relative path is matched by an include filter,
all its ancestor directories starting from the initial directory (but not their content if not included explicitly)
will be included, too.</para>
<example xml:id="ex.c.directory-list">
<title>Sample Directory List Output for a Single File</title>
<para>For a file <literal>a/a/b/file.txt</literal> below the initial directory
<literal>/home/jane</literal>, this output will be produced, omitting content that might be present in the
intermediate directories:</para>
<literallayout>&lt;c:directory xml:base="file:///home/jane/" name="jane">
&lt;c:directory xml:base="a/" name="a">
&lt;c:directory xml:base="a/" name="a">
&lt;c:directory xml:base="b/" name="b">
&lt;c:file xml:base="file.txt" name="file.txt"/>
&lt;/c:directory>
&lt;/c:directory>
&lt;/c:directory>
&lt;/c:directory></literallayout>
</example>
<para>If the <option>exclude-filter</option> pattern matches the slash-augmented relative path, the entry (and all of
its content in case of a directory) is excluded in the output.</para>
<para>If both options are
provided, the include filter is processed first, then the exclude
filter. As a result, an item is included if it matches (at least) one
of the <option>include-filter</option> values and none of the
<option>exclude-filter</option> values.</para>
<para>If no <option>include-filter</option> is given, that is, if <option>include-filter</option> is an empty
sequence, any item will be included in the result (unless it is excluded by <option>exclude-filter</option>).</para>

<note>
<para>There is no way to specify a list of values using attribute value
templates. If the option shortcut syntax is used to provide the
<option>include-filter</option> or <option>exclude-filter</option> option,
it will consist of a single regular expression. To specify a list of
regular expressions, you must use the <tag>p:with-option</tag>
syntax.
</para>
</note>

<para xml:id="cv.directory">The result document produced for the specified directory path has a <tag>c:directory</tag>
document element whose base URI, attached as an <tag role="attribute">xml:base</tag> attribute, is the absolute
directory path (expressed as a URI that ends in a slash) and whose <tag class="attribute">name</tag> attribute
(without a trailing slash) is the last segment of the directory path.</para>

<e:rng-pattern name="VocabDirectory"/>

<para>Its contents are determined as follows, based on the entries in the directory identified by the directory path.
For each entry in the directory and subject to the rules that are imposed by the <option>max-depth</option>,
<option>include-filter</option>, and <option>exclude-filter</option> options, a <tag>c:file</tag>, a
<tag>c:directory</tag>, or a <tag>c:other</tag> element is produced, as follows: </para>

<itemizedlist>
<listitem>
<para>A <tag>c:directory</tag> is produced for each subdirectory not determined to be special. Depending on the
values of the three options, it may contain child elements for the directory’s content.</para>
</listitem>
<listitem>
<para xml:id="cv.file">A <tag>c:file</tag> is produced for each file
not determined to be special.</para>
<e:rng-pattern name="VocabFile"/>
</listitem>
<listitem>
<para xml:id="cv.other"><impl>Any file or directory determined to be
special by the <tag>p:directory-list</tag> step may be output using a
<tag>c:other</tag> element but the criteria for marking a file as
special are <glossterm>implementation-defined</glossterm>.</impl>
</para>
<e:rng-pattern name="VocabOther"/>
</listitem>
</itemizedlist>

<para>Each of the elements <tag>c:file</tag>, <tag>c:directory</tag>,
and <tag>c:other</tag> has a <code>name</code> attribute, whose
value is a relative IRI reference, giving the (local) file or
directory name.</para>

<para>Each of these element also contains the corresponding resource’s URI in an <tag role="attribute">xml:base</tag>
attribute, which may be a relative URI for any but the top-level <tag>c:directory</tag> element. In the case of
<tag>c:directory</tag>, it must end in a trailing slash. This way, users will always be able to compute the
absolute URI for any of these elements by applying <code>fn:base-uri()</code> to it.</para>

<section xml:id="dir-list-details">
<title>Directory list details</title>

<para>If <option>detailed</option> is false, then only the
<tag class="attribute">name</tag> and <tag class="attribute">xml:base</tag> attributes are expected on
<tag>c:file</tag>, <tag>c:directory</tag>, or <tag>c:other</tag>
elements.</para>

<para>If <option>detailed</option> is true, then the pipeline author
is expecting additional details about each entry. The following attributes
<rfc2119>should</rfc2119> be provided by the implementation:</para>

<variablelist>
<varlistentry><term><tag class="attribute">readable</tag></term>
<listitem><para>“<code>true</code>” if the entry is readable.</para>
</listitem>
</varlistentry>
<varlistentry><term><tag class="attribute">writable</tag></term>
<listitem><para>“<code>true</code>” if the entry is writable.</para>
</listitem>
</varlistentry>
<varlistentry><term><tag class="attribute">hidden</tag></term>
<listitem><para>“<code>true</code>” if the entry is hidden.</para>
</listitem>
</varlistentry>
<varlistentry><term><tag class="attribute">last-modified</tag></term>
<listitem><para>The last modification time of the entry, expressed as a lexical
<code>xs:dateTime</code> in UTC.</para>
</listitem>
</varlistentry>
<varlistentry><term><tag class="attribute">size</tag></term>
<listitem><para>The size of the entry in bytes.</para>
</listitem>
</varlistentry>
</variablelist>

<para><impl>The precise meaning of these properties are
<glossterm>implementation-defined</glossterm> and may vary according
to the URI scheme of the <option>path</option>.</impl>
If the value of an attribute is “<code>false</code>” or if it has no
meaningful value, the attribute may be omitted.</para>

<para><impl>Any other attributes on
<tag>c:file</tag>, <tag>c:directory</tag>, or <tag>c:other</tag>
are <glossterm>implementation-defined</glossterm>.</impl></para>
</section>

<simplesect>
<title>Document properties</title>
<para feature="directory-list-preserves-none">No document properties are preserved.</para>
</simplesect>
</section>

<section xml:id="c.file-copy">
<title>p:file-copy</title>

<para>The <code>p:file-copy</code> step copies a file.</para>
@@ -519,6 +716,7 @@ failure causes the entire pipeline to fail.</para>
<bibliolist>
<bibliomixed xml:id="xproc30"/>
<bibliomixed xml:id="xproc30-steps"/>
<bibliomixed xml:id="xpath31-functions"/>
</bibliolist>
</appendix>

@@ -175,7 +175,6 @@ linkend="rfc2119"/>.</para>
<xi:include href="steps/compare.xml"/>
<xi:include href="steps/count.xml"/>
<xi:include href="steps/delete.xml"/>
<xi:include href="steps/directory-list.xml"/>
<xi:include href="steps/error.xml"/>
<xi:include href="steps/escape-markup.xml"/>
<xi:include href="steps/filter.xml"/>

0 comments on commit 4371d1f

Please sign in to comment.
You can’t perform that action at this time.