Built-in file tools
This page describes the built-in I/O tools:
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
orlines
are replaced by the new line of the current platform. The new line of the current platform is also written after each of thelines
."preserve"
Write the
text
'as is'. The new lines as they are in the giventext
are preserved. Using"preserve"
is not supported when writinglines
.Any other value
Write the text or lines of text with the given new line. All new lines in the given
text
orlines
are replaced by the given new line text. The given new line text is also written after each of thelines
.
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 fornewline
when writinglines
.