icarus

README

icarus

iCal file processor

Introduction

icarus is a command line utility that processes iCal files as defined in RFC5545. Additionally, it can convert files to the iCal format.

It utilizes the common unix philosophy of commands doing one specific thing with one output piped to another command.

Version 1 was developed in Java while icarus now is developed in Golang.

The packages that make up icarus can also be used in form of a Golang package.

Usage

Download the last stable release of icarus for the platform and architecture of your choice and then run the icarus command following the processor or converter subcommand and relevant arguments.

Use icarus --help for the available subcommands and arguments. Use icarus <subcommand> --help for more information about the specific subcommand.

Selectors

For processors, icarus supports selecting events from the incoming data to be processed by the selected processor.

By default, all events are selected. The following selectors are available:

• text selector: the --selector argument can be used to select events based on a regular expression. By default, the properties "summary" and "description" are searched for the pattern. This can be changed using the --selector-props list
• time selector: the --timestamp-start and --timestamp-end arguments can be used to select events starting after and ending before the given timestamp respectively. The timestamp needs to be RFC3339-formatted

Outputs

icarus outputs the data in iCal format by default, you can use the --output-type argument to specify another output type.

Available output types are:

csv

Outputs all events as rows in a CSV file. The iCal field names are used for the CSV headers. You can select the separator using the --separator parameter.

list (deprecated)

Outputs all events formatted as a table.

This output is currently deprecated as the name is misleading. In the upcoming major version we will implement an actual list here. You can use the table output to get the same output.

table

Outputs all events formatted as a table. The iCal field names are used headers for the table.

Processors

The following processors are currently available:

addAlarm

Adds an alarm before the selected events. The argument --alarm-before specifies how many minutes the alarm should be before the start of the event.

addDTStamp

Adds a DTSTAMP property as specified by the --timestamp argument. If an event already has a DTSTAMP property, it may be overwritten by using the --overwrite argument.

addProperty

Adds a property to all selected events. If an event already has the given property, it may be overwritten by using the --overwrite argument.

convertAllDay

Convert all day events into events with a start and end time ("timed events") or vice versa if the --all-day flag is used.

Start and end times have to be specified in a colon-separated, 24 hour format (like 13:00) in the arguments --start and --end respectively.

If all day events span multiple dates, the --compress argument can be used to make them only span the start date.

If UTC is not the expected timezone, the IANA timezone name can be set using the --timezone argument.

deleteProperty

Deletes a property from all selected events. Be sure to not remove properties which are required for events (namely DTSTART, DTEND and SUMMARY)

filter

Only output the events matching the selector or, if the --inverse flag is used, events not matching the selector.

print

Output all events from the source calendar. The selectors are ignored for this subcommand. Can be used to make use of icarus' output types.

Converters

The following converters are available:

convertCSV

Converts a file in the CSV format to a calendar. This is done by mapping the CSV header to an iCal field. iCal date fields are convertered to timestamps using the configured timestamp format.

If you don't have a timezone information in the CSV file, which is quite common, you can set the expected timezone location with the --location parameter.

To create a working calendar, you at least need to define columns with the start timestamp, end timestamp and a summary.

Contributing

We're happy to accept contributions to icarus. Please make sure to use the issue tracker first before you send pull requests to make sure the task can not be done with the current set of options.

Since version 2 icarus is developed in Golang.

Please make sure to supply sufficient unit tests to the changes you submit. Always branch from the develop branch.

Creating new processors

A processor has to ímplement the interface BaseProcessor.

Initialize is used to create a new argparse Command type that runs the processor. Use uppercase short arguments to distinguish them from other processors and the main and output arguments.

SetToolbox is called to set the toolbox variable for the processor. The toolbox contains several useful tools for developing a processor - most importantly the EventMatchesSelector function that needs to be called for every event so that the selector arguments are properly used.

Finally, Process is called with the incoming events and a reference to the output events, both in form of a Calendar type from the golang-ical package.

To activate a processor, add it to the GetProcessors function in processors.go.

Be sure to create sufficient unit tests in a _test file and add a documentation to this readme.

Creating new output types

Output types implement the BaseOutputType interface.

Initialize is used to add arguments to the main icarus argument parser. See the argparse package for details.

Use lowercase short arguments to differentiate them from processor arguments, but make sure they don't clash with the arguments of other output types or main arguments.

Generate is provided with the processed calendar entries in form of a Calendar type and an io.Writer variable to which the output should be written to.

GetHelp returns a short string about the function of the output.

Add the new output type to the return value of the GetOutputTypes function in output_types.go

Finally, provide sufficient unit tests in a _test file and update the documentation.