Built-in file tools | ToolDef documentation

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

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`.

"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.