calendarium-romanum/calrom

liturgical calendar for the command line

calrom

Command line utility providing access to the Roman Catholic liturgical calendar (post-Vatican II).

Built on top of the calendarium-romanum Ruby gem.

Installation

calrom is a Ruby gem:

$ gem install calrom

Usage

Specifying date range

Print liturgical calendar for the current month (default):

$ calrom

... for a specified month of the current year:

$ calrom -m 9

... for a specified month of another year:

$ calrom -m 1 2028 or $ calrom 1 2028

... for a whole year:

$ calrom 2017

... for the current year:

$ calrom -y

... for a specified date:

$ calrom 2028-01-15

... for an arbitrary date range:

$ calrom 2028-01-15 2028-03-07

Day and celebration filtering

In addition to specifying date range, filtering is a way to further refine the selection of data to be displayed. Options --day-filter= and --celebration-filter= both accept a snippet of Ruby code, which is then evaled in context of each CalendariumRomanum::Day / CalendariumRomanum::Celebration within the selected date range and only days/celebrations for which the expression evaluates truthy are displayed.

Display only Saturdays:

$ calrom --day-filter='date.saturday?'

Display all Mondays with a celebration of a rank higher than memorial:

$ calrom --day-filter='date.monday?' --day-filter='celebrations[0].rank > MEMORIAL_GENERAL'

(As you can see, calendarium-romanum constants like ranks or seasons are available as top-level constants. Noone likes extensive writing in the terminal.)

Display only ferials:

$ calrom --celebration-filter='ferial?'

Display only celebrations in green:

$ calrom --celebration-filter='colour == GREEN'

The options can be combined and used repeatedly to narrow the selection down as needed.

Selecting calendar

There are a few calendars bundled in calrom (actually in the calendarium-romanum gem) and ready to use. List them:

$ calrom --calendars

Each entry of the listing contains an ID of the calendar, it's name and language code. Use calendar ID to request General Roman Calendar in Latin:

$ calrom --calendar=universal-la

You can prepare your own calendar data and load them:

$ calrom --calendar=path/to/my_calendar.txt

If you specify more than one calendar, they are loaded "layered" one over another (from left to right), which comes in handy when extending a general calendar with just a few additional and/or differing celebrations, e.g. solemnities (titular, dedication) of the local church:

$ calrom --calendar=universal-la --calendar=path/to/our_local_celebrations.txt

Please note that specifying more than one calendar disables automatic loading of parent calendars. If any of the listed calendars extends a parent calendar, the parent either has to be explicitly listed using the --calendar option in order to be loaded, or automatic parent loading has to be explicitly enabled using the --load-parents option.

Limited support for remote calendars is provided. Calendar URL from the Liturgical Calendar API or a compatible calendar API is accepted as a value of --calendar=:

$ calrom --calendar=http://calapi.inadiutorium.cz/api/v0/en/calendars/general-la

Data presentation settings

Print detailed listing:

$ calrom -l

Print current day in a condensed format (intended mainly for use cases like window manager toolbars):

$ calrom --format=condensed --today

Disable colours:

$ calrom --no-color

Machine-readable output formats:

$ calrom --format=json - prints JSON array containing one object per day. The object contents mimick output of the Church Calendar API v0.

$ calrom --format=csv - prints a CSV, one celebration per line (i.e. there is one or more lines for each liturgical day).

Configuration files

calrom looks for configuration files /etc/calromrc and ~/.calromrc. They are processed in this order and both are used if available. Their syntax is that of shell options and arguments (with the sole exception that newline is not considered end of shell input, but generic whitespace), supported are all options and arguments accepted by the command.

If a custom configuration file location is specified on the command line, $ calrom --config=path/to/my/custom/config, the standard system-wide and user-specific configuration files are not loaded. Empty config path $ calrom --config= makes calrom ignore all configuration files and use the built-in default configuration.

Example configuration file, loading the proper calendar of the archdiocese of Prague and disabling colours:

# shell-like comments can be used in configuration files

--calendar=czech-praha-cs # calendar of the archdiocese of Prague
--calendar=~/calendar_data/local_church.txt # path to a custom calendar file with proper celebrations of the parish where I live (titular feast of the church, dedication)

--load-parents # load also parent calendars specified by the calendar file(s)
               # (default if just one calendar file is specified, but we specified two)

--no-color # disable colours

(Configuration file format is inspired by .rspec, .yardopts and others.)

Most options work in such a way that if several conflicting options are provided, the last one wins. You can thus e.g. set your favourite display format (e.g. --list) or date range (e.g. -3) in the configuration file and override it, if necessary, by providing some other option from the same group on the command line. An exception from this rule is the --calendar= option, repeated occurrences of which do not cancel each other, but are all composed together in the given order to build a calendar by layering. Also repeated occurrences of the --day-filter= and --celebration-filter= options don't cancel each other, but all specified filtering expressions are applied.

Running tests

Clone the repository, $ bundle install to install dependencies, then:

$ rake cucumber - run specs describing the command line interface

$ rake spec - run specs describing internal implementation details

$ rake - run all groups of specs one after another

Project roadmap

• detailed listing of a day/month/year/range of dates
• month/year overview - options and output mostly mimicking the BSD Unix cal utility, but with liturgical colours and celebration ranks
• condensed format (but with detailed information) suitable for awesome/i3 toolbars etc.
• machine-readable detailed listing
• year summary: lectionary cycles, movable feasts
• configuration file to set default options
• specify calendar data path (with support for layering several calendars)
• option to auto-select one of optional celebrations - with multiple supported strategies (prefer ferial, take first non-ferial, configured whitelist, blacklist)
• integrate online data sources

