p:file-info (3.0)

Returns information about a file or directory.

Summary
Description
- The result document
Examples
- Basic usage
Additional details
Errors raised
Reference information

Summary

<p:declare-step type="p:file-info">
  <output port="result" primary="true" content-types="application/xml" sequence="false"/>
  <option name="href" as="xs:anyURI" required="true"/>
  <option name="fail-on-error" as="xs:boolean" required="false" select="true()"/>
  <option name="override-content-types" as="array(array(xs:string))?" required="false" select="()"/>
</p:declare-step>

The p:file-info step returns information about a file or directory (or other file system object).

Ports:

Port	Type	Primary?	Content types	Seq?	Description
`result`	`output`	`true`	`application/xml`	`false`	A small XML document, describing the file or directory referenced by the `href` option. See The result document.

Options:

Name	Type	Req?	Default	Description
`href`	`xs:anyURI`	`true`		The URI of the file or directory to describe.
`fail-on-error`	`xs:boolean`	`false`	`true`	Determines what happens if an error occurs during the operation: If this option is `true` (default), an appropriate XProc error is raised. If this option is `false`, the step returns a `<c:error>` document (see here for more information) on its `result` port.
`override-content-types`	`array(array(xs:string))?`	`false`	`()`	Use this to override the content-type determination of files. This works just like the mechanism for the `override-content-types` option of `p:archive-manifest`, except that the regular expression matching is done against the absolute URI of the file.

Name

Type

Req?

Default

Description

href

xs:anyURI

true

The URI of the file or directory to describe.

fail-on-error

xs:boolean

false

true

Determines what happens if an error occurs during the operation:

If this option is true (default), an appropriate XProc error is raised.
If this option is false, the step returns a <c:error> document (see here for more information) on its result port.

override-content-types

array(array(xs:string))?

false

()

Use this to override the content-type determination of files.

This works just like the mechanism for the override-content-types option of p:archive-manifest, except that the regular expression matching is done against the absolute URI of the file.

Description

The p:file-info step returns information about a file or directory (or other file system object) as a small XML document on its result port. What will be returned is dependent on the type of file system object, see The result document.

The result document

The result document describing a file or directory consists of either a <c:file> or <c:directory> element (the c prefix here is bound to the http://www.w3.org/ns/xproc-step namespace). These elements and their attributes are the same as returned by p:directory-list for such a file system object (with the detailed option set to true).

If the href option references any other system object (for instance, on Unix, a device), the result is implementation-defined and therefore depends on the XProc processor used.

Examples

Basic usage

The following example returns information about the data/ directory

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:output port="result"/>

  <p:file-info href="data/"/>
  
</p:declare-step>

Result document:

<c:directory xmlns:c="http://www.w3.org/ns/xproc-step"
             xml:base="file:/…/…/data/"
             name="data"
             readable="true"
             writable="true"
             hidden="false"
             last-modified="2024-12-31T14:05:13.01Z"
             size="0"/>

Notice that the result has an xml:base attribute with the absolute URI of the object described. This is attribute is not mandatory, but you can very probably rely on it being there.

Describing a file looks like this:

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:output port="result"/>

  <p:file-info href="data/x.xml"/>
  
</p:declare-step>

Result document:

<c:file xmlns:c="http://www.w3.org/ns/xproc-step"
        xml:base="file:/…/…/data/x.xml"
        name="x.xml"
        content-type="application/xml"
        readable="true"
        writable="true"
        hidden="false"
        last-modified="2024-12-31T14:05:13.01Z"
        size="88"/>

Additional details

The document appearing on the result port only has a content-type property. It has no other document-properties (also no base-uri).
Relative values for the href option are resolved against the base URI of the element on which this option is specified. In most cases this will be the static base URI of your pipeline (the path where the XProc source containing the p:file-info is stored).
Working on “normal” files and/or directories (on disk, URI scheme file://) is always supported. Whether any other types are supported is implementation-defined, and therefore depends on the XProc processor used. For this, also the interpretation/definition of what is a “directory” and “file” may vary.

Errors raised

Error code	Description
`XC0134`	It is a dynamic error if an implementation does not support `<p:file-info>` for a specified scheme.
`XC0135`	It is a dynamic error if `<p:file-info>` is not available to the step due to access restrictions in the environment in which the pipeline is run.
`XD0011`	It is a dynamic error if the resource referenced by the `href` option does not exist, cannot be accessed or is not a file.
`XD0064`	It is a dynamic error if the base URI is not both absolute and valid according to RFC 3986 .

Reference information

This description of the p:file-info step is for XProc version: 3.0. This is a non-required step (an XProc 3.0 processor does not have to support this).

The formal specification for the p:file-info step can be found here.

The p:file-info step is part of categories:

The p:file-info step is also present in version: 3.1.