## Built-in file tools

This page describes the built-in I/O tools:

- cpfile

- cpdir

- diff

- exists

- filenewer

- filesize

- find

- isdir

- isfile

- mkdir

- mvfile

- mvdir

- readlines

- rmfile

- rmdir

- writefile

### cpfile tool

    tool cpfile(string source, string target, bool overwrite = false)

Copies a file from a source location to a target location.

Parameters

`source`

  The absolute or relative local file system path of the source file. May contain both `\` and `/` as file separators.

`target`

  The absolute or relative local file system path of the target file. May contain both `\` and `/` as file separators.

`overwrite`

  Whether to overwrite the target file if it already exists.

Runtime errors

- If the source file does not exist.

- If the source is a directory rather than a file.

- If it can not be determined whether the source path refers to a file or a directory.

- If the target file exists and overwriting is not allowed.

- If the target file exists and overwriting is allowed, but the target refers to a directory rather than a file.

- If the target file exists and overwriting is allowed, but it can not be determined whether the target path refers to a file or a directory.

- If copying the file failed due to an I/O error.

### cpdir tool

    tool cpdir(string source, string target)

Copies a directory from a source location to a target location. All files and directories in the source directory are copied recursively.

If the operation fails, part of the operation may have already been performed.

Parameters

`source`

  The absolute or relative local file system path of the source directory. All files and directories in the source directory are copied recursively. May contain both `\` and `/` as file separators.

`target`

  The absolute or relative local file system path of the target directory. This is the directory in which the contents of the source directory are copied. The source directory itself is not copied, only the files and directories contained in the source directory. May contain both `\` and `/` as file separators.

Runtime errors

- If the source directory does not exist.

- If the source is a file rather than a directory.

- If it can not be determined whether the source path refers to a file or a directory.

- If the target directory already exists.

- If the target directory doesn’t exist, but one of the ancestors is not a directory.

- If walking the directory (recursively) fails.

- If walking the directory (recursively) encounters a file system cycle (due to symbolic links).

- If a file or (sub-)directory could not be copied due to an I/O error.

### diff tool

    tool bool diff(string file1, string file2, string output = "-", bool missingAsEmpty = false, bool warnOnDiff = false, bool failOnDiff = false)

Computes the differences between two files.

Parameters

`file1`

  The absolute or relative local file system path of the first file. May contain both `\` and `/` as file separators.

`file2`

  The absolute or relative local file system path of the second file. May contain both `\` and `/` as file separators.

`output`

  Specify whether/where to write a unified diff if the files differ. Use `""` to not write a unified diff, `"-"` to write the unified diff to the standard output stream (stdout), or otherwise an absolute or relative local file system path of the file to which to write the unified diff. May contain both `\` and `/` as file separators.

`missingAsEmpty`

  Treat a missing first/second file as empty (`true`) or as an error (`false`).

`warnOnDiff`

  Emit a warning for differing files (`true`) or not (`false`). If a warning is emitted to the standard error stream (stderr), the unified diff (if enabled) is printed first.

`failOnDiff`

  Treat differing files as an error (`true`) or not (`false`). If an error is emitted, the unified diff (if enabled) and warning (if enabled) are printed first.

Returns

`true` if the files differ, `false` otherwise.

Runtime errors

- If either the first or second file doesn’t exist and `missingAsEmpty` is disabled.

- If the first or second file is not a file but a directory.

- If it can not be determined whether the first or second path refers to a file or a directory.

- If an I/O error occurs.

- If the `out` file exists but is a directory rather than a regular file.

- If the `out` file does not exist but cannot be created.

- If the `out` file cannot be opened for writing for any other reason.

- If an I/O error occurs while writing to the `out` file.

- If the `out` file can not be closed.

- If the files differ and `failOnDiff` is enabled.

### exists tool

    tool bool exists(string path)

Does a file or directory with the given path exist?

Parameters

`path`

  The absolute or relative local file system path of the file or directory. May contain both `\` and `/` as file separators.

Returns

`true` if the file or directory exists, `false` otherwise.

### filenewer tool

    tool bool filenewer(string path, string refpath,       bool allowNonExisting = false, bool sameAsNewer = true)
    tool bool filenewer(string path, string... refpaths,   bool allowNonExisting = false, bool sameAsNewer = true)
    tool bool filenewer(string path, list string refpaths, bool allowNonExisting = false, bool sameAsNewer = true)

Checks whether a file is newer (was modified at a later date/time) than some reference file(s). The minimum modification time difference that can be detected is 1 millisecond.

Parameters

`path`

  The absolute or relative local file system path of the file for which to check whether it is newer than the reference file(s). May contain both `\` and `/` as file separators.

`refpath`, `refpaths`

  The absolute or relative local file system path of the reference file(s). May contain both `\` and `/` as file separators.

`allowNonExisting`

  Whether to allow the first file to not exist (`true`) or consider it an error if the first file does not exist (`false`).

`sameAsNewer`

  Whether to treat files with the same last change date as being the same (`false`) or as newer (`true`).

Returns

`false` if the first file does not exist (if allowed by enabling `allowNonExisting`), if the first file is older than any the reference files, or if the first file has the same last change date as any of the reference files and `sameAsNewer` is disabled. `true` if the first file is newer than all of the reference files, if the first file has the same last change date as some of the reference files and `sameAsNewer` is enabled and is newer than all of the other reference files, or if the first file has the same last change date as all the reference files and `sameAsNewer` is enabled.

Runtime errors

- If the first file does not exist and `allowNonExisting` is disabled.

- If any of the reference files does not exist.

- If any of the files is a directory rather than a file.

- If for any of the paths it can not be determined whether the path refers to a file or a directory.

- If the last change date/time of any of the files can not be determined.

### filesize tool

    tool long filesize(string path, bool missingAsZero = false)

Returns the size of the file, in bytes.

Parameters

`path`

  The absolute or relative local file system path of the file. May contain both `\` and `/` as file separators.

`missingAsZero`

  Whether to return 0 if the file does not exist (`true`) or consider it an error if the file does not exist (`false`).

Returns

The size of the file in bytes, or `0` if the file is missing and `missingAsZero` is enabled.

Runtime errors

- If the file does not exist and `missingAsZero` is disabled.

- If the file is a directory rather than a file.

- If it can not be determined whether the path refers to a file or a directory.

- If the size of the file can not be determined due to an I/O error.

### find tool

    tool list string find(string path, string pattern = "*", bool recursive = true, bool files = true, bool dirs = true)

Searches a directory for files and/or directories matching a pattern.

Parameters

`path`

  The absolute or relative local file system path of the directory in which to search. The directory itself is never returned. May contain both `\` and `/` as file separators.

`pattern`

  The pattern to use to match files/directories. Is a Java NIO glob pattern, that is matched against single file names or single directory names, and never against paths. Pattern `"*"` matches all files and directories.

`recursive`

  Whether to recursively look in sub-directories.

`files`

  Whether to match files.

`dirs`

  Whether to match directories.

Returns

The local file system paths of the matched files and directories, relative against the given root directory from which searching started.

Runtime errors

- If the given directory is not found.

- If the given directory is a file rather than a directory.

- If the can not be determined whether the given path refers to a file or a directory.

- If the pattern is invalid.

- If walking the directory (recursively) fails.

- If walking the directory (recursively) encounters a file system cycle (due to symbolic links).

- If the operation fails due to an I/O error.

### isdir tool

    tool bool isdir(string path)

Does a directory with the given path exist?

Parameters

`path`

  The absolute or relative local file system path of the directory. May contain both `\` and `/` as file separators.

Returns

`true` if the directory exists, `false` if it doesn’t exist or is not a directory.

### isfile tool

    tool bool isfile(string path)

Does a file with the given path exist?

Parameters

`path`

  The absolute or relative local file system path of the file. May contain both `\` and `/` as file separators.

Returns

`true` if the file exists, `false` if it doesn’t exist or is not a file.

### mkdir tool

    tool mkdir(string path, bool force = false, bool parents = true)

Creates the given directory, and optionally its parents as needed.

Parameters

`path`

  The absolute or relative local file system path of the directory to create. May contain both `\` and `/` as file separators.

`force`

  Whether to skip creating the directory if it already exists (`true`) or fail if it already exists (`false`).

`parents`

  Whether to allow creating parents as needed (`true`) or fail if the parent directory does not exist (`false`).

Runtime errors

- If the directory already exists and `force` is disabled.

- If creating the directory or any of its parents fails, due to an I/O error.

### mvfile tool

    tool mvfile(string source, string target, bool overwrite = false)

Moves a file from a source location to a target location. This can be used to rename a file and/or move it to another directory.

Parameters

`source`

  The absolute or relative local file system path of the source file. May contain both `\` and `/` as file separators.

`target`

  The absolute or relative local file system path of the target file. May contain both `\` and `/` as file separators.

`overwrite`

  Whether to overwrite the target file if it already exists.

Runtime errors

- If the source file does not exist.

- If the source is a directory rather than a file.

- If it can not be determined whether the source path refers to a file or a directory.

- If the target file exist and overwriting is not allowed.

- If the target file exists and overwriting is allowed, but the target refers to a directory rather than a file.

- If the target file exists and overwriting is allowed, but it can not be determined whether the target path refers to a file or a directory.

- If moving the file fails due to an I/O error.

### mvdir tool

    tool mvdir(string source, string target)

Moves a directory from a source location to a target location. The directory and all files and directories in it are moved recursively.

The operation is implemented as a copy from source to target, followed by a remove of the source. If the operation fails, part of the operation may have already been performed.

Parameters

`source`

  The absolute or relative local file system path of the source directory. The directory itself and all files and directories in it are moved recursively. May contain both `\` and `/` as file separators.

`target`

  The absolute or relative local file system path of the target directory. This is the directory into which the contents of the source directory are moved. May contain both `\` and `/` as file separators.

Runtime errors

- If the source directory does not exist.

- If the source is a file rather than a directory.

- If it can not be determined whether the source path refers to a file or a directory.

- If the target directory already exists.

- If the target directory doesn’t exist but one of the ancestors is not a directory.

- If walking the directory (recursively) fails.

- If walking the directory (recursively) encounters a file system cycle (due to symbolic links).

- If a file or (sub-)directory can not be copied or removed, due to an I/O error.

### readlines tool

    tool list string readlines(string path)

Read lines of text from a file. Uses UTF-8 encoding when reading the file.

Parameters

`path`

  The absolute or relative local file system path of the file to read. May contain both `\` and `/` as file separators.

Returns

The lines of text from the file.

Runtime errors

- If the file does not exist.

- If the path refers to a directory rather than a file.

- If it can not be determined whether the path refers to a file or a directory.

- If for some other reason can not be opened for reading.

- If an I/O error occurs.

- If the file can not be closed.

### rmfile tool

    tool bool rmfile(string path, bool force = false)

Removes a file.

Parameters

`path`

  The absolute or relative local file system path of the file. May contain both `\` and `/` as file separators.

`force`

  Whether to ignore non-existing files (`true`) or consider it an error (`false`).

Returns

`true` if the file was removed, `false` if it could not be removed because it did not exist and force is enabled.

Runtime errors

- If the file does not exist and `force` is disabled.

- If the file is a directory rather than a file.

- If it can not be determined whether the path refers to a file or a directory.

- If an I/O error occurs.

- If the file can not be removed for some other reason.

### rmdir tool

    tool bool rmdir(string path, bool force = false)

Removes a directory, recursively.

Parameters

`path`

  The absolute or relative local file system path of the directory. May contain both `\` and `/` as file separators.

`force`

  Whether to ignore non-existing directories (`true`) or consider it an error (`false`).

Returns

`true` if the directory was removed, `false` if it could not be removed because it did not exist and `force` is enabled.

Runtime errors

- If the directory does not exist and `force` is disabled.

- If the directory is a file rather than a directory.

- If it can not be determined whether the path refers to a file or a directory.

- If an I/O error occurs.

- If walking the directory (recursively) fails.

- If walking the directory (recursively) encounters a file system cycle (due to symbolic links).

- If the directory or one of its sub-files or sub-directories can not be removed for some other reason.

### writefile tool

    tool writefile(string path, string text,       bool append = false, string newline = "platform")
    tool writefile(string path, list string lines, bool append = false, string newline = "platform")

Writes text to a file. Uses UTF-8 encoding when writing the file.

Parameters

`path`

  The absolute or relative local file system path of the file. May contain both `\` and `/` as file separators.

`text`, `lines`

  The text or lines of text to write to the file. In case `lines` are given, a new line will additionally be written after each line of text.

`append`

  Whether to append the lines text to the file if it already exists (`true`), or overwrite the file if it already exists (`false`).

`newline`

  Indicates how to handle new lines:

  Value | Effect
  --- | ---
  `"platform"` | Write the text or lines of text with platform-specific new lines. All new lines in the given `text` or `lines` are replaced by the new line of the current platform. The new line of the current platform is also written after each of the `lines`.
  `"preserve"` | Write the `text` 'as is'. The new lines as they are in the given `text` are preserved. Using `"preserve"` is not supported when writing `lines`.
  Any other value | Write the text or lines of text with the given new line. All new lines in the given `text` or `lines` are replaced by the given new line text. The given new line text is also written after each of the `lines`.

Runtime errors

- If the path exists but is a directory rather than a regular file.

- If the file does not exist, but cannot be created.

- If the file can not be opened for writing for any other reason.

- If writing to the file fails due to an I/O error.

- If closing the file fails.

- If `"preserve"` is given for `newline` when writing `lines`.