calrom 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 2f2a47dec05e4ed520cbe19a3057f8b2a2846659
-  data.tar.gz: 26d20de0bb41c7054a20c22c0b5cbcd44e57e130
+SHA256:
+  metadata.gz: c2e561032a6b91d68a87839856d8ce94b794187a539ac544fc907cfd2568add7
+  data.tar.gz: 8c9ab4bbdc83cc0c9884dbb4fb9f658c578e83956ce63da45b8698f59c55124f
 SHA512:
-  metadata.gz: 1a8246694c98d8525a693b2afc72170205c715a59b79877c8e5b805846dc394e69be9b71bce65a5b50b56d22916f84610932140483ca1ed50577fcb5c708f1bc
-  data.tar.gz: 48f9f4df5a0d75f8eed66520c48b27173f10eb16dd17a7b0f685435d2e6f117dbd97af15cda3b4406ea3290839da81244895fc68cdb57b8fb78abfe29d4c729b
+  metadata.gz: e49e7f177d74b28c08ad6bd6ea25c4579857a6ca16ec68483b8fa4e1ad62807754f7010aad598ee156f728e94fd203042ae31f669f187b6ca52f3abcc0a2eec3
+  data.tar.gz: 2d416f813d7e688b1e855dcb28f27ba47002118c7de8d526ef8b86cd9571edd1bde6fdd9c0eb4c40a23bae75ab17fa66df43a7628b8f3d5ac5d29fd0be7b8bf7

data/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  specs:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # oldest supported and newest MRI
+        # TODO: versions known to have worked back in Travis days; update needed
+        ruby-version:
+          - 2.5.0
+          - 3.0.0
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+      - name: Set up Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+      - name: Install dependencies
+        run: bundle install --jobs=3
+      - name: Run tests
+        run: bundle exec rake

data/.travis.yml

@@ -1,5 +1,15 @@
-sudo: false
 language: ruby
+
+dist: focal
+
+# oldest supported and newest MRI
 rvm:
-  - 2.3.1
-before_install: gem install bundler -v 1.13.6
+  - 2.5.0
+  - 3.0.0
+
+install: bundle install --jobs=3
+
+script: bundle exec rake
+
+git:
+  depth: 3

data/CHANGELOG.md

@@ -1,5 +1,102 @@
 # 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
+
+- date range selection: options `--today`, `--tomorrow`, `--yesterday`
+- specifying the `--calendar=` option multiple times layers the calendars
+- file path can be provided as argument to the `--calendar=` option
+- option `--locale=` to specify language of localized calendar strings
+- language of the (last loaded) sanctorale data is by default used for localized strings
+- output is by default not colorized when not printing to a terminal
+- configuration files
+  - `/etc/calromrc`
+  - `$HOME/.calromrc`
+  - specified by the `--config=` option
+- machine-readable output formats `--format=csv`, `--format=json`
+- option `--calendars` to list bundled calendars
+
+### Fixed
+
+- crash on option parsing errors other than invalid option
+
+## [0.2.0] 2020-06-16
+
+### Added
+
+- cal-like view (is now default for month, year and date range listing)
+- support more cal-like ways of specifying date range
+  - month argument `calrom MONTH YEAR` (as an alternative to month option `cal -m MONTH YEAR`)
+  - month option with p/f flag `calrom -m 5p` / `calrom -m 5f` as a shortcut to specify a month of the previous/following year
+  - option to print the whole current year `calrom -y`
+- support arbitrary date range specified as two ISO dates
+- input is validated, errors handled and reported
+- cal-like option to print (only) the date of Easter
+- cal-like debugging options `-d` and `-H`
+- option `--[no-]color` to enable/disable ANSI colours (enabled by default)
+
+### Changed
+
+- list view: contains weekday names; month names instead of month numbers
+
+### Fixed
+
+- unhandled edge-case in `Calrom::Month` when dealing with the end of a year
+- liturgical colour violet
+
 ## [0.1.0] 2019-10-05
 
 ### Added

data/README.md

@@ -1,5 +1,8 @@
 # calrom
 
