Input and Output Date Format¶

Many options require a date argument, and query results per day are set apart by a leading date line.

The input format of date options and the output format of date lines are taken from the configuration file (see FILES). The formats are set in the "General Options" submenu in interactive mode. Particularly in scripts it may be desirable that formats are independent of the local user configuration. For this purpose use the options --input-datefmt and --output-datefmt.

An input date consists of date, month and year. Here day must be in the range 1-31 and month in 1-12. Depending on the operating system year must be in the range 1902-2037 or 1902-?. Additionally, some short forms are allowed with the obvious meaning: today, tomorrow, yesterday, now and weekdays mon, ..., sun.

Optionally, a date argument for a filter option (see Filter Options) may be followed by a time-of-day specification in hours and minutes (24-hour clock). The specification has the fixed format hh:mm (example: "2018-12-1 20:30" when the input date format is the ISO standard format). Note that the entire date specification must be quoted to create one argument.

Filter, format and day range options¶

These options do not accomplish anything in and of themselves. They influence other options and are in a way opposites: filter options affect the input to, format and day range options the output from calcurse. Specifically, filter options limit what is loaded from the data files into calcurse, day range options limit what is output (see -Q), and format options describe how it is presented.

Filter options have effect on queries (-Q and query short-forms), grep (-G), purge (-P) and export (-x). Format options have effect on queries, grep and --dump-imported. Day range options have effect on queries only.

General filters¶

--filter-type type

--filter-pattern pattern

--filter-hash string

Calendar filters¶

For filter options ending in -from, -to, -after, -before and -range, start or end time is the filter criterion.

An event is an all-day appointment for which no times are displayed. The start time of an event is the beginning of the event day (midnight), the end time is the end of the event day (one second before next midnight).

The -start- options ending in -from, -after and -range refer to the same filter criterion and cannot be used together. The same is the case for options ending in -to, -before and -range. Similar restrictions apply to -end- options.

Start and end times of a recurrent item refer to the very first occurrence, not to those of any of the repetitions. If a recurrent item meets the criterion, all of the repetitions are displayed in queries, even though they may not meet the criterion. If they are unwanted, they may be removed from the output with the day range options, although this will also remove other items in that range.

--filter-start-from date

--filter-start-to date

--filter-start-after date

--filter-start-before date

--filter-start-range range

--filter-end-from date

--filter-end-to date

--filter-end-after date

--filter-end-before date

--filter-end-range range

Todo filters¶

--filter-priority priority

--filter-completed

--filter-uncompleted

Default format strings¶

Each specifier is introduced by a % followed by a character which tells what to print. The available specifiers depend on the item type. Times are printed as hours and minutes (hh:mm) unless otherwise noted; time formats can be changed with extended specifiers.

For each format option there is a default format string which is used when the option is not given. In query results the default format options are:

--format-apt " - %S -> %E\n\t%m\n"
--format-recur-apt " - %S -> %E\n\t%m\n"
--format-event " * %m\n"
--format-recur-event " * %m\n"
--format-todo "%p. %m\n"

In all other cases (grep and dump-imported) the default format string is "%(raw)".

Appointments¶

%d

%e

%E

%m

%n

%N

%r

%s

%S

Events¶

%m

%n

%N

Todo items¶

%m

%n

%N

%p

Extended format specifiers¶

Extended format specifiers can be used to control the printing of times for some of the single-letter specifiers. Additionally there are two specifiers that do not have any corresponding short form and are intended for use in scripting.

%(duration[:format])

%(remaining[:format])

%(start[:format])

%(end[:format])

%(raw)

%(hash)

Data files¶

The calendar file apts contains all of the user’s appointments and events, and the todo file contains the todo list. The notes subdirectory contains the notes which are attached to appointments, events or todos. One text file is created per note, whose name is the SHA1 message digest of the note itself.

The (hidden) lock files of the calcurse (.calcurse.pid) and daemon (.daemon.log) programs are present when they are running. If daemon log activity has been enabled in the notification configuration menu, the file daemon.log is present.

An alternative calendar file may be specified with the -c option.

Configuration files¶

The conf file contains the user configuration and the keys file the user-defined key bindings. The hooks directory contains user-supplied scripts, see Hooks.

Directory configuration¶

An alternative directory for both the configuration files and the data directory may be specified with the -D option.

An alternative directory for the configuration files only may be specified with the -C option; in that case data files are either in the default directory or in the directory specified by -D. If both -D and -C are present, configuration files in the data directory, if any, are ignored.

If $HOME/.calcurse exists, then it will be used as the default for both the data directory and the configuration directory.

<datadir>      <confdir>


     |             |


     |__ apts      |___ conf


     |__ todo      |___ keys


     |__ notes/    |___ hooks/
defaults:


     <datadir>: $XDG_DATA_HOME/calcurse ($HOME/.local/share/calcurse)


     <confdir>: $XDG_CONFIG_HOME/calcurse ($HOME/.config/calcurse)


     both: $HOME/.calcurse (only if it exists)

calcurse may switch between two configuration setups, but still access the same data files e.g. with:

$ calcurse
$ calcurse -C "$HOME/.config/calcurse/config"

Hooks¶

Scripts placed in <confdir>/calcurse/hooks/ (see Directory configuration) trigger actions at certain events. To enable a hook, add a script with one of the following names to this directory. Also make sure the script is executable.

pre-load

post-load

pre-save

post-save

Some examples can be found in the contrib/hooks/ directory of the calcurse source tree.