A dmenu calendar.

git clone git://watertao.xyz/programs/calcurse_dmenu.git

README (5730B)

calcurse_dmenu

dmenu ui for calcurse calendar program

Usage

$ sh calcurse_dmenu.sh

WARNING - this program reads and writes to calcurse data files. If calcurse is installed, as a safety precaution please backup data files first before running this program.

Description

A dmenu calendar.

Reads and writes to calcurse data files and as such is fully compatible with calcurse (Note WARNING above). calcurse is not required to run a fully functioning calcurse_dmenu.

The view and selection of calendar, todo, history, and alarm entries is a 100% dmenu experience. All entry functions are engaged by tagging the entry. By edit tagging an entry, the date, recurrance and description of the entry becomes editable in a dmenu interface. Tagging the entry for note editing employs the $EDITOR of your choice (see config.sh). A more complete view of entries is displayed by a pager of your choice (see config.sh).

This is purely a dmenu/pager/editor experience. Not a single graphical representation of a calendar to be found. That’s for the sake of efficiency. The entire goal of this is for speed of service and use. It provides a very fast access to your calcurse calendar and an equally swift interaction. If calcurse is installed, typing ‘calcurse’ into the dmenu prompt launches calcurse for the graphical experience.

Add entry syntax

date #recurrance :: description

date (optional)

The date is any human readable date string parsed by linux’s coreutils ‘date’ user command. See your date(1) man page for details.

Note: For bsd/et al installs, you’ll need to edit the entry_add.awk file to meet your needs. The easiest is to rewrite this using awk’s builtin date functions, which will likely lead to stricter date entry when adding new calcurse_dmenu entries.

The date may be a range, which is determined by a dash between two dates. If times are specified, entries are stored as calcurse apts, otherwise calendar entries are stored as calcurse events. See Examples below.

recurrance (optional)

A recurring entry is determined by deploying the ‘#’ symbol after the date. A regex representation of the recurrance syntax is:

#[0-9]+[dmyDMY] (end date)?

In other words, pound symbol, following by lapse before next recurrance, followed by type of time lapse - day, week, month, or year, followed by the optional end date. Without the optional end date the recurrance is infinite; birthdays for example. See Examples below.

description

Description is the only required information to create a basic event entry. Without a date, the entry date is set for ‘now’ or rather today. Description can be almost anything, so long as it does not match the pattern of a note marker in the data files. So the following regex representation is not allowed in the description:

>[a-f0-9]{40}

Example:

>123456789a123456789b123456789c123456789d

Also wise to refrain from using ‘::’ in description.

Tag Commands

Tag commands are tags, set by default and configurable in config.sh. They comprise currently five functions:

The entry edit, remove and note tags work by tagging an entry’s entire line. So for the following entry:

Mon 29 > Work week begins {1W} <4

The following returned selection initiates editing the entry in dmenu:

Mon 29 > Work week begins {1W} <4:e

And to open an $EDITOR for entry note creation/editing:

Mon 29 > Work week begins {1W} <4:n

And to remove/delete the entry:

Mon 29 > Work week begins {1W} <4:r

For todo, history, and alarm entries, simply return the tag in dmenu’s prompt. eg:

:h

About Calendar Entry Types

Calcurse specifies two types of calendar entries.

  1. Apts - time specificion, one or more days.
  2. Events - no time specification, one day.

Calcurse compliance dictates that if an event is to span more than one day, it must be recurred. So sticking to calcurse compliancy, a multi- day event would be enterred using recurrance in calcurse_dmenu by:

today #3d :: Some three day event

If a calendar entry begins with a specified time, it is considered an appointment (apt) and can last as many days as your system can handle. To set an apt in calcurse_dmenu, it could be as simple as:

7:00 :: wake up

Or something spanning several days:

7:00 - 5 days 17:00 :: 5 day retreat

Or the same retreat that recurs every year:

7:00 - 5 days 17:00 #1y :: 5 day retreat

Alarm

Alarms are currently under development. The program is equiped to edit alarm entries (not a calcurse function by the way). The alarm implementation will be a stand alone process outside of calcurse_dmenu. It is safe to expect a functioning example of this in the future with documentation.

Requirements

Todo

Examples

10 min :: Doing something in ten minutes from now

thu 9:0 - 17:0 :: work on this thursday from 9a to 5p

jan 12 #1y :: Important person's birthday

sun #1w 10 years :: Day of rest, every Sunday, for ten years!

5:00 #1d jun 12 2042 :: Wake up every day at 5am until 07/12/42

Note on time: normally using the date command, you can specify time using am and pm, however due to calcurse_dmenu parsing of this line, the program looks for full-ish mil times, with a colon and at least a single digit on both sides of that colon. So specifying 5am time looks like: 5:0 or 5:00.