Initial commit: Rust calendar utility

README_ru.md

@@ -0,0 +1,187 @@
+# cal
+
+Календарь для терминала — переписанная на Rust версия утилиты `cal` из util-linux.
+
+## Возможности
+
+- **Гибкое отображение**: один месяц, три месяца, год, произвольное количество месяцев
+- **Неделя с понедельника или воскресенья**: `-m` (ISO) или `-s` (US)
+- **Номера недель**: `-w` с выбором системы нумерации (`--week-type iso` или `us`)
+- **Юлианские дни**: `-j` показывает день года вместо даты
+- **Вертикальный режим**: `-v` для компактного отображения дней по колонкам
+- **Кастомизация реформы**: `--reform 1752|gregorian|iso|julian` для разных календарных систем
+- **Подсветка сегодня**: инверсия цвета для текущего дня
+- **Подсветка выходных и праздников**: цвета для субботы, воскресенья и официальных праздников
+- **Плагины**: динамическая загрузка плагинов для подсветки праздников через API
+
+## Установка
+
+```bash
+cargo build --release
+```
+
+Бинарный файл появится в `target/release/cal`.
+
+### Сборка с плагинами
+
+Плагин подсветки праздников собирается в workspace:
+
+```bash
+cargo build --release --workspace
+```
+
+Плагин `libholiday_highlighter.so` будет в `target/release/`.
+
+## Команды
+
+### Базовое использование
+
+| Команда | Описание |
+|---------|----------|
+| `cal` | Текущий месяц |
+| `cal 2026` | Весь 2026 год |
+| `cal 2 2026` | Февраль 2026 |
+| `cal 15 9 2026` | Сентябрь 2026 с выделением 15 числа |
+| `cal декабрь 2025` | Декабрь 2025 (поддержка названий месяцев) |
+
+### Режимы отображения
+
+| Команда | Описание |
+|---------|----------|
+| `cal -y` | Весь год (12 месяцев) |
+| `cal -Y` | Следующие 12 месяцев от текущего |
+| `cal -3` | Три месяца: предыдущий, текущий, следующий |
+| `cal -n 6` | Показать 6 месяцев |
+| `cal --span -n 12` | 12 месяцев с центрированием на текущем |
+
+### Формат вывода
+
+| Команда | Описание |
+|---------|----------|
+| `cal -v` | Вертикальный режим (дни в колонках) |
+| `cal -j` | Юлианские дни (день года 1-365/366) |
+| `cal -w` | С номерами недель |
+| `cal --week-type us` | Недели по US стандарту (с воскресенья) |
+| `cal -c 2` | Принудительно 2 колонки для мульти-месячного режима |
+| `cal -c auto` | Автоподбор колонок по ширине терминала |
+
+### Календарные опции
+
+| Команда | Описание |
+|---------|----------|
+| `cal -m` | Неделя с понедельника (ISO, по умолчанию) |
+| `cal -s` | Неделя с воскресенья (US стиль) |
+| `cal --reform 1752` | Реформа 1752 года (пропуск 3-13 сентября в Великобритании) |
+| `cal --reform gregorian` | Всегда григорианский календарь |
+| `cal --reform julian` | Всегда юлианский календарь |
+| `cal --iso` | ISO 8601 (алиас для `--reform iso`) |
+
+### Вывод и цвета
+
+| Команда | Описание |
+|---------|----------|
+| `cal --color` | Отключить цвета (монохромный вывод) |
+| `cal -H` | Подсветка праздников через isdayoff.ru API (требует плагин) |
+
+### Комбинированные примеры
+
+```bash
+# Год с номерами недель и праздниками
+cal -y -w -H
+
+# Три месяца вертикально с праздниками
+cal -3 -v -H
+
+# 6 месяцев в 2 колонки
+cal -n 6 -c 2
+
+# Февраль 2026 с юлианскими днями
+cal -j 2 2026
+
+# Следующие 12 месяцев с центрированием
+cal --span -Y
+```
+
+## Плагины
+
+### Holiday Highlighter
+
+Плагин для подсветки официальных праздников через API isdayoff.ru.
+
+#### Поддерживаемые страны
+
+| Код | Страна | Локали |
+|-----|--------|--------|
+| RU | Россия | ru_RU, ru_BY, ru_KZ, ru_UZ, ru_LV |
+| BY | Беларусь | be_BY, ru_BY |
+| KZ | Казахстан | kk_KZ, ru_KZ |
+| US | США | en_US, en |
+| UZ | Узбекистан | uz_UZ, ru_UZ |
+| TR | Турция | tr_TR |
+| LV | Латвия | lv_LV, ru_LV |
+
+Страна определяется автоматически по `LC_ALL`, `LC_TIME` или `LANG`.
+
+#### Типы дней
+
+| Код | Значение | Цвет |
+|-----|----------|------|
+| 0 | Рабочий день | — |
+| 1 | Выходной | Красный |
+| 2 | Сокращённый день | Бирюзовый |
+| 8 | Официальный праздник | Красный |
+
+#### Установка плагина
+
+После сборки workspace плагин находится в `target/release/libholiday_highlighter.so`.
+
+Для системной установки:
+
+```bash
+# Локально для пользователя
+mkdir -p ~/.local/lib/cal/plugins
+cp target/release/libholiday_highlighter.so ~/.local/lib/cal/plugins/
+
+# Системно (требует root)
+sudo mkdir -p /usr/lib/cal/plugins
+sudo cp target/release/libholiday_highlighter.so /usr/lib/cal/plugins/
+```
+
+#### API
+
+Плагин использует [isdayoff.ru API](https://isdayoff.ru/):
+- `GET /api/getdata?year=YYYY&month=MM&pre=1` — данные за месяц
+- `GET /api/getdata?year=YYYY&pre=1` — данные за год
+
+Параметр `pre=1` включает информацию о предпраздничных сокращённых днях.
+
+## Переменные окружения
+
+| Переменная | Описание |
+|------------|----------|
+| `LC_ALL` | Приоритетная локаль для названий месяцев и дней |
+| `LC_TIME` | Локаль для форматирования дат |
+| `LANG` | Резервная локаль |
+| `CAL_TEST_TIME` | Фиксированная дата для тестирования (формат YYYY-MM-DD) |
+
+## Локализация
+
+Поддерживаются названия месяцев на русском и английском:
+
+```bash
+cal январь 2026
+cal February 2026
+cal 1 2026
+```
+
+Дни недели сокращаются до 2 символов согласно локали:
+- **ru_RU**: Пн, Вт, Ср, Чт, Пт, Сб, Вс
+- **en_US**: Mo, Tu, We, Th, Fr, Sa, Su
+
+## Отличия от util-linux cal
+
+- Поддержка вертикального режима (`-v`)
+- Динамические плагины
+- Автоматическое определение локали
+- Гибкая настройка календарной реформы
+- Цветовой вывод с подсветкой сегодня/выходных/праздников