uair(5)

NAME

uair - configuration file

DESCRIPTION

The number of pomodoro sessions and their properties can be specified by an uair configuration file in TOML format. A config file consists of the following keys:

loop_on_end
    This is a boolean value (true or false) which controls whether uair repeats all sessions after the completion of the last session.

iterations
    This is a non-negative integer which specifies the number of times sessions mentioned in the sessions array are iterated.

pause_at_start
    This is a boolean value (true or false) which controls whether uair is at paused state at startup.

startup_text
    It specifies the text to be printed at startup. (Deprecated)

defaults
    This is a table containing default session properties. If a session has a property unspecified, the value of the corresponding key in this table is used instead. Specifying a default id is not allowed.

sessions
    This is an array of tables. Each table in this array corresponds to a session. The order of sessions in this array is the order in which they are scheduled. Each table in this array consists of keys which describe the properties of the session, which are discussed in the following section.

SESSION PROPERTIES

id
    Unique identifier of the session. If unspecified, it is automatically set to the zero-indexed position of the session in the sessions array.

name
    Name of the session.

duration
    Duration of the session. Can be specified in human readable format. e.g.: "1h 47m"

command
    Command which is run when the session finishes. See COMMAND ENVIRONMENT section for information on environment variables which are passed to the command.

format
    Specifies the format in which text is printed each second. See FORMAT SPECIFIERS section for details.

time_format
    Specifies the format in which {time} format specifier prints time. See TIME FORMAT SPECIFIERS section for details.

autostart
    Boolean value (true or false) which dictates whether the session automatically starts.

paused_state_text
    Text which is displayed by the {state} format specifier when the timer is paused.

resumed_state_text
    Text which is displayed by the {state} format specifier when the timer is resumed.

overrides
    A table consisting of OVERRIDABLES as values and their names as keys. It allows to specify named overrides to be applied during `uairctl listen` See OVERRIDABLES section for more information and for the list of overridable properties.

FORMAT SPECIFIERS

The format property of a session is a string which specifies what and how text is printed every second. For example, the following format string can be used to print the name of the session followed by the remaining time, followed by the total duration of the session, all in cyan color.

    {cyan}{name}: {time} / {total}{end}

The list of format specifiers is:

{name}
    Session name

{percent}
    Percentage of time remaining

{time}
    Remaining time for session

{state}
    Text which depends on the state (paused/resumed) of the timer. This text is configurable through paused_state_text and resumed_state_text session properties.

{total}
    Total duration of session

{black}
    Start black color text

{red}
    Start red color text

{green}
    Start green color text

{yellow}
    Start yellow color text

{blue}
    Start blue color text

{purple}
    Start purple color text

{cyan}
    Start cyan color text

{white}
    Start white color text

{end}
    Start end color text

TIME FORMAT SPECIFIERS

The time_format property of a session is a string which specifies what and how text produced by {time} format specifier is printed. Time format specifiers have the following syntax.

    %[optional skip flag][optional padding flag]alphabet

As an example, the following time format string can be used to print time in a digital clock-like format.

    %H:%M:%S

The list of interpreted sequences is:

%Y
    Remaining years

%B
    Remaining months in a year

%D
    Remaining days in a month

%H
    Remaining hours in a day

%M
    Remaining minutes in an hour

%S
    Remaining seconds in a minute

%P
    Prints 's' if the quantity specified by the format specifier before it is plural and nothing if singular.

The list of optional padding flags is:

0
    Pad with zeroes (default)

_
    Pad with spaces

-
    Do not pad

An optional '*' flag may follow '%' to skip the quantity specified by the format specifier and skip all text before the next quantifiable format specifier.

OVERRIDABLES

Each value in the 'overrides' session property is a table named OVERRIDABLES which can contain one or more of the following properties.

format
    Specifies the format in which text is printed each second. See FORMAT SPECIFIERS section for details.

time_format
    Specifies the format in which {time} format specifier prints time. See TIME FORMAT SPECIFIERS section for details.

paused_state_text
    Text which is displayed by the {state} format specifier when the timer is paused.

resumed_state_text
    Text which is displayed by the {state} format specifier when the timer is resumed.

COMMAND ENVIRONMENT

Some environment variables are passed to the command specified by the command property of a session which enables printing various session properties. They are as follows

$name
    name property of session

$duration
    duration property of session

SEE ALSO

uair(1) uairctl(1)