Bruce/tomo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Activity
38d6189d43
tomo/docs/paths.md

23 KiB
Raw Blame History

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_text(text) if you need to use arbitrary text as a file path.

Path Methods

accessed

Gets the file access time of a file.

func accessed(path:Path, follow_symlinks: Bool = yes -> Moment?)
  • path: The path of the file whose access time you want.
  • follow_symlinks: Whether to follow symbolic links (default is yes).

Returns:
A Moment representing when the file or directory was last accessed, or none if no such file or directory exists.

Example:

>> (./file.txt):accessed()
= Sun 16 Mar 2025 03:43:53 PM EDT EDT : Moment?
>> (./not-a-file):accessed()
= none : Moment?

append

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.

func append(path: Path, text: Text, permissions: Int32 = 0o644[32] -> Void)
  • path: The path of the file to append to.
  • text: The text to append to the file.
  • permissions: The permissions to set on the file if it is being created (default is 0o644).

Returns:
Nothing.

Example:

(./log.txt):append("extra line$(\n)")

append_bytes

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.

func append_bytes(path: Path, bytes: [Byte], permissions: Int32 = 0o644[32] -> Void)
  • path: The path of the file to append to.
  • bytes: The bytes to append to the file.
  • permissions: The permissions to set on the file if it is being created (default is 0o644).

Returns:
Nothing.

Example:

(./log.txt):append_bytes([104[B], 105[B]])

base_name

Returns the base name of the file or directory at the specified path.

func base_name(path: Path -> Text)
  • 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

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.

func by_line(path: Path -> func(->Text?)?)
  • 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())

can_execute

Returns whether or not a file can be executed by the current user/group.

func can_execute(path: Path -> Bool)
  • path: The path of the file to check.

Returns: yes if the file or directory exists and the current user has execute permissions, otherwise no.

Example:

>> (/bin/sh):can_execute()
= yes
>> (/usr/include/stdlib.h):can_execute()
= no
>> (/non/existant/file):can_execute()
= no

can_read

Returns whether or not a file can be read by the current user/group.

func can_read(path: Path -> Bool)
  • path: The path of the file to check.

Returns: yes if the file or directory exists and the current user has read permissions, otherwise no.

Example:

>> (/usr/include/stdlib.h):can_read()
= yes
>> (/etc/shadow):can_read()
= no
>> (/non/existant/file):can_read()
= no

can_write

Returns whether or not a file can be written by the current user/group.

func can_write(path: Path -> Bool)
  • path: The path of the file to check.

Returns: yes if the file or directory exists and the current user has write permissions, otherwise no.

Example:

>> (/tmp):can_write()
= yes
>> (/etc/passwd):can_write()
= no
>> (/non/existant/file):can_write()
= no

changed

Gets the file change time of a file.

Note: this is the "ctime" of a file, which is not the file creation time.

func changed(path:Path, follow_symlinks: Bool = yes -> Moment?)
  • path: The path of the file whose change time you want.
  • follow_symlinks: Whether to follow symbolic links (default is yes).

Returns:
A Moment representing when the file or directory was last changed, or none if no such file or directory exists.

Example:

>> (./file.txt):changed()
= Sun 16 Mar 2025 03:43:53 PM EDT EDT : Moment?
>> (./not-a-file):changed()
= none : Moment?

child

Return a path that is a child of another path.

func child(path: Path, child: Text -> [Path])
  • path: The path of a directory.
  • child: The name of a child file or directory.

Returns:
A new path representing the child.

Example:

>> (./directory):child("file.txt")
= (./directory/file.txt)

children

Returns a list of children (files and directories) within the directory at the specified path. Optionally includes hidden files.

func children(path: Path, include_hidden=no -> [Path])
  • path: The path of the directory.
  • include_hidden: Whether to include hidden files, which start with a . (default is no).

Returns:
A list of paths for the children.

Example:

>> (./directory):children(include_hidden=yes)
= [".git", "foo.txt"]

create_directory

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.

