Name
p:directory-list — The standard p:directory-list step.
Synopsis
The p:directory-list step produces a list of the contents
of a specified directory.
| Output port | Primary | Sequence | Content types |
|---|---|---|---|
| result | ✔ | application/xml |
| Option name | Type | Default value | Required |
|---|---|---|---|
| path | xs:anyURI | ✔ | |
| detailed | xs:boolean | false() | |
| exclude-filter | xs:string* | () | |
| include-filter | xs:string* | () | |
| max-depth | xs:string? | '1' | |
| override-content-types | array(array(xs:string))? | () |
Declaration
1 |<p:declare-step xmlns:p="http://www.w3.org/ns/xproc">
| <p:output port="result" content-types="application/xml"/>
| <p:option name="path" required="true" as="xs:anyURI"/>
| <p:option name="detailed" as="xs:boolean" select="false()"/>
5 | <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:option name="override-content-types" as="array(array(xs:string))?"/>
|</p:declare-step>Errors
| Code | Description |
|---|---|
err:XC0012 | It is a
dynamic error (err:XC0012) 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. |
err:XC0017 | It is a
dynamic error (err:XC0017) if the absolute path does not
identify a directory. |
err:XC0090 | It is a dynamic error (err:XC0090) if an
implementation does not support directory listing for a specified scheme. |
err:XC0147 | It is a dynamic
error (err:XC0147) if a specified value is not a valid XPath regular
expression. |
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
- Conformant processors must support directory paths whose
scheme is
file. It is implementation-defined what other schemes are supported byp:directory-list, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes. - Any file or directory determined to be
special by the
p:directory-liststep may be output using ac:otherelement but the criteria for marking a file as special are implementation-defined. - The precise meaning of the detailed properties are
implementation-defined and may vary according
to the URI scheme of the
path. - Any other attributes on
c:file,c:directory, orc:otherare implementation-defined
Description
The p:directory-list step is defined in the
XProc 3.1:
Standard Step Library. It is also described on
XProcRef.org.
Detailed attributes
When the detailed option is true(), the
p:directory-list step provides additional information about each entry.
For directories, those details are:
readable (is the entry readable by the current user),
writable (is the entry writable by the current user),
hidden (is the entry “hidden”),
size (the size of the entry in bytes), and
last-modified (the date and time of the last modification).
Precisely what “hidden” means varies by platform. On Unix-based systems, it often means only
that the filename begins with a “.”. On Windows systems, it reports the setting of the
filesystem’s hidden attribute on filesystems that support it.
XML Calabash also reports if the entry is “executable” in the
cx:executable attribute.
On most systems, the size of a directory is a reflection of the amount of space the directory data structure itself occupies: it is not the sum of the sizes of all of the files contained in the directory.
On systems that support POSIX file attributes, readable, writable, and executable are
taken from the POSIX subsystem. On systems that don’t support POSIX, they’re taken
from Java methods on File objects. If the system supports
POSIX file attributes, XML Calabash reports additional details:
cx:group-readable,
cx:group-writable, and
cx:group-executable (is the entry readable, writable,
and executable by members of the current group) and
cx:other-readable,
cx:other-writable, and
cx:other-executable (is the entry readable, writable,
and executable by others).
For files, all of the preceding details are provided as well as the
content-type of the file. Content types are determined
from the filename (generally, the extension), not by inspecting
the contents of the file.
Examples
Applied to the running example, the
p:directory-list step with the detailed option enabled,
returns a result like this on a system that supports POSIX file attributes:
1 |<c:directory xmlns:c="http://www.w3.org/ns/xproc-step"
| xmlns:cx="http://xmlcalabash.com/ns/extensions"
| xml:base="file:/path/to/examples/xml/"
| name="xml"
5 | readable="true"
| writable="true"
| cx:executable="true"
| cx:group-readable="true"
| cx:group-writable="false"
10 | cx:group-executable="true"
| cx:other-readable="true"
| cx:other-writable="false"
| cx:other-executable="true"
| hidden="false"
15 | size="160"
| last-modified="2024-12-29T18:25:10Z">
| <c:file xml:base="default-ch2.xml"
| name="default-ch2.xml"
| content-type="application/xml"
20 | readable="true"
| writable="true"
| cx:executable="false"
| cx:group-readable="true"
| cx:group-writable="false"
25 | cx:group-executable="false"
| cx:other-readable="true"
| cx:other-writable="false"
| cx:other-executable="false"
| hidden="false"
30 | size="100"
| last-modified="2024-11-24T17:23:22Z"/>
| <c:file xml:base="default-input.xml"
| name="default-input.xml"
| content-type="application/xml"
35 | readable="true"
| writable="true"
| cx:executable="false"
| cx:group-readable="true"
| cx:group-writable="false"
40 | cx:group-executable="false"
| cx:other-readable="true"
| cx:other-writable="false"
| cx:other-executable="false"
| hidden="false"
45 | size="366"
| last-modified="2024-11-24T17:23:22Z"/>
|</c:directory>