The text that calmaker will convert to an ics file.

The calendar in iCal.

Our high school class was very small, and so our high school reunions are small affairs. There were, for example, all of three events this year: a meet-and-greet, a dinner, and a lunch memorial. Even with such a small calendar, people still find a calendar file useful. But it’s not worth it to maintain the events in a calendar app (or, worse, create a calendar app). It’s easier just to keep the events in a simple text file.

So I made a Perl script to convert a simple text file of events into an iCalendar .ics file (Zip file, 10.7 KB). All it needs is a text file like this:

Very simple, and it’s obvious what this text means. In fact, if you open this in pretty much any modern text editor it will be formatted to highlight the important bits and to keep the separate events readable as separate events, because this is very simple Markdown text.

It’s also easy enough for a Perl script to convert to a .ics file.

The script is meant to take files created for human purposes, not computer purposes. Except for the title of the event, which must always come first (and always be preceded by two hash marks—that is, a Markdown level-2 headline), the order of information doesn’t matter. If the script doesn’t recognize a piece of information, it assumes that it’s part of the description. It completely ignores blank lines.

Use the script like this:

You can, of course, leave off the > minicon.ics to see the calendar file output to your Terminal screen.

The above event will be transformed into this:

The script recognizes URLs and date ranges, and even simple addresses.

This gets converted to

Because this is meant for very simple files, it makes some assumptions. I didn’t bother recognizing all time zones, for example. I’m only likely to ever need a handful of time zones, so the current version only has the four continental US zones:

Similarly, if there’s a single hash mark at the top of the file it gets used as the title of the calendar; if not, the filename gets used as the calendar name. And if no time zone is specified in the events text, there’s a default in the script: my own time zone. That’s where most of the events I’ll be creating .ics files for are likely to take place. You, of course, will want to change that default to wherever most of your events take place.

If you need to specify a timezone in the events text, just include it at the top of the file:

The script assumes that events are taking place in the current year, but you can specify a year on the date line (“July 15, 2023” instead of “July 15”) or you can specify a default year at the top of the file

There are two potentially interesting things in this script. First, it isn’t very Perl-like in how it handles the event class. While Perl is much more freeform than other scripting languages—it’s first law is, after all, “There’s more than one way to do it”—it is generally accepted that class definitions go into their own file for re-use elsewhere.

However, I have no intention of re-using this class anywhere; if I do, I’ll move it out, but it’s simple enough that putting this class into its own separate file violates the second law of Perl: keep easy things easy.

So the Event class goes into a BEGIN section, which is basically treated as its own file by Perl; it has its own use lines and its own globals. Each have to go after the package line that names the class.

You can share variables between the main script and the package by defining them with our. It is very similar to the my and local keywords.

These two variables are available throughout the script.

Simple use lines are shared throughout the script as well, without any special handling. I’m not aware of any means to share lines like use List::MoreUtils qw(first_index); throughout the script; since this is Perl, there probably is a way to do it, but the easy way is to simply put the line inside the package.

The second interesting feature of this script—and by interesting, I mean that I finally learned of its existence because I wrote this script—is the ability to place regular expression pattern modifiers inside a regular expression string variable. In Perl, a regular expression is flagged by marking its beginning and ending with slashes¹:

Modifiers go after the final slash, and in that form they can’t be part of the variable. A regular expression in a variable normally looks like this:

Perl recognizes that this is a regular expression from the slashes, and uses the variable as the actual regex. But the case-insensitivity modifier is really part of the regular expression, and should be variable along with the expression. The slashes can’t be part of the variable, because then Perl won’t recognize the regular expression, which means that slash-modifier can’t be part of the variable.

This being Perl, however, there is of course more than one way of doing it. Pattern modifiers can also be placed within the slashes. An open parenthesis, a question mark, a series of pattern modifiers, and a close parenthesis will apply those pattern modifiers to the remainder of the regex.

This form of pattern modifier specification can even be placed within parenthesized subparts of the regular expression, if you need a modifier only for one part of the regex.

The main loop of the script is simply a sieve of regular expressions that recognize bits of events.

Before the script detects an event, it’s looking for the very few items it can use as part of the overall calendar: a title, a time zone, a default year, and a unique identifier (“slug”) for the calendar. The title of the overall calendar is a single pound symbol, a space, and then anything: it’s a Markdown level-1 headline. Timezones are recognized by being one of the zone keys in the timezone hash. And default years are recognized by being a four-digit number starting with a “2”.²