func create_directory(path: Path, permissions=0o755[32] -> Void)
  • path: The path of the directory to create.
  • permissions: The permissions to set on the new directory (default is 0o644).

Returns:
Nothing.

Example:

(./new_directory):create_directory()

exists

Checks if a file or directory exists at the specified path.

func exists(path: Path -> Bool)
  • path: The path to check.

Returns:
True if the file or directory exists, False otherwise.

Example:

>> (/):exists()
= yes

expand_home

For home-based paths (those starting with ~), expand the path to replace the tilde with and absolute path to the user's $HOME directory.

func expand_home(path: Path -> Path)
  • path: The path to expand.

Returns:
If the path does not start with a ~, then return it unmodified. Otherwise, replace the ~ with an absolute path to the user's home directory.

Example:

>> (~/foo):expand_home() # Assume current user is 'user'
= /home/user/foo
>> (/foo):expand_home() # No change
= /foo

extension

Returns the file extension of the file at the specified path. Optionally returns the full extension.

func extension(path: Path, full:Bool = yes -> Text)
  • path: The path of the file.
  • full: Whether to return everything after the first . in the base name, or only the last part of the extension (default is yes).

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

Returns a list of files within the directory at the specified path. Optionally includes hidden files.

func files(path: Path, include_hidden: Bool = no -> [Path])
  • path: The path of the directory.
  • include_hidden: Whether to include hidden files (default is no).

Returns:
A list of file paths.

Example:

>> (./directory):files(include_hidden=yes)
= [(./directory/file1.txt), (./directory/file2.txt)]

from_components

Returns a path built from an array of path components.

func from_components(components: [Text] -> Path)
  • components: An array of path components.

Returns:
A path representing the given components.

Example:

>> Path.from_components(["/", "usr", "include"])
= /usr/include
>> Path.from_components(["foo.txt"])
= ./foo.txt
>> Path.from_components(["~", ".local"])
= ~/.local

glob

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.
func glob(path: Path -> [Path])
  • 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()
= []

group

Get the owning group of a file or directory.

func group(path: Path, follow_symlinks: Bool = yes -> Text?)
  • path: The path whose owning group to get.
  • follow_symlinks: Whether to follow symbolic links (default is yes).

Returns:
The name of the group which owns the file or directory, or none if the path does not exist.

Example:

>> (/bin):group()
= "root"
>> (/non/existent/file):group()
= none:Text

is_directory

Checks if the path represents a directory. Optionally follows symbolic links.

func is_directory(path: Path, follow_symlinks=yes -> Bool)
  • path: The path to check.
  • follow_symlinks: Whether to follow symbolic links (default is yes).

Returns:
True if the path is a directory, False otherwise.

Example:

>> (./directory/):is_directory()
= yes

>> (./file.txt):is_directory()
= no

is_file

Checks if the path represents a file. Optionally follows symbolic links.

func is_file(path: Path, follow_symlinks=yes -> Bool)
  • path: The path to check.
  • follow_symlinks: Whether to follow symbolic links (default is yes).

Returns:
True if the path is a file, False otherwise.

Example:

>> (./file.txt):is_file()
= yes

>> (./directory/):is_file()
= no

is_socket

Checks if the path represents a socket. Optionally follows symbolic links.

func is_socket(path: Path, follow_symlinks=yes -> Bool)
  • path: The path to check.
  • follow_symlinks: Whether to follow symbolic links (default is yes).

Returns:
True if the path is a socket, False otherwise.

Example:

>> (./socket):is_socket()
= yes

is_symlink

Checks if the path represents a symbolic link.

func is_symlink(path: Path -> Bool)
  • path: The path to check.

Returns:
True if the path is a symbolic link, False otherwise.

Example:

>> (./link):is_symlink()
= yes

modified

Gets the file modification time of a file.

func modified(path:Path, follow_symlinks: Bool = yes -> Moment?)
  • path: The path of the file whose modification time you want.
  • follow_symlinks: Whether to follow symbolic links (default is yes).

