calrom 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8080fbff35aedfe1af84126ea841c66f8f3a36a513bc89b4a5f2a736a7b3205f
-  data.tar.gz: c0ff3d64def3e7b227ba4f64e145e0c589c449ec516a04d82a2252d7d4456bf3
+  metadata.gz: d42310796615e6626842e77d06cf282159c50ce621910d7c44f61cfdc0de91ae
+  data.tar.gz: eb40b6b35e68543447d12ebb1ca91be7212a07c92e392ce50cc994b48e9103c7
 SHA512:
-  metadata.gz: 0cf9192362ddd378d703835fab6861e72c8cfd080a7320207bf8e02366898f75152bc8b036709685f0008b5e1afea91b064e6b620f5dedc54e4f797ff0fa5a8e
-  data.tar.gz: cf71e5c86049312c0568d725e0d236e57e9ad0cd205f729f8740af0922d30a4f2f028548abfdc1bc69ee30fcc6fc23f4dc6278ceafce9ac6774a97af3f1abd11
+  metadata.gz: 66a58f4609c50cd65f581bf9cbc8e8c52c2d7330b475d0d45fd0cec9cf6c63d16259c2bbaf83bfde1726486bf8916edc399dd0b9e70287882e34b461fa0f010f
+  data.tar.gz: 7dd18b19ba33a6caa6da2ebb08eedcd0ca12ebcb56f8500e75c35acd61509bfcfe53541608937c205677bd3ad36c951aff197ef02915f020721051a652b8a304

data/CHANGELOG.md

@@ -1,6 +1,27 @@
 # Changelog
 
-## [0.2.0] 2020-01-14
+## [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
 

data/README.md

@@ -46,6 +46,29 @@ Print liturgical calendar for the current month (default):
 
 `$ calrom 2028-01-15 2028-03-07`
 
+### 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`
+
 ### Data presentation settings
 
 Print detailed listing:
