====== Mystic Calendar ======

This is a port of the classic **CNet Calendar** AREXX script (CNet Pro BBS) to **Mystic BBS (Python scripts)**.

It displays a monthly calendar and a right-side “upcoming events” list from a simple data file, and can also generate a separate **birthday events file** from Mystic user records.

This script is intended to be run:

  * at login (ex: a `welcome`/auto-run spot), or
  * as a PFile/Door from a menu.

----

===== What This Version Does =====

  * **80-column layout** (uses 79 to be safe)
  * Left column: **month grid**
  * Right column: **upcoming events list**, grouped by month
  * Reads events from: `cal.YYYY`
  * Reads birthdays from: `cal.bdays.YYYY` (when run with `bd`)
  * Preserves indentation in event lines (multi-line events work)
  * **ANSI colors** (safe approach; no box-drawing due to encoding issues in Mystic Python output path)
  * Can roll forward into next year for the “upcoming” list and show `January YYYY+1` only when needed

----

===== Directory Layout =====

<code>
/mystic/
├── scripts/
│   ├── calendar.mpy
│   ├── generate_birthdays.py
│   └── generate_holidays.py
└── calendar_data/
    ├── cal.2026
    ├── cal.2027
    ├── cal.bdays.2026
    └── cal.bdays.2027
</code>

Notes:
  * Mystic scripts are typically placed under your theme scripts directory, for example:
    * `/home/pi/mystic/themes/default/scripts/`
  * Data lives under:
    * `/home/pi/mystic/themes/default/scripts/calendar_data/`

----

===== Data File Format =====

Each event line begins with **MMDD**, followed by display text.

Example:

<code>
0101 1st  - New Year's Day
0704 4th  - Independence Day!
0820 20th - Renaissance Faire at Burbank CA
0820        E-mail Jim Shaffer for more info
</code>

Rules:
  * The first 4 characters **must** be digits (`MMDD`)
  * Everything after `MMDD` is displayed on the right (the script preserves leading spaces)
  * You can use multiple lines for the same date by repeating the same `MMDD`

Birthday files (`cal.bdays.YYYY`) use the same format.

----

===== Setup =====

Create the data directory:

<code>
mkdir -p /home/pi/mystic/themes/default/scripts/calendar_data
</code>

Confirm your script points to the correct location:

<code>
DATA_PATH = "/home/pi/mystic/themes/default/scripts/calendar_data/"
</code>

----

===== Script Usage =====

Normal events calendar:

<code>
calendar.mpy
</code>

Birthday calendar (reads `cal.bdays.YYYY`):

<code>
calendar.mpy bd
</code>

Important Mystic note:
  * Mystic does not reliably pass arguments via `sys.argv` inside scripts.
  * This script uses Mystic parameter calls (example: `param_count()` / `param_str()`).

----

===== Birthdays =====

Birthdays are generated into yearly files:

  * `cal.bdays.YYYY`

The generator:
  * reads Mystic user records via Mystic’s Python API (`getuser(<id>)`)
  * skips deleted/invalid users
  * formats entries like:
    * `0405 5th  - MobbyG's birthday!`

If you run both `cal.bdays.<year>` and `cal.bdays.<year+1>`, the main calendar script can show upcoming birthdays across the year boundary.

----

===== Why The Fancy Box/Grid Was Dropped =====

We attempted two traditional approaches for a “CNet-style” boxed calendar:

  * **DEC line drawing mode** (VT100 `ESC ( 0` / `ESC ( B`)
  * **CP437 box drawing characters**
  * **Unicode box drawing characters**

In Mystic’s Python output path, those characters were either sanitized or re-encoded (mojibake like `0xB...`, `├ä...`, or `ΓöÇ...`) depending on the terminal/client path.

So this release uses **plain ASCII layout + ANSI colors** for maximum compatibility and reliability.

----

===== Future Enhancement: ANSI Template Overlay (Recommended) =====

If we want the exact “classic boxed calendar” look later without encoding problems, the best approach is:

  - Build a static **.ANS template** containing the full calendar grid and border art
  - Display the template using Mystic’s normal ANSI rendering (where CP437/ANSI art is handled correctly)
  - Use Python only to print the dynamic parts (dates and events) at fixed positions

This avoids encoding problems entirely because the box art is handled by Mystic’s ANSI file renderer, not Python output.

----

===== Install / Menu Integration =====

Add as a PFile/Door (example paths will vary by install):

  * Create a menu entry that runs:
    * `python3 calendar.mpy`
  * For birthday view:
    * `python3 calendar.mpy bd`

You can also call it at login by running it from the appropriate Mystic login event/menu hook.

----

===== Source / Code =====

See full code here:
[[mystic_cal:mystic_cal_code|Mystic Calendar Code]]