April 3, 2006

CLI Magic: When

Author: Joe Barr

User Level: Beginner

If you're the type of geek who likes tools and apps that are fast and lean, and you're not afraid of getting a little CLI under your fingernails, When is a good choice for your personal calendar. Even better, it's easy enough to install and use, and well enough documented, that you don't have to be a geek to take advantage of it.

In many Debian-flavored distributions, installation is as easy as sudo apt-get install when. You can also find the When source code, Debian, and Gentoo packages on the project's homepage. When is written in Perl and does not require compilation, so installation from source code is easy for anyone who can find their way to the command line. Simply untar the download and enter the resulting directory:

tar xzf when.tar.gz
cd when_dist

Then, as root, enter make install. That's all there is to it. If you get lost, you can get a refresher on the installation process by entering when --help from the when_dist subdirectory. Speaking of help, the man page resulting from the install is your main source of documentation. Unless you read Perl, that is, in which case you can simply view the source code.


The first time you run when, run it with the e parameter:

when e

That will create a ~/.when subdirectory that contains two key files files -- calendar and preferences -- and also let you choose an editor to use in the future, if you don't care for the default editor, whose name shall be left unspoken so as not to rile the great hordes using it or its rival products, an event certain to bring forth yet another meaningless yet compelling tsunami of flamage which will convince neither side that they hold the wrong position yet bore everyone else to a near-death experience.

Now you're ready to start entering events in your calendar. To enter a LUG meeting for 7 p.m. on March 30, type when e, which will now start the editor you picked earlier, enter 2006 Mar 30,7PM LUG Meeting, and save the file.

Later, when you've forgotten what's on your schedule, just enter when at the command line. When will display the current date and time, plus any events on your calendar for the next 14 days:

Thu 2006 Mar 30   11:14

Thu 2006 Mar 30 7PM LUG Meeting

But what if your LUG meets every week? You certainly don't want to have to enter the same line 52 times a year. Start When with the editor option again, remove the first entry, and replace it with one that looks like this:

w=Thu,7PM LUG Meeting

Now when you check your calendar, you'll always see it listed, like this:

Thu 2006 Mar 30   11:23

Thu 2006 Mar 30 7PM LUG Meeting
Thu 2006 Apr 6 7PM LUG Meeting

Only two weeks' worth are shown, because the default "window" for calendar events is 14 days. Remember the preferences file that was created during installation? You can change the default window and other things there. Let's start by taking a look at what is in our preferences file right now:

calendar = /home/warthawg/.when/calendar
editor = vi

The default window for items to appear in our calendar is one day into the past and 14 days into the future. We can change that window simply by adding some lines to the preferences file:


Now when we invoke when, the calendar shows this:

Mon 2006 Mar 27   11:50

Thu 2006 Mar 23 7PM LUG Meeting
Fri 2006 Mar 24 Basketball game at 3PM
Sat 2006 Mar 25 Feed the donkeys at 2PM
Thu 2006 Mar 30 7PM LUG Meeting
Thu 2006 Apr 6 7PM LUG Meeting
Thu 2006 Apr 13 7PM LUG Meeting

Be sure to enter the minus sign in front of the number of days in the past, or your results will not be as expected.

Instead of changing the default behavior when you want to see more or less of the calendar, you can also use command line options to indicate that you want to see a calendar for specific periods. The w, m, and y options allow you to request a report on all activity for the coming week, month, or year instead of simply for the default window.

Just need to see when a specific date falls on the calendar? Use the c to get the previous, current, and next month's calendar:

$ when c
------February-------  --------March--------  --------April--------
 S  M  T  W  T  F  S    S  M  T  W  T  F  S    S  M  T  W  T  F  S
          1  2  3  4             1  2  3  4                      1
 5  6  7  8  9 10 11    5  6  7  8  9 10 11    2  3  4  5  6  7  8
12 13 14 15 16 17 18   12 13 14 15 16 17 18    9 10 11 12 13 14 15
19 20 21 22 23 24 25   19 20 21 22 23 24 25   16 17 18 19 20 21 22
26 27 28               26 27 28 29 30 31      23 24 25 26 27 28 29

When has a few more tricks up its sleeve, both as command line arguments and options. I refer you to --help and man entries to further your command of When.

Click Here!