@@ -56,6 +79,45 @@ 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.
+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.
+
+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)
+
+--no-color # disable colours
+```
+
+(Configuration file format is inspired by [.rspec][dotrspec].)
+
 ## Running tests
 
 Clone the repository, `$ bundle install` to install dependencies, then:
@@ -69,14 +131,14 @@ Clone the repository, `$ bundle install` to install dependencies, then:
 ## Project roadmap
 
 * [x] detailed listing of a day/month/year/range of dates
-* [ ] month/year overview - options and output mostly mimicking the
+* [ ] 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] 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
@@ -114,6 +176,9 @@ 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

data/lib/calrom.rb

@@ -10,11 +10,15 @@ require 'calrom/cli'
 require 'calrom/option_parser'
 require 'calrom/config'
 require 'calrom/date_range'
+require 'calrom/rc_parser'
 require 'calrom/exceptions'
 require 'calrom/formatter/formatter'
 require 'calrom/formatter/list'
 require 'calrom/formatter/overview'
+require 'calrom/formatter/csv'
+require 'calrom/formatter/json'
 require 'calrom/formatter/easter'
+require 'calrom/formatter/calendars'
 require 'calrom/highlighter/no'
 require 'calrom/highlighter/list'
 require 'calrom/highlighter/overview'

data/lib/calrom/cli.rb

@@ -2,15 +2,52 @@ module Calrom
   class CLI
     def self.call(argv)
       begin
-        config = OptionParser.call argv
-      rescue ::OptionParser::InvalidOption, InputError => e
+        config_files = OptionParser.call(argv).configs
+
+        config = OptionParser.call(
+          rc_options(config_files.empty? ? nil : config_files) +
+          argv
+        )
+
+        calendar = config.calendar
+      rescue ::OptionParser::ParseError, InputError => e
         STDERR.puts e.message
         exit 1
       end
 
-      calendar = config.calendar
+      I18n.locale = config.locale
 
       config.formatter.call calendar, config.date_range
     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::ParseError => e
+          raise InputError.new("Error loading '#{f}': #{e.message}")
+        end
+
+        options
+      end.flatten
+    end
   end
 end

data/lib/calrom/config.rb

@@ -1,14 +1,45 @@
 module Calrom
   class Config
+    DEFAULT_DATA = CR::Data::GENERAL_ROMAN_ENGLISH
+    DEFAULT_LOCALE = :en
+
     def initialize
       self.today = Date.today
       self.date_range = Month.new(today.year, today.month)
+      self.sanctorale = []
+      self.configs = []
     end
 
-    attr_accessor :today, :date_range, :formatter, :colours
+    attr_accessor :today, :date_range, :formatter, :colours, :sanctorale, :locale, :configs
 
     def calendar
-      CR::PerpetualCalendar.new(sanctorale: CR::Data::GENERAL_ROMAN_ENGLISH.load)
+      CR::PerpetualCalendar.new(sanctorale: build_sanctorale)
+    end
+
+    def build_sanctorale
+      if @sanctorale.empty?
+        return DEFAULT_DATA.load
+      end
+
+      data = @sanctorale.collect do |s|
+        if s == '-'
+          CR::SanctoraleLoader.new.load_from_string STDIN.read
+        elsif File.file? s
+          CR::SanctoraleLoader.new.load_from_file s
+        elsif CR::Data[s]
+          CR::Data[s].load
+        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
+      end
+
+      CR::SanctoraleFactory.create_layered(*data)
+    end
+
+    def locale
+      @locale || locale_in_file_name || DEFAULT_LOCALE
     end
 
     def formatter
@@ -16,17 +47,31 @@ module Calrom
         Formatter::List.new highlighter(Highlighter::List), today
       elsif @formatter == :easter
         Formatter::Easter.new
+      elsif @formatter == :calendars
+        Formatter::Calendars.new highlighter(Highlighter::Overview), today
+      elsif @formatter == :csv
+        Formatter::Csv.new
+      elsif @formatter == :json
+        Formatter::Json.new
       else
         Formatter::Overview.new highlighter(Highlighter::Overview), today
       end
     end
 
     def highlighter(colourful)
-      if self.colours == false
+      if (self.colours == false || (self.colours.nil? && !STDOUT.isatty))
         return Highlighter::No.new
       end
 
       colourful.new
     end
+
+    private
+
+    def locale_in_file_name
+      locale = (sanctorale.last || DEFAULT_DATA.siglum).split('-').last&.to_sym
+
+      I18n.available_locales.include?(locale) ? locale : nil
+    end
   end
 end

data/lib/calrom/formatter/calendars.rb

@@ -0,0 +1,22 @@
+require 'yaml'
+
+module Calrom
+  module Formatter
+    # Prints list of available bundled calendars
+    class Calendars < Formatter
+      def call(calendar, date_range)
+        last_locale = nil
+        CR::Data.each do |d|
+          meta = load_front_matter d
+          puts if last_locale && last_locale != meta['locale']
+          puts "%-20s:  %s  [%s]" % [d.siglum, meta['title'], meta['locale']]
+          last_locale = meta['locale']
+        end
+      end
+
+      def load_front_matter(data_file)
+        YAML.load File.read data_file.path
+      end
+    end
+  end
+end

data/lib/calrom/formatter/csv.rb

@@ -0,0 +1,28 @@
+require 'csv'
+
+module Calrom
+  module Formatter
+    class Csv
+      def call(calendar, date_range)
+        CSV do |out|
+          out << %w(date title symbol rank rank_num colour season)
+
+          date_range.each do |date|
+            day = calendar[date]
+            day.celebrations.each do |c|
+              out << [
+                day.date,
+                c.title,
+                c.symbol,
+                c.rank.short_desc,
+                c.rank.priority,
+                c.colour.symbol,
+                day.season.symbol
+              ]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/calrom/formatter/easter.rb

@@ -7,7 +7,7 @@ module Calrom
           raise 'unexpected date range, expected a year'
         end
 
-        puts CalendariumRomanum::Temporale::Dates
+        puts CR::Temporale::Dates
                .easter_sunday(date_range.first.year - 1)
                .strftime('%D')
       end

data/lib/calrom/formatter/json.rb

@@ -0,0 +1,38 @@
+require 'json'
+
+module Calrom
+  module Formatter
+    # JSON format mimicking Church Calendar API v0 (https://github.com/igneus/church-calendar-api)
+    class Json
+      def call(calendar, date_range)
+        # We build the outer JSON Array manually in order to be able to print
+        # vast amounts of calendar data without risking RAM exhaustion.
+        print "["
+
+        date_range.each_with_index do |date, i|
+          day = calendar[date]
+          hash = {
+            date: date,
+            season: day.season.symbol,
+            season_week: day.season_week,
+            celebrations: day.celebrations.collect do |c|
+              {
+                title: c.title,
+                symbol: c.symbol,
+                colour: c.colour.symbol,
+                rank: c.rank.short_desc,
+                rank_num: c.rank.priority
+              }
+            end,
+            weekday: date.strftime('%A'),
+          }
+
+          puts "," if i > 0
+          print JSON.generate hash
+        end
+
+        puts "]"
+      end
+    end
+  end
+end

data/lib/calrom/option_parser.rb

@@ -6,6 +6,12 @@ module Calrom
   class OptionParser
     using PatternMatch
 
+    class CustomizedOptionParser < ::OptionParser
+      def separator(string)
+        super "\n" + string
+      end
+    end
+
     def self.call(argv)
       self.new.call(argv)
     end
@@ -21,16 +27,38 @@ module Calrom
 
       range_type = nil
 
-      opt_parser = ::OptionParser.new do |opts|
-        opts.on('-l', '--list', 'list mode') do
-          config.formatter = :list
-        end
+      opt_parser = CustomizedOptionParser.new do |opts|
+        opts.banner = <<~EOS
+        Usage: calrom [options] [arg1 [arg2]]
 
-        # cal
-        opts.on('-e', '--easter', 'display date of Easter') do
-          config.formatter = :easter
+        Specifying date range (cal/ncal-compatible):
+
+          calrom             - current month
+          calrom -m 5        - May of the current year
+          calrom -m 5p       - May of the previous year
+          calrom -m 5f       - May of the following year
+          calrom -m 5 2000   - May 2000
+          calrom 5 2000      - also May 2000
+          calrom 2000        - whole year 2000
+          calrom -y 2000     - also whole year 2000
+          calrom -y          - whole current year
+
+        Specifying date range (not cal-compatible):
+
+          calrom 2000-05-31              - specified day (only)
+          calrom 2000-05-31 2000-07-01   - arbitrary date range
+          calrom (--yesterday|--today|--tomorrow)
+
+        EOS
+
+        opts.separator 'Configuration files'
+
+        opts.on('--config=CONFIG', 'load configuration from file (may be used multiple times, all specified files will be loaded)') do |value|
+          config.configs << value
         end
 
+        opts.separator 'Options selecting date range'
+
         # cal
         opts.on('-m MONTH', '--month=MONTH', 'display the specified month. \'f\' or \'p\' can be appended to display the same month of the following or previous year respectively') do |value|
           range_type = :month
@@ -47,28 +75,79 @@ module Calrom
           range_type = :year
         end
 
+        opts.on('--yesterday', 'display previous day') do |value|
+          day = Date.today - 1
+          range_type = :day
+        end
+
+        opts.on('--today', 'display current day') do |value|
+          day = Date.today
+          range_type = :day
+        end
+
+        opts.on('--tomorrow', 'display following day') do |value|
+          day = Date.today + 1
+          range_type = :day
+        end
+
+        opts.separator "Options configuring liturgical calendar"
+
+        opts.on('-c CAL', '--calendar=CAL', 'specify (sanctorale) calendar to use. If repeated, layers all specified calendars one over another') do |value|
+          config.sanctorale << value
+        end
+
+        locales_help = I18n.available_locales.join(', ')
+        opts.on('--locale=LOCALE', "override language in which temporale celebration titles are rendered (supported: #{locales_help})") do |value|
+          config.locale = value.to_sym
+        end
+
+        opts.separator 'Options affecting presentation'
+
+        opts.on('-l', '--list', 'display detailed listing of days and celebrations (synonym to --format=list)') do
+          config.formatter = :list
+        end
+
+        supported_formats = %i(overview list csv json)
+        formats_help = supported_formats.join(', ')
+        opts.on('--format=FORMAT', supported_formats, "specify output format (supported: #{formats_help})") do |value|
+          config.formatter = value
+        end
+
+        # cal
+        opts.on('-e', '--easter', 'display date of Easter (only)') do
+          config.formatter = :easter
+        end
+
+        opts.on('--calendars', 'list bundled calendars') do |value|
+          config.formatter = :calendars
+        end
+
+        opts.on('--[no-]color', 'enable/disable colours (enabled by default)') do |value|
+          config.colours = value
+        end
+
+        opts.separator 'Debugging options'
+
         # cal
         opts.on('-d YM', '--current-month=YM', 'use given month (YYYY-MM) as the current month (for debugging of date range selection)') do |value|
           year, month = value.split '-'
         end
 
         # cal
-        opts.on('-H DATE', '--highlight-date=DATE', 'use given date as the current date (for debugging of highlighting') do |value|
+        opts.on('-H DATE', '--highlight-date=DATE', 'use given date as the current date (for debugging of highlighting)') do |value|
           config.today = validate_day value
         end
 
-        opts.on(nil, '--[no-]color', 'enable/disable colours (enabled by default)') do |value|
-          config.colours = value
-        end
+        opts.separator 'Information regarding calrom'
 
-        opts.on_tail(nil, '--version', 'display calrom version') do
+        opts.on('-V', '--version', 'display calrom version') do
           puts 'calrom v' + Calrom::VERSION
           exit
         end
 
         # Normally optparse defines this option by default, but once -H option is added,
         # for some reason -h (if not defined explicitly) is treated as -H.
-        opts.on_tail('-h', '--help', 'display this help') do
+        opts.on('-h', '--help', 'display this help') do
           puts opts
           exit
         end
@@ -138,6 +217,8 @@ module Calrom
     end
 
     def validate_day(day)
+      return day if day.is_a? Date
+
       Date.parse(day)
     rescue ArgumentError
       raise InputError.new("not a valid date #{day}")
@@ -156,7 +237,7 @@ module Calrom
           Month.new(year, month)
         end
 
-      beginning = CalendariumRomanum::Calendar::EFFECTIVE_FROM
+      beginning = CR::Calendar::EFFECTIVE_FROM
       if range.first < beginning
         raise InputError.new("implemented calendar system in use only since #{beginning}")
       end

data/lib/calrom/rc_parser.rb

@@ -0,0 +1,10 @@
+require 'shellwords'
+
+module Calrom
+  # Parses configuration file contents to an ARGV-like Array
+  class RcParser
+    def self.call(content)
+      Shellwords.split(content.gsub(/#.+?$/, ''))
+    end
+  end
+end

data/lib/calrom/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: calrom
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Jakub Pavlík
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-06-16 00:00:00.000000000 Z
+date: 2020-06-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: calendarium-romanum
@@ -133,14 +133,18 @@ files:
 - lib/calrom/config.rb
 - lib/calrom/date_range.rb
 - lib/calrom/exceptions.rb
+- lib/calrom/formatter/calendars.rb
+- lib/calrom/formatter/csv.rb
 - lib/calrom/formatter/easter.rb
 - lib/calrom/formatter/formatter.rb
+- lib/calrom/formatter/json.rb
 - lib/calrom/formatter/list.rb
 - lib/calrom/formatter/overview.rb
 - lib/calrom/highlighter/list.rb
 - lib/calrom/highlighter/no.rb
 - lib/calrom/highlighter/overview.rb
 - lib/calrom/option_parser.rb
+- lib/calrom/rc_parser.rb
 - lib/calrom/version.rb
 homepage: https://github.com/calendarium-romanum/calrom
 licenses: