{"id":13708428,"url":"https://github.com/calendarium-romanum/calrom","last_synced_at":"2025-05-06T13:30:25.169Z","repository":{"id":56307784,"uuid":"212888607","full_name":"calendarium-romanum/calrom","owner":"calendarium-romanum","description":"liturgical calendar for the command line","archived":false,"fork":false,"pushed_at":"2023-02-09T13:41:28.000Z","size":152,"stargazers_count":10,"open_issues_count":11,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-27T09:52:02.555Z","etag":null,"topics":["calendar","church","cli-app","hacktoberfest","liturgy","ruby","ruby-gem"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/calendarium-romanum.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-04T19:29:59.000Z","updated_at":"2025-01-02T05:58:19.000Z","dependencies_parsed_at":"2024-11-19T21:15:52.124Z","dependency_job_id":null,"html_url":"https://github.com/calendarium-romanum/calrom","commit_stats":{"total_commits":171,"total_committers":2,"mean_commits":85.5,"dds":0.005847953216374324,"last_synced_commit":"79537ab97a3e604223867d018f9df447453490e5"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calendarium-romanum%2Fcalrom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calendarium-romanum%2Fcalrom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calendarium-romanum%2Fcalrom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calendarium-romanum%2Fcalrom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/calendarium-romanum","download_url":"https://codeload.github.com/calendarium-romanum/calrom/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252693478,"owners_count":21789696,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["calendar","church","cli-app","hacktoberfest","liturgy","ruby","ruby-gem"],"created_at":"2024-08-02T23:00:22.533Z","updated_at":"2025-05-06T13:30:24.790Z","avatar_url":"https://github.com/calendarium-romanum.png","language":"Ruby","funding_links":[],"categories":["Applications","Liturgy","Línea de comandos"],"sub_categories":["St. Thomas Aquinas"],"readme":"# calrom\n\n![Build Status](https://github.com/calendarium-romanum/calrom/actions/workflows/ci.yml/badge.svg)\n[![Gem Version](https://badge.fury.io/rb/calrom.svg)](https://badge.fury.io/rb/calrom)\n\nCommand line utility providing access to the Roman Catholic\nliturgical calendar (post-Vatican II).\n\nBuilt on top of the [calendarium-romanum][caro] Ruby gem.\n\n## Installation\n\ncalrom is a Ruby gem:\n\n`$ gem install calrom`\n\n## Usage\n\n### Specifying date range\n\nPrint liturgical calendar for the current month (default):\n\n`$ calrom`\n\n... for a specified month of the current year:\n\n`$ calrom -m 9`\n\n... for a specified month of another year:\n\n`$ calrom -m 1 2028` or `$ calrom 1 2028`\n\n... for a whole year:\n\n`$ calrom 2017`\n\n... for the current year:\n\n`$ calrom -y`\n\n... for a specified date:\n\n`$ calrom 2028-01-15`\n\n... for an arbitrary date range:\n\n`$ calrom 2028-01-15 2028-03-07`\n\n### Day and celebration filtering\n\nIn addition to specifying date range, filtering is a way to further refine\nthe selection of data to be displayed. Options `--day-filter=` and `--celebration-filter=`\nboth accept a snippet of Ruby code, which is then `eval`ed in context of each\n`CalendariumRomanum::Day` / `CalendariumRomanum::Celebration` within the selected date range\nand only days/celebrations for which the expression evaluates truthy are displayed.\n\nDisplay only Saturdays:\n\n`$ calrom --day-filter='date.saturday?'`\n\nDisplay all Mondays with a celebration of a rank higher than memorial:\n\n`$ calrom --day-filter='date.monday?' --day-filter='celebrations[0].rank \u003e MEMORIAL_GENERAL'`\n\n(As you can see, `calendarium-romanum` constants like ranks or seasons are available\nas top-level constants. Noone likes extensive writing in the terminal.)\n\nDisplay only ferials:\n\n`$ calrom --celebration-filter='ferial?'`\n\nDisplay only celebrations in green:\n\n`$ calrom --celebration-filter='colour == GREEN'`\n\nThe options can be combined and used repeatedly to narrow the selection down as needed.\n\n### Selecting calendar\n\nThere are a few calendars bundled in calrom (actually in the calendarium-romanum gem)\nand ready to use. List them:\n\n`$ calrom --calendars`\n\nEach entry of the listing contains an ID of the calendar, it's name and language code.\nUse calendar ID to request General Roman Calendar in Latin:\n\n`$ calrom --calendar=universal-la`\n\nYou can prepare [your own calendar data][carodata] and load them:\n\n`$ calrom --calendar=path/to/my_calendar.txt`\n\nIf you specify more than one calendar, they are loaded \"layered\" one over another\n(from left to right), which comes in handy when extending a general calendar\nwith just a few additional and/or differing celebrations, e.g. solemnities (titular, dedication)\nof the local church:\n\n`$ calrom --calendar=universal-la --calendar=path/to/our_local_celebrations.txt`\n\nPlease note that specifying more than one calendar disables automatic loading of\nparent calendars. If any of the listed calendars extends a parent calendar,\nthe parent either has to be explicitly listed using the `--calendar` option in order to be loaded,\nor automatic parent loading has to be explicitly enabled using the `--load-parents` option.\n\nLimited support for remote calendars is provided. Calendar URL from the\n[Liturgical Calendar API](http://calapi.inadiutorium.cz/) or a compatible calendar API\nis accepted as a value of `--calendar=`:\n\n`$ calrom --calendar=http://calapi.inadiutorium.cz/api/v0/en/calendars/general-la`\n\n### Data presentation settings\n\nPrint detailed listing:\n\n`$ calrom -l`\n\nPrint current day in a condensed format (intended mainly for use cases like\nwindow manager toolbars):\n\n`$ calrom --format=condensed --today`\n\nDisable colours:\n\n`$ calrom --no-color`\n\nMachine-readable output formats:\n\n`$ calrom --format=json` - prints JSON array containing one object per day.\nThe object contents mimick output of the [Church Calendar API v0][calapidoc].\n\n`$ calrom --format=csv` - prints a CSV, one celebration per line\n(i.e. there is one or more lines for each liturgical day).\n\n### Configuration files\n\n`calrom` looks for configuration files `/etc/calromrc` and `~/.calromrc`.\nThey are processed in this order and both are used if available.\nTheir syntax is that of shell options and arguments (with the sole exception that newline\nis not considered end of shell input, but generic whitespace), supported are all options and arguments\naccepted by the command.\n\nIf a custom configuration file location is specified on the command line,\n`$ calrom --config=path/to/my/custom/config`, the standard system-wide and user-specific configuration\nfiles are *not* loaded. Empty config path `$ calrom --config=` makes calrom ignore all configuration\nfiles and use the built-in default configuration.\n\nExample configuration file, loading the proper calendar of the archdiocese of Prague\nand disabling colours:\n\n```bash\n# shell-like comments can be used in configuration files\n\n--calendar=czech-praha-cs # calendar of the archdiocese of Prague\n--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)\n\n--load-parents # load also parent calendars specified by the calendar file(s)\n               # (default if just one calendar file is specified, but we specified two)\n\n--no-color # disable colours\n```\n\n(Configuration file format is inspired by [.rspec][dotrspec], [.yardopts][dotyardopts]\nand others.)\n\nMost options work in such a way that if several conflicting options are provided,\nthe last one wins. You can thus e.g. set your favourite display format (e.g. `--list`)\nor date range (e.g. `-3`) in the configuration file and override it, if necessary,\nby providing some other option from the same group on the command line.\nAn exception from this rule is the `--calendar=` option, repeated occurrences of which\ndo not cancel each other, but are all composed together in the given order to build a calendar\nby layering.\nAlso repeated occurrences of the `--day-filter=` and `--celebration-filter=` options\ndon't cancel each other, but all specified filtering expressions are applied.\n\n## Running tests\n\nClone the repository, `$ bundle install` to install dependencies, then:\n\n`$ rake cucumber` - run specs describing the command line interface\n\n`$ rake spec` - run specs describing internal implementation details\n\n`$ rake` - run all groups of specs one after another\n\n## Project roadmap\n\n* [x] detailed listing of a day/month/year/range of dates\n* [x] month/year overview - options and output mostly mimicking\n  the BSD Unix [`cal`][cal] utility,\n  but with liturgical colours and celebration ranks\n* [x] condensed format (but with detailed information) suitable for awesome/i3 toolbars etc.\n* [x] machine-readable detailed listing\n* [ ] year summary: lectionary cycles, movable feasts\n* [x] configuration file to set default options\n* [x] specify calendar data path (with support for layering several calendars)\n* [ ] option to auto-select one of optional celebrations - with multiple supported strategies (prefer ferial, take first non-ferial, configured whitelist, blacklist)\n* [ ] integrate online data sources\n\n## Backward compatibility\n\nProject adheres to [semantic versioning][semver]\nwith regard to the command line interface:\nbetween major releases,\nthe same configuration (through command line options and other\nways of configuration the application will eventually support)\nshould print information of the same (or greater) level of detail\nfor the same range of dates.\nFor output formats explicitly documented as machine-readable,\nformat must be preserved (where some machine-readable\nformats, especially the structured ones, allow backward-compatible\nextensions, others do not, according to their nature).\n\nNo backward compatibility is guaranteed on the level of the application's\ninternal interfaces, since they are not intended to be used\nby third-party code.\n\n## CLI patterns\n\nWhen designing new elements (options, arguments) of the\ncommand line interface\n\n* [(BSD version of) `cal`][cal] should be mimicked where reasonable\n* the [Command-Line Options][taoup] chapter from E. S. Raymond's\n  *The Art of Unix Programming* should be consulted in the rest\n  of cases\n\n## License\n\nGNU/GPL 3.0 or later\n\n[caro]: https://github.com/igneus/calendarium-romanum\n[carodata]: https://github.com/igneus/calendarium-romanum/tree/master/data\n[calapidoc]: http://calapi.inadiutorium.cz/api-doc\n[semver]: https://semver.org/\n[cal]: https://www.freebsd.org/cgi/man.cgi?query=cal\n[taoup]: http://www.catb.org/esr/writings/taoup/html/ch10s05.html\n[dotrspec]: https://relishapp.com/rspec/rspec-core/v/2-0/docs/configuration/read-command-line-configuration-options-from-files\n[dotyardopts]: https://rubydoc.info/gems/yard/file/docs/GettingStarted.md#yardopts-options-file\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcalendarium-romanum%2Fcalrom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcalendarium-romanum%2Fcalrom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcalendarium-romanum%2Fcalrom/lists"}