Skip to content
Permalink
Browse files

Merge pull request xproc#105 from gimsieke/directory-list

address issues discussed in xproc#89
  • Loading branch information...
ndw committed Jun 10, 2019
2 parents cad45e4 + 0d38b2e commit a4bbf347425b3f9a4c3205480352c77cf0c01686
Showing with 34 additions and 12 deletions.
  1. +34 −12 steps/src/main/xml/steps/directory-list.xml
@@ -52,25 +52,47 @@ one representing a regular expressions as specified in <biblioref linkend="xpath
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. Prior to be matched against the regular expression, the relative path
will be completed with a leading slash and, if the item is a directory, with a trailing slash.</para>
<para>Examples: A file <literal>file.txt</literal> in the directory specified by <option>path</option> will become
<literal>/file.txt</literal>. A relative path <literal>dir1/file.txt</literal> will become
<literal>/dir1/file.txt</literal>. A relative path <literal>dir1/dir2</literal> will become
<literal>/dir1/dir2/</literal>. A relative path <literal>a/a/b/file.txt</literal> will become
<literal>/a/a/b/file.txt</literal>.</para>
<para>Regular expression that match <literal>/a/a/b/file.txt</literal> are, for example,
<literal>^/(\w+/){2,3}.+\.txt$</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 any
<option>exclude-filter</option> pattern matches the slash-augmented relative path, the entry is excluded in the output. If both options are
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> id <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. Example: 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:<literallayout>&lt;c:directory xml:base="file:/home/jane/` uri="." name="jane">
&lt;c:directory uri="a/" name="a">
&lt;c:directory uri="a/a/" name="a">
&lt;c:directory uri="a/a/b/" name="b">
&lt;c:file uri="a/a/b/file.txt" name="file.txt"/>
&lt;/c:directory>
&lt;/c:directory>
&lt;/c:directory>
&lt;/c:directory></literallayout></para>
<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>

<para>The augmented relative path will also be stored as a <tag role="attribute">uri</tag> attribute on the respective
<tag>c:directory</tag>, <tag>c:file</tag>, and <tag>c:other</tag> elements. This relative URI, if resolved against
the top-level directory’s <tag role="attirubte">xml:base</tag> attribute value, will give the absolute URI for the
resource. The top-level <tag>c:directory</tag> will always have the relative URI <literal>.</literal> attached to
it, while its <tag role="attribute">xml:base</tag> will also undergo trailing-slash normalization, which is to say,
it always must end in a slash.</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

0 comments on commit a4bbf34

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