ncalendar

 1## About
 2
 3This is an implementation of the `calendar(1)` program as available on [many][openbsd calendar] [BSD][freebsd calendar] [variants][netbsd calendar].
 4
 5## Status
 6
 7This is mostly intended as a toy project for experimenting a bit with Rust.
 8The implementation is primarily inspired by the [OpenBSD `calendar(1)` implementation][openbsd calendar] and implements most of its feature.
 9However, the input format is not intended to be fully compatible with OpenBSD.
10
11## Features
12
13* Saner and more strict input format compared to the BSD version
14* Re-usable parser for the input format is provided as a Rust library
15    * Allows building additional tools on top
16    * For example, exporters for other formats
17* Lots of great non-features:
18    * No locale support
19    * No support for Julian or Cyrillic calendars
20    * No built-in support for [national holidays][openbsd ostern.c]
21
22## Installation
23
24This software can be installed using the following commands:
25
26    $ cargo install --path .
27
28This will drop the `ncalendar` binary into `~/.cargo/bin`.
29Make sure that directory is in your `$PATH`.
30
31## Usage
32
33The `ncalendar(1)` program reads calendar entries from the file `~/.ncalendar/calendar` by default.
34The input format for this file is "documented" through [parser combinators][parser combinators wk] in `src/lib/format.rs`.
35When invoked, all calendar entries which match a certain time span are written to standard output.
36By default, entries for the current and the next day are printed.
37The time span can be configured, via the `-B` (backward), `-A` (forward) and `-t` (set different current date) command-line options an.
38For example:
39
40    $ ncalendar -B 3 -A 11 -t 20122022
41
42Will print all calendars in the inclusive range between the 17th December of 2022 and the 31th December.
43The program is best invoked from a daily user-level cronjob.
44
45## Test
46
47Unit tests can be executed using the following command:
48
49    $ cargo test
50
51
52## License
53
54This program is free software: you can redistribute it and/or modify it
55under the terms of the GNU Affero General Public License as published by
56the Free Software Foundation, either version 3 of the License, or (at
57your option) any later version.
58
59This program is distributed in the hope that it will be useful, but
60WITHOUT ANY WARRANTY; without even the implied warranty of
61MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero
62General Public License for more details.
63
64You should have received a copy of the GNU Affero General Public License
65along with this program. If not, see <https://www.gnu.org/licenses/>.
66
67[openbsd calendar]: https://man.openbsd.org/calendar
68[freebsd calendar]: https://www.freebsd.org/cgi/man.cgi?query=calendar
69[netbsd calendar]: https://man.netbsd.org/calendar.1
70[parser combinators wk]: https://en.wikipedia.org/wiki/Parser_combinator
71[openbsd ostern.c]: https://github.com/openbsd/src/blob/47f32dc2b6cade03c63e7f98f4f715cb45238c6e/usr.bin/calendar/ostern.c