README.md in calrom-0.3.0 vs README.md in calrom-0.4.0
- old
+ new
@@ -1,8 +1,8 @@
# calrom
-[](https://travis-ci.org/calendarium-romanum/calrom)
+
[](https://badge.fury.io/rb/calrom)
Command line utility providing access to the Roman Catholic
liturgical calendar (post-Vatican II).
@@ -44,10 +44,39 @@
... 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 `eval`ed 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:
@@ -67,16 +96,32 @@
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](http://calapi.inadiutorium.cz/) 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:
@@ -92,34 +137,44 @@
`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.
-It usually makes sense to use configuration files only for the most fundamental settings
-you will never change, like selecting calendar (if you know you will always check this single one)
-or disabling colours (if you hate colourful output).
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.
+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:
```bash
# shell-like comments can be used in configuration files
---calendar=czech-cs # celebrations common for the whole Czech Republic
---calendar=czech-cechy-cs # Bohemia
---calendar=czech-praha-cs # archdiocese of Prague
---calendar=/home/igneus/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)
+--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][dotrspec].)
+(Configuration file format is inspired by [.rspec][dotrspec], [.yardopts][dotyardopts]
+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
@@ -129,21 +184,20 @@
`$ rake` - run all groups of specs one after another
## Project roadmap
* [x] detailed listing of a day/month/year/range of dates
-* [ ] month/year overview - options and output mostly mimicking
+* [x] month/year overview - options and output mostly mimicking
the BSD Unix [`cal`][cal] utility,
but with liturgical colours and celebration ranks
-* [ ] condensed format (but with detailed information) suitable for awesome/i3 toolbars etc.
+* [x] condensed format (but with detailed information) suitable for awesome/i3 toolbars etc.
* [x] machine-readable detailed listing
* [ ] year summary: lectionary cycles, movable feasts
* [x] configuration file to set default options
* [x] 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
-* [ ] interactive browsing
## Backward compatibility
Project adheres to [semantic versioning][semver]
with regard to the command line interface:
@@ -166,11 +220,11 @@
When designing new elements (options, arguments) of the
command line interface
* [(BSD version of) `cal`][cal] should be mimicked where reasonable
* the [Command-Line Options][taoup] chapter from E. S. Raymond's
- "The Art of Unix Programming" should be consulted in the rest
+ *The Art of Unix Programming* should be consulted in the rest
of cases
## License
GNU/GPL 3.0 or later
@@ -180,5 +234,6 @@
[calapidoc]: http://calapi.inadiutorium.cz/api-doc
[semver]: https://semver.org/
[cal]: https://www.freebsd.org/cgi/man.cgi?query=cal
[taoup]: http://www.catb.org/esr/writings/taoup/html/ch10s05.html
[dotrspec]: https://relishapp.com/rspec/rspec-core/v/2-0/docs/configuration/read-command-line-configuration-options-from-files
+[dotyardopts]: https://rubydoc.info/gems/yard/file/docs/GettingStarted.md#yardopts-options-file