Skip to content

lukelawlor/pomocom

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

43 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Pomocom

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

./doc/ncurses_large.png

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:

NameTypeDefault ValueDescription
interfaceintncursesThe type of interface pomocom will present
update_intervallong1The # of seconds to wait between screen updates
pause_before_section_startboolfalseIf true, makes pomocom pause before a section starts
set_terminal_titlebooltrueIf true, sets the terminal title to “pomocom - (pomo file name)” on startup
set_terminal_title_countdownbooltrueIf true, sets the terminal title to a countdown (runs every screen update)
breaks_until_long_breakint2Controls how many break sections must pass before a long break occurs
key.quitcharqKey to quit pomocom
key.pausecharjKey to pause and unpause
key.section_begincharjKey to begin the section
key.section_skipcharkKey to skip to the next section
path.configstring~/.config/pomocom/Path (ending with /) to the directory where pomocom.conf resides
path.sectionstring~/.config/pomocom/Path (ending with /) to the directory where pomo files reside
path.binstring~/.config/pomocom/Path (ending with /) to the directory where executable scripts reside
ncurses.color.pomocom.fgshortblueForeground color for the first line of text in the ncurses interface
ncurses.color.pomocom.bgshortdefaultBackground color for the first line of text in the ncurses interface
ncurses.color.section_work.fgshortyellowForeground color for the work section name
ncurses.color.section_work.bgshortdefaultBackground color for the work section name
ncurses.color.section_break.fgshortgreenForeground color for the break section names
ncurses.color.section_break.bgshortdefaultBackground color for the break section names
ncurses.color.time.fgshortdefaultForeground color for the time remaining in a section
ncurses.color.time.bgshortdefaultBackground 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.

KeywordIntended ForValue in Source CodeLiteral Value
truebooleans11
falsebooleans00
ansiinterfaceINTERFACE_ANSI0
ncursesinterfaceINTERFACE_NCURSES1
wxinterfaceINTERFACE_WX2
defaultncurses colors-1-1
blackncurses colorsCOLOR_BLACK?
redncurses colorsCOLOR_RED?
greenncurses colorsCOLOR_GREEN?
yellowncurses colorsCOLOR_YELLOW?
bluencurses colorsCOLOR_BLUE?
magentancurses colorsCOLOR_MAGENTA?
cyanncurses colorsCOLOR_CYAN?
whitencurses colorsCOLOR_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