Utilities

The utility functions available at src/utility.sh provide functionality that is very simple and sometimes generally used across the whole application.

log

log <level> <message>

The log function takes a log level between 1 and 5 as its first argument and a message as its second argument. The log message must be wrapped in double quotes, otherwise only the first word will be considered part of the message and the rest will be discarded.

If the environment variable DEBUG is set to a number corresponding to the provided log level or greater, the message is printed.

The current log levels are:

0. user: Always displays, with [tori] at the very left followed by a second-precision timestamp, a colon and the message. This is meant for user messages that are always relevant. This level is not affected by the value of the DEBUG environment variable
1. fatal: For critical, unrecoverable or unsupported situations. The application must immediately exit after printing the message. Displays when the log level is 1 or higher with a second-precision timestamp.
2. error: For unexpected conditions where potential undesired behavior, loss of user data or other unintended state may happen or has already happened. The application may exit immediately after printing the message. Displays when the log level is 2 or higher with a second-precision timestamp.
3. warn: For expected conditions already handled by the application that may potentially be unintended behavior, depending on the user’s intentions. A warning should not precede the application exiting. Displays when the log level is 3 or higher with a second-precision timestamp. This is the default when DEBUG is not set or is set to a non-numerical value.
4. info: For messages that do not represent errors or unintended situations, but provide more insight into the current state or behavior. This level is for development purposes. Displays when the log level is 4 or higher with a nanosecond-precision timestamp.
5. debug For messages that express any change in state or behavior, typically to help understand the application’s flow of execution. This level is for development purposes. Displays when the log level is 5 or higher with a nanosecond-precision timestamp. Levels higher than 5 are not valid, but are brought down to 5.

The log level defaults to 3 (warn). To completely disable log messages (except for the user level), set DEBUG=0.

If DEBUG is set to a value greater than 5, it will be reset to 5. If it is set to any non-numerical value, it will be set to the default, 3.

All log messages are printed to STDERR so as not to shadow function return values.

set_opts

set_opts <on|off>

The set_opts function checks if the shell options are supported and sets them. If they are not supported, it considers the shell unsupported. This causes it to print a fatal error message and return exit code 1.

This function is called with the on argument in the very early stages after the application just started in order to enable these options for the remainder of execution. It may then be used again to perform operations that require these options to be unset.

For example:

set_opts off # disable options
echo "$potentially_unset_variable" 
set_opts on # re-enable options

It modifies the following options:

• errexit: Exit after any non-zero return¹
• nounset: Exit when trying to expand an unset variable

To enable them, use set_opts on. To disable them, use set_opts off.

print_help

print_help

The print_help function is responsible for printing help text when the user runs tori help, tori -h or tori --help. It takes no arguments.

juno@akuma:~/tori $ tori -h

  tori: configuration managent and system replication tool

    Options:

        check           compare configuration to system state
        cache           refresh the local package cache

        version         print current version with release date
        help            show this help text

  See 'man tori' or https://tori.jutty.dev/docs for more help

The help text contains a brief description of what tori is, what commands are available and where to find more help via the man page or this documentation website.

prepare_directories

prepare_directories

The prepare_directories function runs at the very start of execution in order to verify that critical directories exist. It takes no arguments.

The directories are:

• CONFIG_ROOT, default ~/.config/tori: application exits with a fatal error and exit code 1 if not found
• TMP_ROOT, default /tmp/tori: created if not found
• CACHE_ROOT, default ~/.cache/tori: created if not found
• BACKUP_ROOT, default ~/.local/state/tori/backup: created if not found
  • with subdirectories canonical and ephemeral

ask

ask <prompt> <option>[,option2,option3[, ...]]

The ask function will prompt the user for one choice among the comma-separated list of alternatives.

It will also include an “Exit” option that does not need to be provided in the list of alternatives.

This function will print a number to standard output corresponding to the chosen option starting from 1, and 0 if the “Exit” option is chosen.

tildify

tildify <path>

The tildify function takes a file path and replaces the first occurrence of the user’s home directory with a ~ (tilde) character. The home directory string to replace is determined by reading the value of the presently set $HOME environment variable.