Once it sees an event headline, the script only looks for new events and their information. It does this by filtering the text through a series of regular expressions.

Detecting an event headline is simple: it’s just two pound symbols, a space, and any text. If there’s already an event, that event gets closed; if there isn’t an event, this is the first one, and so the calendar is started up. Then, the new event is created with its title and the current timezone.

The location’s title is marked by two asterisks—Markdown bold—at the beginning and end of the text.

The street address of the location is matched by looking for numbers at the start of the line and any text ending in Avenue, Boulevard, Lane, and so on. Obviously, there are more possibilities, and you’ll need to add them if you’re using them.

Similarly, the city, state, and zip code are detected by looking for a capitalized letter, then any letters as well as a space, a comma and a space, two capital letters, a space, and five digits. That is, something like “San Diego, CA 92102”. Depending on where you are or where your events take place, you may want to open up this regular expression to more possibilities.

URLs must begin with “https://”. If your event is still using “http://”, you’ll want to change the “https” to “https?”. A question mark makes the preceding character optional.

A time is recognized as anything like “5:30 pm” or “10:15 AM”. It’s case-insensitive to allow for both uppercase and lowercase “am” and “pm”.

A duration is any digit, a space, and either the word hours, minutes, or days. The “s” is optional in each case, so that you can type “1 hour” or “3 days” or even “2 day”.

The date regex uses a variable created from the list of months. It can be any month name, a one or two digit number (that is, the date in the month), and optionally a dash and another number to create a multi-day event.

This does exactly the same thing:

And finally, anything that isn’t recognized is part of the description.

You can see how this works in the sample text file for a fictional roleplaying minicon. I’ve included that, and the .ics file it creates, in the calmaker zip archive (Zip file, 10.7 KB) so that you can see what it does on a real file.

I quoted Douglas Adams in 42 Astoundingly Useful Scripts and Automations for the Macintosh about being “rarely happier than when spending an entire day programming my computer to perform automatically a task that it would otherwise take me a good ten seconds to do by hand.”³ Creating a .ics file by hand would have taken more than ten seconds, but there’s still a lot of that sentiment in this script. It depends on how often I use this script. But there remains a joy in taking something in one format—especially something that is simple and readable by human eyes—and transforming it automatically into the kind of restricted format that computers need.

There remains a joy in exploring the hidden crevasses of an interchange format such as icalendar, teasing out its benefits and working around its flaws, to create something that can be shared throughout a wide community. It is one of the many great joys of programming.

There are still things to do. I don’t like how the script handles calendar and event identifiers. These identifiers (X-WR-RELCALID and UID in the .ics file) make it possible to update events that already exist in the user’s calendar. They’re very useful. Without event identifiers, when a participant adds the calendar a second time they’ll get a second set of events and have to manually delete all of the events in the first set. With event identifiers, the calendar program will automatically replace the old set with the new set.

For any gathering of any reasonable size, they’re a necessity, because you’ll almost certainly be updating your event information. So currently the script allows you to specify a slug for the calendar and for each event. It looks for “slug:text” and uses that as the calendar or event slug, combining it with a base identifier built in to the script. Never change a slug once it’s been created! A changed slug doesn’t update the old versions of what it referred to.

I have no idea how to create a unique, unchanging identifier from the event information alone without defeating that purpose. If it were based on the title, date, and/or time, it would then change when the event’s title, date, or time changed, and would thus not replace the old event. So currently, the script defaults to incrementing an event number, starting at 1. The first event is “baseid-calendarid-event-1”, the second “baseid-calendarid-event-2”, and so on.

As long as any updated .ics file contains at least as many events as the previous .ics file, all of the events will be replaced when someone re-downloads the calendar file. If the updated file contains fewer events, however, the trailing events will probably not be deleted (it may depend on the calendar program used).

If you use webcal:// instead of http:// or https:// to link to the calendar file, the calendar program should check regularly for updates automatically.⁴

You may wish to change the base identifier to something that reflects your own domain name or name. For example, if you have a domain name of “example.com ”, you might change the base identifier to “example-com”:

And of course you may also wish to change the default time zone at the top of the file.

iCalendar .ics file creator (Zip file, 10.7 KB)