clcal

command-line calendar

usage

clcal was designed to be run from your shell startup file such as (if you use bash) ~/.bashrc, but how you use it is up to you.

If you only wish to be reminded once of your appointments, and not each time you open a new term (I tend to open lots), then put a pre-requisite check in before you run clcal, e.g.

# check for number of terms, run clcal if only one term is open
# (Eterm is used in this example)
if [ `ps -ef | grep Eterm | grep $LOGNAME | grep -v grep | wc -l | awk '{ print $1 }'` = 1 ]
   then
      ~/bin/clcal -w
fi
# end check

~/.calendar/year/month/date

This directory structure is absolutely required if you wish to make any use of clcal. Note the following formats:

~	refers to your home directory
.calendar	a directory
year	this directory represents the year in four-digit format, e.g. 2004
month	this directory represents the month in two-digit format, e.g. 05
date	this file represents the date in two-digit format, e.g. 09

The date file contains the appointment/event information you wish to display. Just create and edit this file using your preferred editor. You are limited to 61 characters per line (if you want the output to look good). Note that tabs may not be accurately echoed to the screen, so use spaces as a preference.

~/.clcal/colour.cfg

The colour.cfg file is optional. Copy the sample from the source directory to the location listed if you wish to colour your output. Edit the file to suit your requirements. By default (i.e if you don't have a colour.cfg file), certain parts of the output are printed in bold.

clcal command line options

-h --help	Prints the help page.
-v --version	Prints version information.
-d # --day #	Prints your calendar entries for # number of days, or one day (today) if no number is specified. If you specify a negative number (e.g. `-10`), then clcal will print the appropriate entries for the 10 days prior to today.
-w # --week #	Prints your calendar entries for # number of weeks (etc).
-m # --month #	Prints your calendar entries for # number of months (etc).
-y # --year #	Prints your calendar entries for # number of years (etc).
	The period options above (-d/w/m/y etc) may be combined in positive-negative pairs to display previous calendar entries and future calendar entries with the same command. For example: `clcal -d 7 -w -9` will print calendar entries for nine weeks prior to today, then today's entries, then the entries for the next seven days. `clcal -w -9 -w` will achieve the same output. Note that the negative period modifier must be specified (the positive period modifier is 1 by implication unless specified), so that in order to show calendar entries for one week prior to and one week after today, you could use: `clcal -w -w -1`.
-s xyz --search xyz --searchfwd xyz	Performs a search ahead in your calendar entries for the regular expression (in this example) "xyz". The search is case insensitive. The default is to search one year ahead, but this can be tailored by combining with the period flags above. e.g: `clcal -s doctor -m` or `clcal -w 7 -s dentist`. If your regular expression has spaces in it, put quotes around it, e.g: `clcal -s "bank holiday"`. Negative numbers are allowed (e.g: `clcal -w -7 -s dentist`) to search through past entries (like the `-b` option). If `clcal` finds your regular expression, it will print out each entry which contains it. If `clcal` does not find a match, then it will tell you that no entries containing your regular expression were found.
-b abc --searchbck abc	Performs a search back in your calendar's (past) entries for the regular expression "abc". The search is case insensitive. The default search period is one year, and may be modified in a similar way to the -s option. Negative numbers are not allowed with an explicit search back.
-a lmn --all lmn	Performs a search through all your calendar's entries for the regular expression "lmn". The search is case insensitive. If the regular expression is omitted, then this option will print ALL your calendar entries to stdout.

The options -b, and --searchbck are deprecated by the introduction of the use of negative numbers as search modifiers. However, after some thought, I have decided not to remove them from later versions of clcal.

Running clcal without any options will generate a brief usage message.

caveats

The maximum length for a line in a date file is 61 characters. If you go beyond this, strange things happen.
If you make an entry which contains tabs in a date file, these may not be accurately echoed to the screen, so please use spaces if you get unusual results.
The --month/-m option actually searches for calendar entries 30 days (or multiples of 30 days) ahead, not one calendar month.
The output is emboldened/coloured using ANSI escape sequences. If your term cannot interpret these correctly, then I'm afraid clcal (as it is), is not for you.
This is my first published C program. Learning all the time.