12 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.from_unsafe_text(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.
Usage:
append(path: Path, text: Text, permissions: Int32 = 0o644_i32) -> 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)")
base_name
Description:
Returns the base name of the file or directory at the specified path.
Usage:
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.
Usage:
by_line(path: Path) -> func()->NextLine
Parameters:
path: The path of the file.
Returns:
An iterator that can be used to get lines from a file one at a time.
Example:
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.
Usage:
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.
Usage:
create_directory(path: Path, permissions=0o644_i32) -> 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.
Usage:
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.
Usage:
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.
Usage:
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)]
is_directory
Description:
Checks if the path represents a directory. Optionally follows symbolic links.
Usage:
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.
Usage:
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.
Usage:
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.
Usage:
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.
Usage:
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.
Usage:
read(path: Path) -> Text
Parameters:
path: The path of the file to read.
Returns:
The contents of the file. If the file does not exist, an error will be raised.
Example:
content := (./file.txt):read()
relative
Description:
Returns the path relative to a given base path. By default, the base path is the current directory.
Usage:
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.
Usage:
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.
Usage:
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.
Usage:
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.
Usage:
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.
Usage:
write(path: Path, text: Text, permissions=0o644_i32) -> 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_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.
Usage:
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()