util-linux-cal/README_ru.md

# 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`)
- Динамические плагины
- Автоматическое определение локали
- Гибкая настройка календарной реформы
- Цветовой вывод с подсветкой сегодня/выходных/праздников