Backward compatibility

Project adheres to semantic versioning with regard to the command line interface: between major releases, the same configuration (through command line options and other ways of configuration the application will eventually support) should print information of the same (or greater) level of detail for the same range of dates. For output formats explicitly documented as machine-readable, format must be preserved (where some machine-readable formats, especially the structured ones, allow backward-compatible extensions, others do not, according to their nature).

No backward compatibility is guaranteed on the level of the application's internal interfaces, since they are not intended to be used by third-party code.

CLI patterns

When designing new elements (options, arguments) of the command line interface

• (BSD version of) cal should be mimicked where reasonable
• the Command-Line Options chapter from E. S. Raymond's The Art of Unix Programming should be consulted in the rest of cases

License

GNU/GPL 3.0 or later

calrom's Issues

Help: describe formats

calrom --help should not only enumerate supported values of the --format option, but also provide a concise explanation what each of them means.

Sanctorale data in configuration file

There should be a way to provide inline sanctorale data directly in the .calromrc configuration file.

Typical use case is calendar of a local church, which usually has only one or two proper celebrations. Currently the only way is to create a separate sanctorale data file and reference it using the --calendar= option.

Add condensed output format

As specified in the project roadmap:

condensed format (but with detailed information) suitable for awesome/i3 toolbars etc.

It should fit all important information regarding a liturgical day in a single line of no more than 30 characters (the less the better) and be well readable even with colours disabled.

While it's mostly intended for displaying single-day date ranges, it should produce meaningful (not necessarily beautiful) output for any valid date range.

Where to start: For existing output formats see features/main_modes.feature (commonly used output formats can be invoked by dedicated options) and features/machine_readable_output.feature (any output format can be invoked by the --format= option).

[BC] Remove output formats not displaying calendar data

Currently there are some synonym options resulting in the same output

• --format=calendars and --calendars
• --format=easter and --easter

That's unfortunate, because the semantics of --calendars and --easter are quite different from the rest of the --format=... options. --format should only be used to select a formatter operating on any given date range and actually displaying calendar data for that date range (not a listing of supported calendars, which is not dependent on the date range at all, or easter date for a single year). --format=calendars and --format=easter should not be available.

Crash when `--easter` is combined with a date range

Invocations like calrom --easter 2010-01-01 2050-12-30 or calrom --easter -3 - in fact any invocation specifying a date range other than a single year - result in an unhandled exception.

Related to #10

Specifying date range: add cal-like options -B and -A

From (an older version of) the cal man page:

-A number
             Months to add after. The specified number of months is added to the end of the display. This is in addition to any date range selected by the
             -y, -3, or -1 options. For example, “cal -y -B2 -A2” shows everything from November of the previous year to February of the following year.
             Negative numbers are allowed, in which case the specified number of months is subtracted. For example, “cal -y -B-6” shows July to December.
             And “cal -A11” simply shows the next 12 months.

-B number
             Months to add before. The specified number of months is added to the beginning of the display. See -A for examples.

Where to start:

• Start by adding to features/date_range_formats.feature a new scenario using one of the options and making it pass; then add another.
• Describe effects of each of the new options in spec/option_parser_spec.rb

README: add animated gif with usage examples

It would be neat to have in the README an animated gif quickly showing the main use cases, i.e. mostly the execution scenarios currently listed in the README. Here is how to do it.

Eventually I will create one myself, but for the time being let this issue be here as a memo for myself and as a help request for anyone who may happen to be willing to contribute such a gif.

Detailed output format

display all the contents of CalendariumRomanum::Day in a human-friendly layout

Specifying date range: add cal-like option -3

From the cal man page:

-3    Display the previous, current and next month surrounding today.

Where to start: for existing options and arguments specifying date range see features/date_range_formats.feature

Options to print only temporale/sanctorale celebrations

(instead of a properly built calendar, correctly combining both cycles and resolving conflicts)

New date range: liturgical year

analogous to -y / --year, but observing liturgical year boundaries

List of movable feasts

There should be a way to obtain a list of movable feasts (similar to the one traditionally printed at the front of missals and breviaries) for any given year.

Support custom calendar implementations

calrom should provide the advanced users some way to use their own calendar implementations (like czech_old_catholic_calendar or the Anglican Ordinariates calendar), instead of or alongside with calendarium-romanum, as long as they are API-compatible with calendarium-romanum.

Can't show calendar for month of December

calrom -m 12 fails with the following error:

Traceback (most recent call last):
        7: from /home/$USER/.gem/ruby/2.5.0/bin/calrom:23:in `<main>'
        6: from /home/$USER/.gem/ruby/2.5.0/bin/calrom:23:in `load'
        5: from /home/$USER/.gem/ruby/2.5.0/gems/calrom-0.1.0/exe/calrom:7:in `<top (required)>'
        4: from /home/$USER/.gem/ruby/2.5.0/gems/calrom-0.1.0/lib/calrom/cli.rb:4:in `call'
        3: from /home/$USER/.gem/ruby/2.5.0/gems/calrom-0.1.0/lib/calrom/option_parser.rb:45:in `call'
        2: from /home/$USER/.gem/ruby/2.5.0/gems/calrom-0.1.0/lib/calrom/option_parser.rb:45:in `new'
        1: from /home/$USER/.gem/ruby/2.5.0/gems/calrom-0.1.0/lib/calrom/date_range.rb:17:in `initialize'
/home/$USER/.gem/ruby/2.5.0/gems/calrom-0.1.0/lib/calrom/date_range.rb:17:in `new': invalid date (ArgumentError)

(wherein I replaced my username with $USER)

The same thing happens if you also specify a year, e.g. calrom -m 12 2021.