Gcal the ultra-powerful command line GNU calendar

April 15, 2010 6 minutes read | 1244 words by Ruben Berenguel

The Ben NanoNote has very few applications, as of now. And one it has (among a few nice others), is Gcal. I didn’t know what Gcal was, and the Qi hardware wiki page on Gcal pointed me to this quite nice tutorial: The many uses of Gcal.

The tutorial is quite good, but somewhat long, and lacks a few specific examples, so I decided to write just what I read in that tutorial, mixed with the uses I am putting it to, so it is more a Gcal use cases than a full blown tutorial like that.

Dear reader, if you find anything confusing, want a longer explanation or information about some command not explained here, feel free to post the question as a comment below, this will help everyone reading this.

What can you use Gcal for? Gcal can be used for a lot of calendar related questions. A zillion calendar options (did you wonder what the old armenic months are?), more than you probably know about. Of course, if you are not a calendar freak, this is not the main selling point. Gcal works (and is intended to) as a diary, and appointment planner. It can also be used to determine sunset or sunshine in your local coordinates, and if you are an amateur astronomer, it can give you the twilight times. The same holds for data for the Moon, it can give you the moon phase, for instance.

Hey, its already the 21st century! Command line? I can hear you mumbling How come I have to use a command-line calendar?‘Of course, if you are into really pretty UIs… Skip this article. This is more for the Unix/Linux user who just pops open a terminal and shouts gcal -f $mycalendar when he wants to know what today is due.

Ultra-portable & ultra-accessible. If you happen to have an ultraportable Linux thingy (like the NanoNote ;) you can carry your Gcal whenever you go. But if you have a fixed Linux box with Internet connection (at you office, at your server, wherever) you can ssh and run Gcal, from anywhere.

First steps: Installing and month displays: Well, the first step is to have gcal installed. If you are on a Linux box, it is quite easy, as it is in all repositories.

sudo apt-get install gcal

Now you can run it, to get a calendar view of the current month (gcal). You can also view three months (gcal .), or a full year (gcal 2010). The command -b N selects the number of month rows to display (gcal -b 4). You can also select a specific year, or range of months (gcal 3-5 2009). There is also an alternate month view (gcal -i). Below you can see this examples in a composition of terminal captures

Click to enlarge, and try by yourself!

Resource files: your calendar and more, much more. The crux of Gcal is its ability to work with resource files. In a typical resource file example.gcal (the name and extension are of your choice) you have something that looks like

0 This appears every day!
20100410 This only on 2010, April 11th

Your diary will be something like this. You may wonder if this is enough… But I haven’t told you what you can write and what you can do with these date fields! Some more examples

2010apr01#99 All April
2010apr01#may99 April&May
2010aprsa1#sa9.7 April saturdays

The general notation for date ranges is date-identifier#final-date. Thus, we select the first day of April, and the event lasts until the 99th day, effectively marking all days of April. To mark all saturdays, a similar notation is used, but amazingly, a high number results in a error, please select 9 as in the sample. You can see a sample output in the following screenshot. You will also need to add .7, for each 7 days.

Click to enlarge

You can also see how to call Gcal to open a resource file: with either --resource-file or the -f commands. To display the fixed date list (i.e. what there is in the resource file) you need the -c command, and -cd or -ct would only list today and tomorrow, respectively. The command shown is -cdl@t55 which stands for show today and 55 days ahead starting from tomorrow.

You can find all range modifiers here.

Change of the date format. If you are a tinkerer, you probably don’t like the default time representation. I don’t I prefer to get output as YYYYMMDD without any separation. It can be easily pasted into file names to have them quickly sorted by date.

How to change it? As usual, you can invoke gcal with a change for that. An example could be --date-format='%>3w#K%1%Y%>02*M%>02*D%2’ I can hear you saying d’oh! But it is not as bad as it seems. It breaks down as

%>3w#K 3 letters of the weekday
%1 Start highlighting
%Y Year number
%>02*M Fix 2 digits in month number
%>02*D Fix 2 digits in month day number
%2 End highlighting.

Not as bad as it looked like? You can find all descriptions for this here (bottom).

Click to enlarge

Change fixed date header list. That fixed date list heading is pretty ugly, don’t you think? What happens when you call Gcal with --heading-text="%3 %Y %U %4"? You can see the output below. It makes for a more appealing view of events. To learn about heading modifiers, look here (and search for heading).

Click to enlarge

Sample script: sunset and sunrise times. You can save this in astronomical.gcal, and open when you want to know at which time the sun sets or shines. There are a lot of related options, learn more about sun/moon modifiers here. You will need to know your latitude/longitude.

; latitude 41.4798
; longitude 2.3188 for gcal add 2 trailing zeros
; height 0
; Winter time Barcelona: GMT+1 Summer time Barcelona: GMT+2

$w=+60
$s=+120
$v=%2%4
$p=0*d1#999

$c=+41.4798+002.3188
$x=~Sunrise %o$c,$w | Sunset %s$c,$w ~Daylength %u$c,$w | Nightlength %z$c,$w
$y=~Sunrise %o$c,$s | Sunset %s$c,$s ~Daylength %u$c,$s | Nightlength %z$c,$s

; Winter time selector
$b=%e#1980 %i0@a#0@b-1
b=10sun9

; Summer time selector
$a=%e#1980 %e0@a#0@b-1
a=03sun9

; What will be written, through selectors.
$p $a $x
$p $b $y

And the output of gcal –resource-file=./astronomical –heading-text="%3 %Y %U %4" –date-format='%>3w#K%1%Y%>02*M%>02*D%2' -cdl@t4 is shown in the following screenshot.

Click to enlarge

This is getting hard… I know, all these commands together are getting increasingly harder to write or comment. If you happen to use or call a specific command really often, you can call gcal -list-of-commands-really-long -S name and it will output that call into a executable shell script that when invoked calls Gcal with said options. This one is great!

I hope you enjoyed this small tutorial on Gcal. Please also read the one I used as a guide (which covers a few more things I ommited), and refer to Gcal’s documentation if in doubt. If you liked this post, consider sharing it with your favourite tool (Stumble, reddit, digg, mail). Thanks!

Next week I’ll show you how to use sed to add colours to your events, and how to set at to send you an email every day with your scheduled tasks. You can see a sample from my colour scheme below.

ParseList(ScrambleList(Relateds(Linux)),5)