p:file-mkdir (3.0)

Creates a directory.

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

Summary

<p:declare-step type="p:file-mkdir">
  <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()"/>
</p:declare-step>

The p:file-mkdir step creates the directory specified in the href option.

Ports:

Port	Type	Primary?	Content types	Seq?	Description
`result`	`output`	`true`	`application/xml`	`false`	A `<c:result>` element containing the absolute URI of the created directory (the `c` prefix here is bound to the `http://www.w3.org/ns/xproc-step` namespace).

Options:

Name	Type	Req?	Default	Description
`href`	`xs:anyURI`	`true`		The URI of the directory to create.
`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.

Name

Type

Req?

Default

Description

href

xs:anyURI

true

The URI of the directory to create.

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.

Description

The p:file-mkdir step creates the directory specified in the href option . The result port emits a small XML document with only a <c:result> element, containing the absolute URI of the created directory (the c prefix here is bound to the http://www.w3.org/ns/xproc-step namespace).

Any non-existent directories leading up to the final directory to create are created also.

Examples

Basic usage

The following example creates a build directory:

Pipeline document:

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

  <p:output port="result"/>

  <p:file-mkdir href="build"/>
  
</p:declare-step>

Result document:

<c:result xmlns:c="http://www.w3.org/ns/xproc-step">file:/…/…/build</c:result>

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-mkdir 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
`XC0114`	It is a dynamic error if the directory referenced by the `href` option cannot be created.
`XC0140`	It is a dynamic error if an implementation does not support `<p:file-mkdir>` for a specified scheme.
`XC0141`	It is a dynamic error if `<p:file-mkdir>` not available to the step due to access restrictions in the environment in which the pipeline is run.
`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-mkdir 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-mkdir step can be found here.

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

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