Functions

The zip sources these before your code. Names start with a dot. Bash and zsh ship the same names.

Do not call .tmpdir, .tmpfile, .on_exit, or .lock from a substitution. An EXIT trap of your own replaces the one these helpers use. Call .cleanup from that trap if the paths should still be removed.

The readme in the zip lists these too. This page does not paste the function file.

Stop and continue

Name	What it does
`.die`	Prints its arguments to stderr and exits 1.
`.warn`	Prints its arguments to stderr and continues.
`.need`	Exits 1 when a command is missing and names that command.
`.have`	Returns 0 when a command exists and 1 when it does not.
`.need_file`	Exits 1 when the path is not a file and names that path.
`.need_dir`	Exits 1 when the path is not a directory and names that path.
`.strict`	Stops on the first failed command, including a pipeline, and on an unset variable.
`.quiet`	Runs a command with no output and returns its status.
`.retry`	Runs a command until it returns 0, at most N times. N must be a positive whole number.
`.confirm`	Reads a line and returns 0 for y or yes.
`.quote`	Prints one word quoted for the shell.
`.log`	Writes a log line. The first argument is the level. --verbose raises the level.

Temporary paths

Name	What it does
`.tmpdir`	Creates a directory, stores the path in the name you pass, and removes it when the script exits.
`.tmpfile`	Does the same for a file.
`.on_exit`	Runs its command when the script exits.
`.cleanup`	Removes those paths now.
`.lock`	Creates a directory and removes it when the script exits. A second call prints locked: and returns 1.

Text

Name	What it does
`.trim`	Prints the string without leading or trailing whitespace.
`.blank`	Returns 0 when the trimmed string is empty.
`.lower`	Lowercases ASCII letters.
`.upper`	Uppercases ASCII letters.
`.len`	Prints the length.
`.contains`	Returns 0 when the string contains the text.
`.prefix`	Returns 0 when the string starts with the text.
`.suffix`	Returns 0 when the string ends with the text.
`.strip_prefix`	Removes a matching prefix and returns 1 when it is absent.
`.strip_suffix`	Removes a matching suffix and returns 1 when it is absent.
`.replace`	Replaces every copy of a literal string. An empty search string returns 1.
`.join`	Prints the later arguments separated by the first argument.
`.repeat`	Prints the string a given number of times and returns 1 when that count is not a whole number.
`.contains_word`	Matches one word separated by whitespace.
`.matches`	Compares a string to a glob.

Lines

Name	What it does
`.foreach`	Runs a command once per line and passes the line as the last argument. The line is not split on spaces.
`.count_lines`	Prints the line count.
`.first_line`	Prints the first line and returns 1 when the file is empty.
`.last_line`	Prints the last line and returns 1 when the file is empty.
`.indent`	Prefixes each line with the number of spaces you pass.
`.unique_lines`	Prints the first copy of each line.
`.sort_lines`	Prints the lines in byte order. A missing file returns 1.

Paths

Name	What it does
`.abspath`	Prints the physical path. An empty argument returns 1.
`.ensure_dir`	Creates a directory and prints that path. It returns 1 when the path is a file.
`.exists`	Returns 0 for a file, a directory, or a symlink.
`.readable`	Returns 0 when the path is readable.
`.writable`	Returns 0 when the path is writable.
`.backup`	Copies a file to a sibling whose name ends in .bak. The next copy uses .bak.1.
`.extension`	Prints the suffix after the last dot. A name with no suffix prints an empty line.
`.stripext`	Removes that suffix and keeps the directory.
`.empty_dir`	Returns 0 when the directory has no entries and 1 when it is missing or not empty.
`.is_file`	Returns 0 or 1 and does not exit. It follows a symlink.
`.is_dir`	Returns 0 or 1 and does not exit.
`.is_link`	Returns 0 or 1 and does not exit. It does not follow the symlink.
`.is_exec`	Returns 0 or 1 and does not exit.
`.basename`	Prints the last path part. A name that starts with a dash stays a name.
`.dirname`	Prints the directory part. An empty argument returns 1.
`.list_dir`	Prints one entry name per line, including names that start with a dot.
`.same`	Returns 0 when two files have the same bytes.
`.filesize`	Prints the byte count.
`.sha256`	Prints the checksum and nothing else.

Numbers and URLs

Name	What it does
`.is_int`	Returns 0 for a whole number. A leading plus or minus is allowed.
`.least`	Prints the smaller of two whole numbers.
`.greatest`	Prints the larger of two whole numbers.
`.clamp`	Keeps a number inside a low and high bound. A reversed bound returns 1.
`.urlencode`	Percent-encodes every character except letters, digits, period, tilde, underscore, and hyphen.
`.urldecode`	Turns a percent-encoded pair back into a character. A bad pair stays as text.