Returns:
A Moment representing when the file or directory was last modified, or none if no such file or directory exists.

Example:

>> (./file.txt):modified()
= Sun 16 Mar 2025 03:43:53 PM EDT EDT : Moment?
>> (./not-a-file):modified()
= none : Moment?

owner

Get the owning user of a file or directory.

func owner(path: Path, follow_symlinks: Bool = yes -> Text?)
  • path: The path whose owner to get.
  • follow_symlinks: Whether to follow symbolic links (default is yes).

Returns:
The name of the user who owns the file or directory, or none if the path does not exist.

Example:

>> (/bin):owner()
= "root"
>> (/non/existent/file):owner()
= none:Text

parent

Returns the parent directory of the file or directory at the specified path.

func parent(path: Path -> Path)
  • path: The path of the file or directory.

Returns:
The path of the parent directory.

Example:

>> (./path/to/file.txt):parent()
= (./path/to/)

read

Reads the contents of the file at the specified path or a null value if the file could not be read.

func read(path: Path -> Text?)
  • 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()
= none : Text?

read_bytes

Reads the contents of the file at the specified path or a null value if the file could not be read.

func read_bytes(path: Path -> [Byte]?)
  • 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()
= none : [Byte]?

relative_to

Returns the path relative to a given base path. By default, the base path is the current directory.

func relative_to(path: Path, relative_to=(./) -> Path)
  • path: The path to convert.
  • relative_to: 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

Removes the file or directory at the specified path. A runtime error is raised if something goes wrong.

func remove(path: Path, ignore_missing=no -> Void)
  • path: The path to remove.
  • ignore_missing: Whether to ignore errors if the file or directory does not exist (default is no).

Returns:
Nothing.

Example:

(./file.txt):remove()

resolved

Resolves the absolute path of the given path relative to a base path. By default, the base path is the current directory.

func resolved(path: Path, relative_to=(./) -> Path)
  • path: The path to resolve.
  • relative_to: 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)

set_owner

Set the owning user and/or group for a path.

func set_owner(path:Path, owner: Text? = none:Text, group: Text? = none:Text, follow_symlinks: Bool = yes)
  • path: The path to change the permissions for.
  • owner: If non-none, the new user to assign to be the owner of the file (default: none).
  • group: If non-none, the new group to assign to be the owner of the file (default: none).
  • follow_symlinks: Whether to follow symbolic links (default is yes).

Returns:
Nothing. If a path does not exist, a failure will be raised.

Example:

(./file.txt):set_owner(owner="root", group="wheel")

subdirectories

Returns a list of subdirectories within the directory at the specified path. Optionally includes hidden subdirectories.

func subdirectories(path: Path, include_hidden=no -> [Path])
  • path: The path of the directory.
  • include_hidden: Whether to include hidden subdirectories (default is no).

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

Generates a unique directory path based on the given path. Useful for creating temporary directories.

func unique_directory(path: Path -> Path)
  • path: The base path for generating the unique directory. The last six letters of this path must be XXXXXX.

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

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.

func write(path: Path, text: Text, permissions=0o644[32] -> Void)
  • path: The path of the file to write to.
  • text: The text to write to the file.
  • permissions: The permissions to set on the file if it is created (default is 0o644).

Returns:
Nothing.

Example:

(./file.txt):write("Hello, world!")

write_bytes

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.

func write(path: Path, bytes: [Byte], permissions=0o644[32] -> Void)
  • path: The path of the file to write to.
  • bytes: An array of bytes to write to the file.
  • permissions: The permissions to set on the file if it is created (default is 0o644).

Returns:
Nothing.

Example:

(./file.txt):write_bytes([104[B], 105[B]])

write_unique

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.

func write_unique(path: Path, text: Text -> Path)
  • path: The base path for generating the unique file. This path must include the string XXXXXX in 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

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.

func write_unique_bytes(path: Path, bytes: [Byte] -> Path)
  • path: The base path for generating the unique file. This path must include the string XXXXXX in 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()