16 KiB
Paths and Files
Tomo supports a built-in syntax for file and directory paths, with some logic to help prevent or mitigate the risks of errors caused by string manipulations of file paths. Tomo does not have a built-in datatype to represent files specifically, but instead relies on Paths as the API to do filesystem operations.
Syntax
Paths are domain-specific languages that have their own dedicated
syntax. A path literal begins with either (/, (./, (../, or (~/ and continues
until a matching closing parenethesis:
>> (/tmp)
= (/tmp)
>> (~/path with/(parens) is/ok/)
= (~/path with/(parens) is/ok/)
Interpolation
Paths can contain interpolations using $, just like strings. However, there are
certain values that cannot be interpolated:
- The literal string
. - The literal string
.. - Any text that contains a forward slash (
/)
The intended use for path interpolation is to take user input which may or may
not be trustworthy and interpret that value as a single path component name,
i.e. the name of a directory or file. If a user were to supply a value like
.. or foo/baz, it would risk navigating into a directory other than
intended. Paths can be created from text with slashes using
Path.without_escaping(text) if you need to use arbitrary text as a file path.
Path Methods
append
Description:
Appends the given text to the file at the specified path, creating the file if
it doesn't already exist. Failure to write will result in a runtime error.
Signature:
func append(path: Path, text: Text, permissions: Int32 = 0o644[32] -> Void)
Parameters:
path: The path of the file to append to.text: The text to append to the file.permissions(optional): The permissions to set on the file if it is being created (default is0o644).
Returns:
Nothing.
Example:
(./log.txt):append("extra line$(\n)")
append_bytes
Description:
Appends the given bytes to the file at the specified path, creating the file if
it doesn't already exist. Failure to write will result in a runtime error.
Signature:
func append_bytes(path: Path, bytes: [Byte], permissions: Int32 = 0o644[32] -> Void)
Parameters:
path: The path of the file to append to.bytes: The bytes to append to the file.permissions(optional): The permissions to set on the file if it is being created (default is0o644).
Returns:
Nothing.
Example:
(./log.txt):append_bytes([104[B], 105[B]])
base_name
Description:
Returns the base name of the file or directory at the specified path.
Signature:
func base_name(path: Path -> Text)
Parameters:
path: The path of the file or directory.
Returns:
The base name of the file or directory.
Example:
>> (./path/to/file.txt):base_name()
= "file.txt"
by_line
Description:
Returns an iterator that can be used to iterate over a file one line at a time,
or returns a null value if the file could not be opened.
Signature:
func by_line(path: Path -> func(->Text?)?)
Parameters:
path: The path of the file.
Returns:
An iterator that can be used to get lines from a file one at a time or a null
value if the file couldn't be read.
Example:
# Safely handle file not being readable:
if lines := (./file.txt):by_line():
for line in lines:
say(line:upper())
else:
say("Couldn't read file!")
# Assume the file is readable and error if that's not the case:
for line in (/dev/stdin):by_line()!:
say(line:upper())
children
Description:
Returns a list of children (files and directories) within the directory at the specified path. Optionally includes hidden files.
Signature:
func children(path: Path, include_hidden=no -> [Path])
Parameters:
path: The path of the directory.include_hidden(optional): Whether to include hidden files, which start with a.(default isno).
Returns:
A list of paths for the children.
Example:
>> (./directory):children(include_hidden=yes)
= [".git", "foo.txt"]
create_directory
Description:
Creates a new directory at the specified path with the given permissions. If
any of the parent directories do not exist, they will be created as needed.
Signature:
func create_directory(path: Path, permissions=0o755[32] -> Void)
Parameters:
path: The path of the directory to create.permissions(optional): The permissions to set on the new directory (default is0o644).
Returns:
Nothing.
Example:
(./new_directory):create_directory()
exists
Description:
Checks if a file or directory exists at the specified path.
Signature:
func exists(path: Path -> Bool)
Parameters:
path: The path to check.
Returns:
True if the file or directory exists, False otherwise.
Example:
>> (/):exists()
= yes
extension
Description:
Returns the file extension of the file at the specified path. Optionally returns the full extension.
Signature:
func extension(path: Path, full=yes -> Text)
Parameters:
path: The path of the file.full(optional): Whether to return everything after the first.in the base name, or only the last part of the extension (default isyes).
Returns:
The file extension (not including the leading .) or an empty text if there is
no file extension.
Example:
>> (./file.tar.gz):extension()
= "tar.gz"
>> (./file.tar.gz):extension(full=no)
= "gz"
>> (/foo):extension()
= ""
>> (./.git):extension()
= ""
files
Description:
Returns a list of files within the directory at the specified path. Optionally includes hidden files.
Signature:
func files(path: Path, include_hidden=no -> [Path])
Parameters:
path: The path of the directory.include_hidden(optional): Whether to include hidden files (default isno).
Returns:
A list of file paths.
Example:
>> (./directory):files(include_hidden=yes)
= [(./directory/file1.txt), (./directory/file2.txt)]
glob
Description:
Perform a globbing operation and return an array of matching paths. Some glob
specific details:
- The paths "." and ".." are not included in any globbing results.
- Files or directories that begin with "." will not match
*, but will match.*. - Globs do support
{a,b}syntax for matching files that match any of several choices of patterns. - The shell-style syntax
**for matching subdirectories is not supported.
Signature:
func glob(path: Path -> [Path])
Parameters:
path: The path of the directory which may contain special globbing characters like*,?, or{...}
Returns:
A list of file paths that match the glob.
Example:
# Current directory includes: foo.txt, baz.txt, qux.jpg, .hidden
>> (./*):glob()
= [(./foo.txt), (./baz.txt), (./qux.jpg)]
>> (./*.txt):glob()
= [(./foo.txt), (./baz.txt)]
>> (./*.{txt,jpg}):glob()
= [(./foo.txt), (./baz.txt), (./qux.jpg)]
>> (./.*):glob()
= [(./.hidden)]
# Globs with no matches return an empty array:
>> (./*.xxx):glob()
= []
is_directory
Description:
Checks if the path represents a directory. Optionally follows symbolic links.
Signature:
func is_directory(path: Path, follow_symlinks=yes -> Bool)
Parameters:
path: The path to check.follow_symlinks(optional): Whether to follow symbolic links (default isyes).
Returns:
True if the path is a directory, False otherwise.
Example:
>> (./directory/):is_directory()
= yes
>> (./file.txt):is_directory()
= no
is_file
Description:
Checks if the path represents a file. Optionally follows symbolic links.
Signature:
func is_file(path: Path, follow_symlinks=yes -> Bool)
Parameters:
path: The path to check.follow_symlinks(optional): Whether to follow symbolic links (default isyes).
Returns:
True if the path is a file, False otherwise.
Example:
>> (./file.txt):is_file()
= yes
>> (./directory/):is_file()
= no
is_socket
Description:
Checks if the path represents a socket. Optionally follows symbolic links.
Signature:
func is_socket(path: Path, follow_symlinks=yes -> Bool)
Parameters:
path: The path to check.follow_symlinks(optional): Whether to follow symbolic links (default isyes).
Returns:
True if the path is a socket, False otherwise.
Example:
>> (./socket):is_socket()
= yes
is_symlink
Description:
Checks if the path represents a symbolic link.
Signature:
func is_symlink(path: Path -> Bool)
Parameters:
path: The path to check.
Returns:
True if the path is a symbolic link, False otherwise.
Example:
>> (./link):is_symlink()
= yes
parent
Description:
Returns the parent directory of the file or directory at the specified path.
Signature:
func parent(path: Path -> Path)
Parameters:
path: The path of the file or directory.
Returns:
The path of the parent directory.
Example:
>> (./path/to/file.txt):parent()
= (./path/to/)
read
Description:
Reads the contents of the file at the specified path or a null value if the
file could not be read.
Signature:
func read(path: Path -> Text?)
Parameters:
path: The path of the file to read.
Returns:
The contents of the file. If the file could not be read, a null value will be
returned. If the file can be read, but is not valid UTF8 data, an error will be
raised.
Example:
>> (./hello.txt):read()
= "Hello" : Text?
>> (./nosuchfile.xxx):read()
= NULL : Text?
read_bytes
Description:
Reads the contents of the file at the specified path or a null value if the
file could not be read.
Signature:
func read_bytes(path: Path -> [Byte]?)
Parameters:
path: The path of the file to read.
Returns:
The byte contents of the file. If the file cannot be read, a null value will be
returned.
Example:
>> (./hello.txt):read()
= [72[B], 101[B], 108[B], 108[B], 111[B]] : [Byte]?
>> (./nosuchfile.xxx):read()
= NULL : [Byte]?
relative
Description:
Returns the path relative to a given base path. By default, the base path is the current directory.
Signature:
func relative(path: Path, relative_to=(./) -> Path)
Parameters:
path: The path to convert.relative_to(optional): The base path for the relative path (default is./).
Returns:
The relative path.
Example:
>> (./path/to/file.txt):relative(relative_to=(./path))
= (./to/file.txt)
remove
Description:
Removes the file or directory at the specified path. A runtime error is raised if something goes wrong.
Signature:
func remove(path: Path, ignore_missing=no -> Void)
Parameters:
path: The path to remove.ignore_missing(optional): Whether to ignore errors if the file or directory does not exist (default isno).
Returns:
Nothing.
Example:
(./file.txt):remove()
resolved
Description:
Resolves the absolute path of the given path relative to a base path. By default, the base path is the current directory.
Signature:
func resolved(path: Path, relative_to=(./) -> Path)
Parameters:
path: The path to resolve.relative_to(optional): The base path for resolution (default is./).
Returns:
The resolved absolute path.
Example:
>> (~/foo):resolved()
= (/home/user/foo)
>> (./path/to/file.txt):resolved(relative_to=(/foo))
= (/foo/path/to/file.txt)
subdirectories
Description:
Returns a list of subdirectories within the directory at the specified path. Optionally includes hidden subdirectories.
Signature:
func subdirectories(path: Path, include_hidden=no -> [Path])
Parameters:
path: The path of the directory.include_hidden(optional): Whether to include hidden subdirectories (default isno).
Returns:
A list of subdirectory paths.
Example:
>> (./directory):subdirectories()
= [(./directory/subdir1), (./directory/subdir2)]
>> (./directory):subdirectories(include_hidden=yes)
= [(./directory/.git), (./directory/subdir1), (./directory/subdir2)]
unique_directory
Description:
Generates a unique directory path based on the given path. Useful for creating temporary directories.
Signature:
func unique_directory(path: Path -> Path)
Parameters:
path: The base path for generating the unique directory. The last six letters of this path must beXXXXXX.
Returns:
A unique directory path after creating the directory.
Example:
>> created := (/tmp/my-dir.XXXXXX):unique_directory()
= (/tmp/my-dir-AwoxbM/)
>> created:is_directory()
= yes
created:remove()
write
Description:
Writes the given text to the file at the specified path, creating the file if
it doesn't already exist. Sets the file permissions as specified. If the file
writing cannot be successfully completed, a runtime error is raised.
Signature:
func write(path: Path, text: Text, permissions=0o644[32] -> Void)
Parameters:
path: The path of the file to write to.text: The text to write to the file.permissions(optional): The permissions to set on the file if it is created (default is0o644).
Returns:
Nothing.
Example:
(./file.txt):write("Hello, world!")
write_bytes
Description:
Writes the given bytes to the file at the specified path, creating the file if
it doesn't already exist. Sets the file permissions as specified. If the file
writing cannot be successfully completed, a runtime error is raised.
Signature:
func write(path: Path, bytes: [Byte], permissions=0o644[32] -> Void)
Parameters:
path: The path of the file to write to.bytes: An array of bytes to write to the file.permissions(optional): The permissions to set on the file if it is created (default is0o644).
Returns:
Nothing.
Example:
(./file.txt):write_bytes([104[B], 105[B]])
write_unique
Description:
Writes the given text to a unique file path based on the specified path. The
file is created if it doesn't exist. This is useful for creating temporary
files.
Signature:
func write_unique(path: Path, text: Text -> Path)
Parameters:
path: The base path for generating the unique file. This path must include the stringXXXXXXin the file base name.text: The text to write to the file.
Returns:
The path of the newly created unique file.
Example:
>> created := (./file-XXXXXX.txt):write_unique("Hello, world!")
= (./file-27QHtq.txt)
>> created:read()
= "Hello, world!"
created:remove()
write_unique_bytes
Description:
Writes the given bytes to a unique file path based on the specified path. The
file is created if it doesn't exist. This is useful for creating temporary
files.
Signature:
func write_unique_bytes(path: Path, bytes: [Byte] -> Path)
Parameters:
path: The base path for generating the unique file. This path must include the stringXXXXXXin the file base name.bytes: The bytes to write to the file.
Returns:
The path of the newly created unique file.
Example:
>> created := (./file-XXXXXX.txt):write_unique_bytes([1[B], 2[B], 3[B]])
= (./file-27QHtq.txt)
>> created:read()
= [1[B], 2[B], 3[B]]
created:remove()