+![Build Status](https://github.com/calendarium-romanum/calrom/actions/workflows/ci.yml/badge.svg)
+[![Gem Version](https://badge.fury.io/rb/calrom.svg)](https://badge.fury.io/rb/calrom)
+
 Command line utility providing access to the Roman Catholic
 liturgical calendar (post-Vatican II).
 
@@ -9,22 +12,190 @@ Built on top of the [calendarium-romanum][caro] Ruby gem.
 
 calrom is a Ruby gem:
 
-`gem install calrom`
+`$ 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 `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:
+
+`$ 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][carodata] 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](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:
+
+`$ calrom --format=json` - prints JSON array containing one object per day.
+The object contents mimick output of the [Church Calendar API v0][calapidoc].
+
+`$ 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:
+
+```bash
+# 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][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
+
+`$ 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
+* [x] detailed listing of a day/month/year/range of dates
+* [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.
-* [ ] machine-readable detailed listing
+* [x] condensed format (but with detailed information) suitable for awesome/i3 toolbars etc.
+* [x] 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)
+* [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
 
@@ -51,7 +222,7 @@ 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
@@ -59,6 +230,10 @@ command line interface
 GNU/GPL 3.0 or later
 
 [caro]: https://github.com/igneus/calendarium-romanum
+[carodata]: https://github.com/igneus/calendarium-romanum/tree/master/data
+[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

data/Rakefile

@@ -1,6 +1,10 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "cucumber/rake/task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+Cucumber::Rake::Task.new
+
+desc 'runs all tests'
+task :default => [:spec, :cucumber]

data/calrom.gemspec

@@ -20,10 +20,11 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'calendarium-romanum', '~> 0.6.0'
+  spec.add_dependency 'calendarium-romanum', '~> 0.9.0'
+  spec.add_dependency 'calendarium-romanum-remote', '~> 0.3.0'
   spec.add_dependency 'colorize', '~> 0.8'
+  spec.add_dependency 'pattern-match', '~> 1.0'
 
-  spec.add_development_dependency 'bundler', '~> 1.13'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'cucumber', '~> 1.3'

data/lib/calrom/cli.rb

@@ -1,16 +1,75 @@
 module Calrom
   class CLI
     def self.call(argv)
-      config = OptionParser.call argv
-      calendar = config.calendar
+      begin
+        config_files = OptionParser.call(argv).configs
 
-      enumerator = Enumerator.new do |yielder|
-        config.date_range.each do |date|
-          yielder.yield calendar[date]
-        end
+        config = EnvironmentReader.call
+        config = OptionParser.call(
+          rc_options(config_files.empty? ? nil : config_files) +
+          argv,
+          config
+        )
+
+        calendar = config.calendar
+      rescue OptionParser::Error, InputError => e
+        STDERR.puts e.message
+        exit 1
       end
 
-      config.formatter.call enumerator, config.date_range
+      begin
+        I18n.locale = config.locale
+      rescue I18n::InvalidLocale
+        locales_help = I18n.available_locales.join(', ')
+        STDERR.puts "Locale '#{config.locale}' unsupported (available locales: #{locales_help})"
+        exit 1
+      end
+
+      unless config.verbose
+        HTTPI.log = false
+      end
+
+      begin
+        config.build_formatter.call calendar, config.date_range
+      rescue CR::Remote::UnexpectedResponseError => e
+        STDERR.puts "Remote calendar query failed: #{e.message}"
+        exit 1
+      rescue InputError => e
+        STDERR.puts e.message
+        exit 1
+      rescue Errno::EPIPE
+        # broken pipe - simply stop execution, exit successfully
+      end
+    end
+
+    private
+
+    # options loaded from configuration files
+    def self.rc_options(paths = nil)
+      return [] if paths == ['']
+
+      paths ||=
+        ['/etc/calromrc', '~/.calromrc']
+          .collect {|f| File.expand_path f }
+          .select {|f| File.file? f }
+
+      paths.collect do |f|
+        begin
+          content = File.read(f)
+        rescue Errno::ENOENT
+          raise InputError.new("Configuration file \"#{f}\" not found")
+        end
+
+        options = RcParser.call content
+
+        begin
+          OptionParser.call(options)
+        rescue OptionParser::Error => e
+          raise InputError.new("Error loading '#{f}': #{e.message}")
+        end
+
+        options
+      end.flatten
     end
   end
 end

data/lib/calrom/config.rb

@@ -1,18 +1,150 @@
 module Calrom
   class Config
+    DEFAULT_DATA = CR::Data::GENERAL_ROMAN_ENGLISH
+    DEFAULT_LOCALE = :en
+
     def initialize
       self.today = Date.today
-      self.date_range = CR::Util::Month.new(today.year, today.month)
+      self.date_range = Month.new(today.year, today.month)
+      self.sanctorale = []
+      self.configs = []
+      self.verbose = false
+      self.highlight = Set.new(%i(colour rank today))
+      self.transfer_to_sunday = []
+      self.temporale_extensions = []
+      self.filter_days = []
+      self.filter_celebrations = []
     end
 
-    attr_accessor :today, :date_range
+    ATTRIBUTES = [
+      :today,
+      :date_range,
+      :formatter,
+      :colours,
+      :sanctorale,
+      :transfer_to_sunday,
+      :temporale_extensions,
+      :locale,
+      :configs,
+      :load_parents,
+      :highlight,
+      :verbose,
+      :filter_days,
+      :filter_celebrations,
+    ]
+
+    attr_accessor *ATTRIBUTES
+
+    def ==(b)
+      self.class == b.class &&
+        ATTRIBUTES.all? {|prop| public_send(prop) == b.public_send(prop) }
+    end
 
     def calendar
-      CR::PerpetualCalendar.new(sanctorale: CR::Data::GENERAL_ROMAN_ENGLISH.load)
+      calendar =
+        if is_remote_calendar?
+          if @sanctorale.size > 1
+            raise InputError.new '--calendar option provided multiple times, but at least one of the calendars is remote. Remote calendars cannot be layered.'
+          end
+
+          CR::Remote::Calendar.new date_range.first.year, @sanctorale.last
+        else
+          CR::PerpetualCalendar.new(sanctorale: build_sanctorale, temporale_options: temporale_options, vespers: true)
+        end
+
+      FilteringCalendar.new(
+        calendar,
+        filter_days,
+        filter_celebrations,
+      )
+    end
+
+    def build_sanctorale
+      if @sanctorale.empty?
+        return DEFAULT_DATA.load
+      end
+
+      data = @sanctorale.collect do |s|
+        expanded = File.expand_path s
+
+        if s == '-'
+          CR::SanctoraleLoader.new.load_from_string STDIN.read
+        else
+          data_file =
+            if File.file? expanded
+              SanctoraleFile.new expanded
+            elsif CR::Data[s]
+              CR::Data[s]
+            else
+              raise InputError.new "\"#{s}\" is neither a file, nor a valid identifier of a bundled calendar. " +
+                                   "Valid identifiers are: " +
+                                   CR::Data.each.collect(&:siglum).inspect
+            end
+
+          if load_parents?
+            data_file.load_with_parents
+          else
+            data_file.load
+          end
+        end
+      end
+
+      CR::SanctoraleFactory.create_layered(*data)
+    end
+
+    def temporale_options
+      {transfer_to_sunday: transfer_to_sunday, extensions: temporale_extensions}
+    end
+
+    def locale
+      @locale || locale_in_file_metadata || DEFAULT_LOCALE
+    end
+
+    def build_formatter
+      highlighter = Highlighter::List
+      klass = @formatter && Formatter.const_get(@formatter.capitalize)
+
+      if @formatter.nil?
+        klass = date_range.is_a?(Day) ? Formatter::List : Formatter::Overview
+      end
+
+      if [Formatter::Calendars, Formatter::Overview].include? klass
+        highlighter = Highlighter::Overview
+      end
+
+      klass.new build_highlighter(highlighter), today
+    end
+
+    def build_highlighter(colourful)
+      if (self.colours == false || (self.colours.nil? && !STDOUT.isatty))
+        return Highlighter::No.new
+      end
+
+      Highlighter::Selective.new highlight, colourful.new
+    end
+
+    # Should calendars be loaded including parent files they reference?
+    def load_parents?
+      load_parents == true ||
+        (load_parents.nil? && @sanctorale.size == 1)
+    end
+
+    def highlight
+      if date_range.is_a? Day
+        @highlight - [:today]
+      else
+        @highlight
+      end
+    end
+
+    private
+
+    def locale_in_file_metadata
+      is_remote_calendar? ? nil : build_sanctorale.metadata['locale']&.to_sym
     end
 
-    def formatter
-      Formatter::List.new Highlighter::List.new, today
+    def is_remote_calendar?
+      !!@sanctorale.find {|s| s =~ /^https?:\/\// }
     end
   end
 end