Pomocom

A simple, fast, and configurable pomodoro timer with multiple interfaces

Interfaces

ANSI

This interface is displayed with ANSI terminal escape codes. It is the most lightweight interface, but it lacks several features, including:

• colors
• pausing
• skipping sections

ncurses

This interface is displayed with the POSIX library ncurses. It is fully featured!

wxWidgets

This interface is displayed with the cross-platform GUI library wxWidgets. It’s in early development and doesn’t support all pomocom settings yet.

Building & Installation

pomocom has the following dependencies:

• C++20
• libncursesw v6.3+ (optional)
• wxWidgets v3.2+ (optional)

pomocom can be compiled using the Makefile by running make in the project’s root directory. To customize the compilation process, you may edit config.mk.

To install, run make install. This will copy the config directory in the project’s root directory to ~/.config/pomocom on POSIX systems.

To install just the pomocom binary and leave config directories untouched, run make installbin.

To uninstall, run make uninstall. This will remove the config directory at ~/.config/pomocom.

Configuration

pomocom is configured with files found in ~/.config/pomocom. In there, pomocom.conf contains program settings values, and pomo files (ending in .pomo) contain timing section information.

pomocom.conf

pomocom.conf is written in the following format:

setting_name_1 setting_value_1
setting_name_2 setting_value_2
setting_name_3 setting_value_3
...

Settings come in two distinct types: strings and numbers.

String settings can hold strings with spaces in them, but these spaces must come after the space character after the setting name.

Number settings can be split into multiple subtypes with different byte sizes: bool (1 byte), char (1 byte), int (1 byte), short (2 bytes), and long (8 bytes). These settings can also be set to string values that pomocom converts into numbers using an internal table of keywords (ex. you can set the setting interface to ncurses because ncurses is defined as a keyword that translates to the number 1). See the end of this section for a table of all keywords.

Here is an example pomocom.conf file:

interface ncurses
update_interval 1
pause_before_section_start true
breaks_until_long_reset 2
key.quit q
key.pause j
key.section_begin j
key.section_skip k
ncurses.color.pomocom.fg blue
ncurses.color.pomocom.bg default
ncurses.color.section_work.fg yellow
ncurses.color.section_work.bg default
ncurses.color.section_break.fg green
ncurses.color.section_break.bg default
ncurses.color.time.fg default
ncurses.color.time.bg default

You may also configure settings using command line arguments that follow the format --setting_name=setting_value. Settings specified in this way are set after pomocom.conf is read.

Here is a table of all settings:

Name	Type	Default Value	Description
interface	int	ncurses	The type of interface pomocom will present
update_interval	long	1	The # of seconds to wait between screen updates
pause_before_section_start	bool	false	If true, makes pomocom pause before a section starts
set_terminal_title	bool	true	If true, sets the terminal title to “pomocom - (pomo file name)” on startup
set_terminal_title_countdown	bool	true	If true, sets the terminal title to a countdown (runs every screen update)
breaks_until_long_break	int	2	Controls how many break sections must pass before a long break occurs
key.quit	char	q	Key to quit pomocom
key.pause	char	j	Key to pause and unpause
key.section_begin	char	j	Key to begin the section
key.section_skip	char	k	Key to skip to the next section
path.config	string	~/.config/pomocom/	Path (ending with /) to the directory where pomocom.conf resides
path.section	string	~/.config/pomocom/	Path (ending with /) to the directory where pomo files reside
path.bin	string	~/.config/pomocom/	Path (ending with /) to the directory where executable scripts reside
ncurses.color.pomocom.fg	short	blue	Foreground color for the first line of text in the ncurses interface
ncurses.color.pomocom.bg	short	default	Background color for the first line of text in the ncurses interface
ncurses.color.section_work.fg	short	yellow	Foreground color for the work section name
ncurses.color.section_work.bg	short	default	Background color for the work section name
ncurses.color.section_break.fg	short	green	Foreground color for the break section names
ncurses.color.section_break.bg	short	default	Background color for the break section names
ncurses.color.time.fg	short	default	Foreground color for the time remaining in a section
ncurses.color.time.bg	short	default	Background color for the time remaining in a section

Below is a table of all keywords. You can also see the initializers for keywords in src/settings.cc.

Keyword	Intended For	Value in Source Code	Literal Value
true	booleans	1	1
false	booleans	0	0
ansi	interface	INTERFACE_ANSI	0
ncurses	interface	INTERFACE_NCURSES	1
wx	interface	INTERFACE_WX	2
default	ncurses colors	-1	-1
black	ncurses colors	COLOR_BLACK	?
red	ncurses colors	COLOR_RED	?
green	ncurses colors	COLOR_GREEN	?
yellow	ncurses colors	COLOR_YELLOW	?
blue	ncurses colors	COLOR_BLUE	?
magenta	ncurses colors	COLOR_MAGENTA	?
cyan	ncurses colors	COLOR_CYAN	?
white	ncurses colors	COLOR_WHITE	?

Pomo Files

Pomo files are written in the following format:

(name of work section)
(optional +)(command to run when the section is over)
(section duration in minutes)m(section duration in seconds)s

(name of break section)
(optional +)(command to run when the section is over)
(section duration in minutes)m(section duration in seconds)s

(name of long break section)
(optional +)(command to run when the section is over)
(section duration in minutes)m(section duration in seconds)s

If the section command is prefixed with +, the command will be prefixed with the path contained in the setting paths.bin (set by default to ~/.config/pomocom/). This is used so that you can easily execute files in a directory meant for pomocom scripts without needing to add this directory to your $PATH.

Here is an example pomo file:

work time
+msg.sh snare "work time"
25m0s

break time
+msg.sh square "break time"
5m0s

long break time
+msg.sh square "break time"
15m0s

Usage

Command Line Arguments

Picking the Pomo File to Read on Startup

Any argument that doesn’t start with - is interpreted as the pomo file to read. The path of this file will be the said argument prefixed with the setting paths.section (set by default to ~/.config/pomocom/) and suffixed with .pomo. If this argument starts with ./, the pomo file will be searched for relative to the working directory.

When pomocom is run with no specified pomo file, the pomo file standard.pomo in the program’s config directory is read.

Short Arguments

-b

This will start the pomodoro timer on a short break section.

-B

This will start the pomodoro timer on a long break section.

-q (minutes of work section ) (minutes of break section) (minutes of long break section)

This stands for quick pomo file setup. It will make pomocom read the default pomo file and overwrite the lengths of each section with those specified.

Long Arguments (Settings)

To change settings, pass an argument starting with -- and ending with the setting name. The next argument should be the value of the setting.

Settings specified in this way will override the settings in pomocom.conf.

Examples

This will open the pomo file work.pomo in the directory contained in the setting paths.section and set the setting interface to wx, regardless of what interface is set as in pomocom.conf.

pomocom work --interface wx

This will open the pomo file abc.pomo in the working directory that the command is run from.

pomocom ./abc

Default Controls

These are not available in the ANSI interface.

j

Begin the timing section, pause, and unpause

k

Skip the section

q

Quit