release 0.4.0

CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## [0.4.0] 2022-06-27
+
+### Added
+
+- date range selection: cal-like option `-3` to select the current month together
+  with the preceding and following one (contributed by Fabio Soares @fabiosoaresv)
+- if exactly one sanctorale data file is specified and its YAML front matter
+  references a parent calendar (key `extends`), the file is loaded with its complete
+  graph of parents
+- option `--[no-]load-parents` to explicitly enable/disable loading of parent calendars
+- basic support for remote calendars: the `--calendar=` option now accepts
+  also a calendar API URL like
+  `--calendar=http://calapi.inadiutorium.cz/api/v0/en/calendars/general-la`,
+  the referenced API is expected to be compatible with
+  [Liturgical Calendar API](http://calapi.inadiutorium.cz/) v0
+- calendar listing (`--calendars`) marks default calendar as such
+- calendar listing lists each calendar's parents
+- option `--verbose`
+- condensed view (`--format=condensed`), intended for use cases like printing current day
+  in a window manager toolbar and the like
+- option `--to-sunday=` to configure which temporale solemnities should be transferred to Sunday
+  (e.g. `--to-sunday=epiphany`)
+- option `--temporale-extension=` to activate temporale extension
+  (supported values are [temporale extension](https://github.com/igneus/calendarium-romanum/tree/master/lib/calendarium-romanum/temporale/extensions)
+  class names, e.g. `--temporale-extension=ChristEternalPriest`)
+- any class in the `Calrom::Formatter` module is considered formatter and its
+  lowercased name can be used as value for the `--format=` option - custom formatters
+  can be added by defining new classes in the namespace
+- options `--day-filter=` and `--celebration-filter=` for filtering days and celebrations
+  by a Ruby expression
+- environment variable `CALROM_CURRENT_DATE` can be used to override current date
+  (intended mainly for testing)
+
+### Changed
+
+- automated locale selection based on sanctorale data file relies solely on the `locale` key
+  of the file's YAML front matter (previously it relied on a file naming convention)
+- option `--calendar=` expands tilde in path (if it isn't expanded by shell,
+  as is the case e.g. in configuration files)
+- when displaying just a single day, highlighting of the current day is disabled by default
+  (i.e. if the day being displayed is current day, it won't be highlighted as such)
+- list view (`--list`): rank is not printed for ferials and Sundays
+- overview view always arranges the displayed months in multiple columns, just like `cal`
+  (previously date ranges spanning less than three months were printed in a single column)
+- date range specification: support for dates with year higher than 9999 (e.g. `10000-01-01`)
+
+### Fixed
+
+- crash on invalid value of `--locale`
+- list view: when printing a date range between the same months of different years
+  (e.g. 2000-01-xx .. 2001-01-xx), year was not printed in month headings
+
 ## [0.3.0] 2020-06-21
 
 ### Added

README.md

@@ -46,6 +46,35 @@ Print liturgical calendar for the current month (default):
 
 `$ 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)
@@ -69,6 +98,17 @@ 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:
@@ -99,9 +139,6 @@ 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
@@ -126,6 +163,16 @@ and disabling colours:
 (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:

lib/calrom/version.rb

@@ -1,3 +1,3 @@
 module Calrom
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end