icalBuddy
icalBuddy is a command-line utility that can be used to get lists of items (i.e. events and tasks/todos) from the OS X calendar database (the same one iCal uses.) It requires Mac OS 10.5 or later. See my blog post about it for more info.
Documentation:- icalBuddy manual page
- icalBuddyConfig manual page
- icalBuddyLocalization manual page
- Frequently Asked Questions
~ $
~ $ icalBuddy eventsToday
* Update timesheet (Work)
* New Event (Test calendar)
00:02 - 00:03
* Timed test (Test calendar)
location: Building A
notes: Remember the milk
url: http://example.com
20:00 - 21:00
~ $
~ $
~ $ icalBuddy -sc eventsToday
Work:
------------------------
* Update timesheet
Test calendar:
------------------------
* New Event
00:02 - 00:03
* Timed test
location: Building A
notes: Remember the milk
url: http://example.com
20:00 - 21:00
~ $
~ $
~ $ icalBuddy -sc -ec Work eventsToday
Test calendar:
------------------------
* New Event
00:02 - 00:03
* Timed test
location: Building A
notes: Remember the milk
url: http://example.com
20:00 - 21:00
~ $
~ $
~ $ icalBuddy -sc -ec Work --timeFormat "%I:%M %p" eventsToday
Test calendar:
------------------------
* New Event
12:02 AM - 12:03 AM
* Timed test
location: Building A
notes: Remember the milk
url: http://example.com
08:00 PM - 09:00 PM
~ $
~ $
~ $
~ $
~ $ icalBuddy uncompletedTasks
* Talk to [organization] about combining [software_products] integration specs (there's overlap) (Work)
priority: high
* Test (Test calendar)
notes: I loves mine icalBuddies
url: http://google.com
due: 2008-06-30 00:00:00 +0300
priority: high
* Pay dad for the car servicing (Home)
priority: high
* Do some stuff (Home)
priority: medium
* Write some things (Home)
priority: medium
* Rewrite icalGet in Obj-C using Cocoa (Home)
* Install MS Office for Win from work (Work)
* Freak out (Home)
~ $
~ $
~ $ icalBuddy -sc -ic "Test calendar, Work" uncompletedTasks
Work:
------------------------
* Talk to [organization] about combining [software_products] integration specs (there's overlap)
priority: high
* Install MS Office for Win from work
Test calendar:
------------------------
* Test
notes: I loves mine icalBuddies
url: http://google.com
due: 2008-06-30 00:00:00 +0300
priority: high
~ $
~ $
~ $ icalBuddy -sc -ic "Test calendar, Work" -etp "priority, dueDate, url" uncompletedTasks
Work:
------------------------
* Talk to [organization] about combining [software_products] integration specs (there's overlap)
* Install MS Office for Win from work
Test calendar:
------------------------
* Test
notes: I loves mine icalBuddies
~ $
If you are going to use icalBuddy with GeekTool, I recommend that you try my custom build of it — it includes some features that might be useful, like ANSI escape sequence formatting support (i.e. colors, bolding, underlining etc.) and unicode (UTF-8) support (for displaying non-ASCII characters like umlauts, arabic or hebrew). Version 3 of GeekTool also seems to be coming along nicely and it seems to have some (or all?) of these features already so it might be better to check that one out first, though.
icalBuddy has been written in Objective-C (with a little bit of C sprinkled on top), using the OS X Cocoa, CalendarStore, AppKit and AddressBook framework APIs. This software is licensed under the MIT License.
Copyright © 2008-2010 Ali Rantakari.
Repository URL:
http://hasseg.org/git-public/icalBuddy.git/
Repository web page:
http://hasseg.org/gitweb?p=icalBuddy.git
Example:
cd ~/mycode
git clone http://hasseg.org/git-public/icalBuddy.git/
Latest version:
Version 1.7.0
→
Download
February 03, 2010
Changelog:
- Added the
-sed(or--showEmptyDates) argument that display sections for empty dates (i.e. dates that have no items) that fall within the specified range as well. This argument applies only if the-sd(or--separateByDate) argument is used. - The tab (
\t) escape sequence is now interpreted in some argument values.
Older versions:
Version 1.6.19
→
Download
February 01, 2010
Changelog:
- Added italian localization file by Giuseppe Sacco (grazie!)
- A few escape sequences (most notably newlines, i.e.
\n) are now interpreted for some arguments that take arbitrary strings as their values.
Version 1.6.18
→
Download
January 22, 2010
Changelog:
- The application's Universal Binary now contains 64-bit Intel (x86_64) code in addition to 32-bit Intel (i386) and 32-bit PowerPC (ppc) code.
- Added polish localization file by RybA. (dzięki!)
- Added latin localization file by Miller Krause (gratiae!)
Version 1.6.17
→
Download
January 16, 2010
Changelog:
- An uninstallation script is now included.
- The default bullet point has been changed from an asterisk (
*) to an actual bullet point (•). - Bright ANSI colors are now considered when determining the closest equivalent ANSI color for the actual color of a calendar.
Version 1.6.16
→
Download
January 11, 2010
Changelog:
- If output formatting is turned on (via the
-for--formatOutputargument) and no foreground color is specified for event/task titles (in the config file's formatting section), the closest ANSI color to the color of the calendar will be used as the title foreground color.
Version 1.6.15
→
Download
December 02, 2009
Changelog:
- If the date or time format is an empty string, the date/time separator (e.g.
" at ") won't be displayed.
Version 1.6.14
→
Download
November 24, 2009
Changelog:
- Added support for bright foreground and background ANSI colors as well as blinking text.
Version 1.6.13
→
Download
November 12, 2009
Changelog:
- Added German Localization file by Wolf Mc Ewen (Danke schön!)
Version 1.6.12
→
Download
October 08, 2009
Changelog:
- Improved the formatting for the list of changes since the currently installed version (in the self auto-update feature invoked via
icalBuddy -u).
Version 1.6.11
→
Download
October 03, 2009
Changelog:
- Made the automatic update feature work even if you don't have the
linkscommand-line browser installed (this is quite embarrassing but I forgot that it doesn't ship with Mac OS X by default)
Version 1.6.10
→
Download
September 29, 2009
Changelog:
- When sorting tasks by due date, in ascending order, put tasks without due date last (instead of first).
- Made the
-ic(or--includeCals) and-ec(or--excludeCals) arguments work when using thecalendarscommand. - Fixed a crashing bug related to the self auto-update feature.
- Fixed the install script's colored output on Snow Leopard.
Version 1.6.9
→
Download
August 02, 2009
Changelog:
- Fixed a bug in the installation script that caused it to fail when run under a path that contained spaces.
Version 1.6.8
→
Download
July 06, 2009
Changelog:
- Added the
-std(or--sortTasksByDate) argument, which sorts tasks simply by their due dates (in descending order), as well as the-stda(or--sortTasksByDateAscending) argument, which does the same but in ascending order. - Fixed a bug where specifying the value
"*"for either the-eepor the-etparguments would exclude all properties instead of everything but the titles.
Version 1.6.7
→
Download
May 15, 2009
Changelog:
- Added the
-eed(or--excludeEndDates) argument, which excludes the dates/times of when events end from the output.
Version 1.6.6
→
Download
April 27, 2009
Changelog:
- Added formatting keyword
calendarNameInTitlewhich can be used to specify the formatting of the calendar names that are printed in parentheses next to event/task titles. (See the configuration file man page for more info on formatting keywords.) - Added localization keyword
dateTimeSeparatorwhich specifies what to print between the date and the time — in english, for example," at "is used. (See the localization file man page for more info on localization keywords.) - Removed the
-dts(or--dateTimeSeparator) argument due to the value it sets being specified in the localization file now. - Improved the formatting of the list of changes since the current version when running the automatic update (
icalBuddy -u, followed by optionawhen you get the question of how to proceed.) - Added french localization file (by Matthieu Sieben — merci!)
- Added PDF versions of all the three manual pages into the distribution package.
- Added the FAQ html file into the distribution package.
- Cleaned up the code in various places.
Version 1.6.5
→
Download
April 19, 2009
Changelog:
- Added the
-ps(or--propertySeparators) argument, which can be used to specify what to separate printed item properties with. The value for this argument is a string where each component is separated by an arbitrary character (which must also be present at the start and the end), like this:"|-first-|-second-|-third-|". The components in this list will be used as the separators between item properties in order from first (for the first printed property for an item) to last, using the last one several times if too few are specified. The default is"|\n |"(that's a newline followed by four spaces, used as the separator for all properties.) This argument can be used to print item properties on the same line (just specify a value that does not include a newline.) - Added an automatic update feature: run
icalBuddy -uto check for updates and then if an update is found, respond to the question of how to proceed with optiona, and icalBuddy will first display you a list of what's changed since the version you're running and then ask if you'd like it to automatically download the distribution package and update itself. - Added the
-nnr(or--notesNewlineReplacement) argument, which can be used to specify the string to use for replacing newlines within values of the notes property. - Removed the
-i(or--indent) argument (not needed anymore due to the new-psargument, which provides similar behaviour in a more flexible way.) - Removed the
-nni(or--notesNewlinesIndent) argument (not needed anymore due to the new-nnrargument, which provides similar behaviour in a more flexible way.)
Version 1.6.1
→
Download
April 16, 2009
Changelog:
- Fixed bug where multi-day-spanning events were shown for each and every day they span, regardless of the specified date range to display, when using the
-sd(or--separateByDate) argument. (as reported and tested by Kene and Micah -- thanks) - Added the
-li(or--limitItems) argument which can be used to limit the number of printed items (events/tasks) to a maximum number.
Version 1.6.0
→
Download
March 27, 2009
Changelog:
- Added the possibility to fully customize the formatting (colors, bolding, underlining) icalBuddy uses for the output (when the
-f(or:--formatOutput) argument is used) via a per-user configuration file. See the icalBuddyConfig man page for documentation. - Added the possibility to set "constant" argument values via the per-user configuration file (that is, argument values that will always be true when you run icalBuddy, without having to always explicitly provide them as arguments to the executable.) See the icalBuddyConfig man page for documentation.
- Added command arguments
editConfigandeditConfigCLIfor automatically creating the configuration file if it doesn't exist and opening it in an editor (so for example you can runicalBuddy editConfigto open the configuration file in a GUI editor andicalBuddy editConfigCLIto open it in a command-line editor.) - Display the currently logged in user's birthday event from the Birthdays calendar by default as "My Birthday" (this is also localizable by using the key
myBirthday.) - Fixed bug where parts of the output that were affected by command-line arguments were garbled if non-ASCII characters were passed in as the values for those arguments.
- Made the default value of the section separator string
"\n------------------------": the leading newline is now part of the section separator which means that it is now possible to either keep the section separator on the same line with the section title by specifying a value that doesn't have a newline in the beginning (e.g.icalBuddy -ss " -----") or just omit it completely by specifying an empty string (e.g.icalBuddy -ss "".) - Added argument
-nni(or:--notesNewlinesIndent) for modifying the number of indenting whitespace characters to use when indenting additional lines in the "notes" property values. So for example if you're using icalBuddy with GeekTool and a non-fixed-width font, the indenting level for additional lines in the notes property values might be a bit off, so now you can use this argument to fix this (for example, runicalBuddy -nni 4in order to add four whitespace characters to the indenting oricalBuddy -nni -2to remove two.) - Made the "usage" output (i.e. what you see when you run icalBuddy without any arguments) a lot more succinct.
Version 1.5.0
→
Download
March 16, 2009
Changelog:
- Implemented localization support: you can now create a property list file at
~/.icalBuddyLocalization.plistcontaining a dictionary mapping of localization keys (e.g."someonesBirthday") to their human-readable equivalents (e.g."%@'s Birthday"). Documentation for this feature can be found in the icalBuddyLocalization man page: just typeman icalBuddyLocalizationinto the terminal. An example localization file for Finnish is included.
Version 1.4.0
→
Download
March 11, 2009
Changelog:
- Implemented output type
eventsFrom:to:which allows you to specify any arbitrary date range for getting the events to be displayed. An example:icalBuddy eventsFrom:"2009-01-01 10:12:13 +02:00" to:"2009-02-02 20:22:23 +02:00"
Version 1.3.7
→
Download
March 05, 2009
Changelog:
- Fixed a bug where multi-day-spanning events were only displayed under the start day when separating by day (e.g. an event that spans from monday to tuesday would only be displayed under monday.)
- Fixed a bug where sections would be displayed for the starting days of multi-day-spanning events (where the span would include the current date) when separating by day, even when the start date was before the current date (e.g. a section for "yesterday" would be shown with an event that spans from monday to tuesday if you ran
icalBuddy -sdon tuesday.) - Fixed regression where past events for the current date were not shown when separating by day even though the
-nargument was not set.
Version 1.3.6
→
Download
February 26, 2009
Changelog:
- Fixed bug where the
-iargument was not taken into account when indenting additional lines for values of the "notes" property (only exhibited if note values have line breaks.) - Fixed bug where having percentage characters (
%) in any of the calendar items (i.e. in their titles or in any properties) made the output get garbled. - Added a lot more colors into the output (via ANSI escape sequences) if the
-fargument is set. - Added more possible values for the "relative dates" (i.e. dates that are easily identifiable with a simple natural language phrase or word (in relation to the current date) instead of the standard representation specified by the date formatting string): in addition to "today" and "tomorrow", dates may now also be displayed as "day after tomorrow", "yesterday" or "day before yesterday".
- Added argument
-nrd(or:--noRelativeDates) for disabling the "relative dates" feature (see previous point.) - Cleaned up the code a bit.
Version 1.3.5
→
Download
February 21, 2009
Changelog:
- Implemented custom date formatting specifier
%RW, which stands for "relative week" (for example: last week, this week, next week, 2 weeks from now etc.) It can now be used in values for the date format (-dfor--dateFormat) argument. - Added argument
-b "value"(or--bullet "value") for specifying the string to use as the "bullet point" (the default is"* ".) - Added argument
-ab "value"(or--alertBullet "value") for specifying the string to use as the "alert bullet point" (the default is"! ".) - Added argument
-i "value"(or--indent "value") for specifying the string to use as the indentation for lines other than the first one for each item (i.e. the one that gets the bullet point) (the default is four spaces:" ".) - Added argument
-ss "value"(or--sectionSeparator "value") for specifying the string to use as the "section separator" (i.e. the string that separates sections from items that belong to that section) (the default is"------------------------".) - Made installation a bit easier: the install script has been renamed to install.command so that you can run it directly from Finder by double-clicking. It will also tell you what it's going to do and prompt you to continue or cancel before actually starting to install.
Version 1.3.2
→
Download
February 19, 2009
Changelog:
- Fixed a regression where the due date for a task was not indented or bulleted properly in the output.
- Fixed a regression where the "alert" bullet point (an exclamation point (
!) instead of an asterisk (*)) was not used for tasks that are late. - Fixed a regression where the URLs for events in the birthdays calendar were shown (they're not supposed to be shown to users.)
Version 1.3.1
→
Download
February 17, 2009
Changelog:
- Added shell script
install.shfor installing the binary and the man page into the default locations so that users wouldn't need to have the OS X developer tools (i.e.makethat's needed in order to runmake install) installed. Update (feb 18, 2009): actually added the install.sh file into the package (it was missing before) :)
Version 1.3.0
→
Download
February 08, 2009
Changelog:
- Added argument
-sd(or--separateByDate) which will separate items in the output by their dates (start dates in the case of events and due dates in the case of tasks.) - Added argument
-po(or--propertyOrder) which can be used to specify the order in which item (event or task) properties appear in the output. The allowed values (in the default order) are the following:title, location, notes, url, datetime, priority.
Version 1.2.5
→
Download
February 06, 2009
Changelog:
- Added output type argument
"eventsNow"which outputs only events that are occurring at present time (i.e. right now.) - Added the
-nc(or--noCalendarNames) argument, which omits the names of the calendars that events or tasks belong to from the output.
Version 1.2.1
→
Download
February 06, 2009
Changelog:
- Fixed some mistakes in documentation and added documentation for the "eventsToday+NUM" feature.
Version 1.2.0
→
Download
February 05, 2009
Changelog:
- Made it possible to display events from farther on in the future by adding "+NUM" to the end of the "eventsToday" argument, where NUM is the number of days into the future you would like to see (i.e. "icalBuddy eventsToday+2" to also see events for tomorrow and the day after.)
- Changed the
-s(or--separate) argument to-sc(or--separateByCalendar) in order to allow for distinctions between different kinds of separation (like separation of items by date, which will be coming in a future update.) - Removed the
-dtf(or--dateTimeFormat) argument as redundant (we can just use a combination of the date formatting string and the time formatting string to get a date-time formatting string.) - Added argument
-dts(or--dateTimeSeparator) for specifying the separator string between dates and times in the output. The default is" at ". - Added some simple cases where dates would be formatted as natural language relative to the current date (e.g. "today" or "tomorrow" instead of "2009-02-05".)
- Fixed the tinyurl links to Apple's date formatting string syntax documentation.
Version 1.1.1
→
Download
October 11, 2008
Changelog:
Just some minor code cleanup.
Version 1.1.0
→
Download
August 01, 2008
Changelog:
Changes related to output string encoding:- Changed the default output string encoding to UTF-8.
- Added option
--strEncodingfor setting the desired output string encoding. - Added possible
output_typevalue "strEncodings" so that you can runicalBuddy strEncodingsto see all the possible values for the--strEncodingoption.
Version 1.0.8
→
Download
July 28, 2008
Changelog:
- Added parameter (
-for--formatOutput) to specify whether to format the output via ANSI espace sequences (in order to make it more readable). Currently this only makes the titles of items bold.
Version 1.0.7
→
Download
July 23, 2008
Changelog:
- Added additional ordering rule for tasks to make identically prioritized tasks get ordered alphabetically by title.
- Code cleanup: used bitflags for the pretty-print functions instead of "contexts".
Version 1.0.6
→
Download
July 02, 2008
Changelog:
- Fixed displaying of events from Address Book's Birthdays calendar (before it would just show the URL to the Address Book entry, now it shows a line like
"* Ali Rantakari's Birthday".)
Version 1.0.5
→
Download
June 23, 2008
Changelog:
- Made tasks that are late from their due date get sorted before ones that are not (when the priority is the same.)
- Fixed silly oversight in Makefile where
sudo make installwould fail because the binary and manfile installation paths were not present.
Version 1.0.4
→
Download
June 21, 2008
Changelog:
- Now prints only the date (instead of the date & the time) for task due dates (you can't specify a time for a task due date in iCal anyway.)
- Now prints
"today"(instead of the time) for a task's due date if it is on the current date. - Now uses an exclamation point symbol (
!) in place of the standard asterisk "bullet point" symbol (*) for tasks that are late from their due date. - Added new parameter
-df(or:--dateFormat) for specifying formatting strings for dates (as opposed to times or date & time combinations.)
Version 1.0.3
→
Download
June 21, 2008
Changelog:
- Made notes and locations with values of empty strings (or just any number of whitespace) not get displayed.
- Put default time and dateTime formatting strings into macros.
Version 1.0.2
→
Download
June 19, 2008
Changelog:
- Added indentation to new lines within notes.
- Changed all
printf()statements toNSPrint()statements in order to avoid some weird problems with standard output. - Removed some unnecessary
return(0)statements.
Version 1.0.1
→
Download
June 19, 2008
Changelog:
- Now a Universal Binary. Also changed gcc arguments in makefile to conform to this.
- Added possibility to exclude all properties in the output for tasks or events by specifying
"*"as the value for -etp or -eep argument(s). - Fixed a bug where events from the previous day would be displayed when using the
"eventsToday"output type argument value. - Cleaned code a bit (removed an unused variable, made some things more explicit etc.)