Markup::Calendar

Raku package with Markup (HTML, Markdown) calendar functions for displaying monthly, yearly, and custom calendars.

Motivation

The package "Text::Calendar", [AAp1], provides the core functions for making the calendars in this package. The packages "Data::Translators", [AAp2], and "Pretty::Table", [ULp1], provide additional formatting functionalities.

I want to keep "Text::Calendar" lightweight, without any dependencies. Hence I made this separate package, "Markup::Calendar", that has more involved dependencies and use-cases.

An "involved use case" is calendar in which some of the days have tooltips and hyperlinks.

Installation

From Zef ecosystem:

zef install Markup::Calendar

From GitHub:

zef install https://github.com/antononcube/Raku-Markup-Calendar.git

Examples

Basic HTML calendar

use Markup::Calendar;
use Text::Calendar;

calendar():html

HTML yearly calendar with highlights

Here is an HTML calendar that weekend days are highlighted and with larger font:

calendar-year( 
    per-row => 4, 
    highlight => (Date.new(2024,1,1)...Date.new(2024,12,31)).grep({ $_.day-of-week ≥ 6 }),
    highlight-style => 'color:orange; font-size:14pt'
):html

2026

Standalone calendar file

Here we make a standalone calendar file:

spurt('example.html', calendar-year(year => 2024, highlight => [3=>3, 5=>24, 9=>9], highlight-style=>'color:red', format=>'html'))

# True

CLI

The package provides the Command Line Interface (CLI) script mcal. Here is its usage message:

mcal --help

# Usage:
#   mcal [-y|--year=<Str>] [-m|--months=<Str>] [-h|--highlight=<Str>] [-t|--tooltip=<Str>] [-l|--hyperlink=<Str>] [-s|--highlight-style=<Str>] [--per-row[=UInt]] [--doc|--document] -- Displays a calendar in HTML format.
#   
#     -y|--year=<Str>               Year spec; if an empty string only the months spec is used. [default: '']
#     -m|--months=<Str>             Months spec, comma separated list of integers or month names. [default: 'Whatever']
#     -h|--highlight=<Str>          Highlight spec that is a comma separated list of days. [default: '']
#     -t|--tooltip=<Str>            Tooltip spec. [default: '']
#     -l|--hyperlink=<Str>          Hyperlink spec (per calendar day.) [default: '']
#     -s|--highlight-style=<Str>    Highlight style (HTML style.) [default: 'color:orange; font-…']
#     --per-row[=UInt]              Number of months per row. [default: 3]
#     --doc|--document              Should a complete HTML document be made or not? [default: False]

TODO

• TODO Features
  • DONE HTML
    • DONE Full HTML calendar
    • DONE Partial HTML calendar (e.g. equivalent of cal -3)
    • DONE Highlighted days
    • DONE Tooltips for days
    • DONE Hyperlinks for days
  • TODO Markdown
    • TODO Full Markdown calendar
    • TODO Partial Markdown calendar
    • TODO Highlighted days
    • TODO Tooltips for days
    • TODO Hyperlinks for days
  • CLI
• Unit tests
  • DONE Basic usage
  • DONE Equivalence using different signatures
  • TODO Correctness
• Documentation
  • DONE Basic README
  • TODO Diagrams
  • TODO Comparisons

References

[AAp1] Anton Antonov, Text::Calendar Raku package, (2024), GitHub/antononcube.

[AAp2] Anton Antonov, Data::Translators Raku package, (2023), GitHub/antononcube.

[LUp1] Luis F. Uceta, Pretty::Table Raku package, (2020), GitLab/uzluisf.