189 lines
7.5 KiB
Markdown
189 lines
7.5 KiB
Markdown
# MDView: описание работы и тестовые паттерны
|
||
## Назначение
|
||
`mdview` — консольный просмотрщик Markdown для текстового режима 80x32.
|
||
Программа загружает `.MD`-файл, индексирует его на экранные сегменты и рендерит содержимое с учётом переносов, стилей и специальных блоков.
|
||
|
||
## Как работает программа
|
||
### 1) Загрузка файла
|
||
- На старте вызывается `load_file(path)`.
|
||
- Если путь не передан, используется `SAMPLE.MD`.
|
||
- При ошибках загрузки программа показывает причину и завершает работу после нажатия клавиши.
|
||
|
||
### 2) Индексация (`index_lines`)
|
||
- Файл разбирается в массив сегментов для быстрого рендера.
|
||
- Поддерживаются ключевые типы строк:
|
||
- заголовки `#..####`,
|
||
- маркированные/нумерованные списки,
|
||
- цитаты `>`,
|
||
- горизонтальные разделители,
|
||
- fenced code-блоки,
|
||
- таблицы (nowrap-режим),
|
||
- обычные параграфы.
|
||
- Для list/quote/plain используется общая логика сканирования с режимами склейки строк.
|
||
|
||
### 3) Рендер (`render_line`, `render_viewport`)
|
||
- Для каждой видимой строки рисуется префикс (маркер списка, цитаты и т.д.) и текст.
|
||
- Поддерживаются inline-стили:
|
||
- `**жирный**`,
|
||
- `*курсив*`,
|
||
- `_подчёркнутый_`,
|
||
- `~~зачёркнутый~~`,
|
||
- `` `code` ``.
|
||
- Табы расширяются до фиксированного шага.
|
||
- Для длинных nowrap-строк применяется горизонтальный сдвиг и индикаторы `<`/`>`.
|
||
|
||
### 4) Навигация
|
||
- `Up/Down` — прокрутка на 1 строку.
|
||
- `PgUp/PgDn` — прокрутка на экран.
|
||
- `Home/End` — начало/конец документа.
|
||
- `Left/Right` — горизонтальная прокрутка nowrap-контента.
|
||
- `Esc` или `F10` — выход.
|
||
|
||
## Сборка и запуск
|
||
```bash
|
||
make -C examples/mdview
|
||
```
|
||
|
||
Запуск на целевой системе:
|
||
```bash
|
||
mdview.exe <путь_к_файлу.md>
|
||
```
|
||
|
||
Если путь не указан, открывается `SAMPLE.MD`.
|
||
|
||
## Тестовые паттерны
|
||
Ниже набор паттернов для ручной регрессии.
|
||
|
||
### P01 — Базовый smoke-тест открытия
|
||
Вход:
|
||
- валидный markdown-файл среднего размера.
|
||
|
||
Ожидается:
|
||
- файл открывается без ошибок;
|
||
- статус-бар и меню отображаются корректно;
|
||
- прокрутка работает.
|
||
|
||
### P02 — Ошибка открытия файла
|
||
Вход:
|
||
- несуществующий путь к файлу.
|
||
|
||
Ожидается:
|
||
- сообщение `mdview: cannot load file`;
|
||
- корректный код причины (`open failed` и т.п.);
|
||
- ожидание клавиши перед выходом.
|
||
|
||
### P03 — Пустой файл
|
||
Вход:
|
||
- пустой `.md`.
|
||
|
||
Ожидается:
|
||
- сообщение `mdview: empty file`;
|
||
- корректное завершение после нажатия клавиши.
|
||
|
||
### P04 — Обычный параграф и переносы
|
||
Шаблон:
|
||
```md
|
||
Это длинный абзац для проверки переноса строк в обычном тексте.
|
||
Вторая строка должна мягко склеиться с первой.
|
||
```
|
||
|
||
Ожидается:
|
||
- строки склеиваются как единый параграф;
|
||
- переносы происходят по ширине экрана без потери символов.
|
||
|
||
### P05 — Hard break в параграфе
|
||
Шаблон:
|
||
```md
|
||
Первая строка с двумя пробелами в конце.
|
||
Вторая строка после hard break.
|
||
```
|
||
|
||
Ожидается:
|
||
- между строками сохраняется принудительный разрыв;
|
||
- inline-стиль не ломается.
|
||
|
||
### P06 — Многострочный список с lazy continuation
|
||
Шаблон:
|
||
```md
|
||
- Пункт списка, который продолжается
|
||
на следующей строке с отступом.
|
||
```
|
||
|
||
Ожидается:
|
||
- continuation-строка склеивается с пунктом через один пробел;
|
||
- лишние ведущие отступы continuation не попадают в итоговый текст;
|
||
- переносы не ломают маркер списка.
|
||
|
||
### P07 — Многострочная цитата
|
||
Шаблон:
|
||
```md
|
||
> Первая строка цитаты
|
||
> Вторая строка цитаты
|
||
> Третья строка цитаты
|
||
```
|
||
|
||
Ожидается:
|
||
- для продолжений корректно повторяется quote-префикс;
|
||
- сырой символ `>` из исходника не «просачивается» в середину текста.
|
||
|
||
### P08 — Пустая quoted-строка как разделитель
|
||
Шаблон:
|
||
```md
|
||
> Первый параграф цитаты
|
||
>
|
||
> Второй параграф цитаты
|
||
```
|
||
|
||
Ожидается:
|
||
- пустая quoted-строка разделяет два параграфа;
|
||
- рендер не объединяет их в один поток.
|
||
|
||
### P09 — Таблица в nowrap-режиме
|
||
Шаблон:
|
||
```md
|
||
| col1 | col2 | col3 |
|
||
|------|------|------|
|
||
| очень длинное значение | очень длинное значение | очень длинное значение |
|
||
```
|
||
|
||
Ожидается:
|
||
- строка таблицы не переносится по словам;
|
||
- работает горизонтальный сдвиг `Left/Right`;
|
||
- индикаторы `<`/`>` показывают скрытый контент.
|
||
|
||
### P10 — Fenced code-block
|
||
Шаблон:
|
||
~~~md
|
||
```text
|
||
**это не жирный**
|
||
_это не подчёркнутый_
|
||
```
|
||
~~~
|
||
|
||
Ожидается:
|
||
- внутри code-блока inline-разметка не применяется;
|
||
- текст отображается как литерал.
|
||
|
||
### P11 — Inline-стили на обычном тексте
|
||
Шаблон:
|
||
```md
|
||
Текст с **жирным**, *курсивом*, _подчёркнутым_, ~~зачёркнутым~~ и `code`.
|
||
```
|
||
|
||
Ожидается:
|
||
- все перечисленные стили рендерятся корректно;
|
||
- литеральные случаи вроде `2 * 3` не превращаются в стиль.
|
||
|
||
### P12 — Статус-бар и границы прокрутки
|
||
Вход:
|
||
- документ на несколько экранов.
|
||
|
||
Ожидается:
|
||
- корректные `L x-y / total` и `%`;
|
||
- `Home/End` приводят к ожидаемым позициям;
|
||
- при выходе за границы документа top-line корректно clamp-ится.
|
||
|
||
## Рекомендация по регрессии
|
||
После любых изменений в логике индексации/рендера прогонять минимум:
|
||
- `P04`, `P05`, `P06`, `P07`, `P09`, `P10`, `P11`, `P12`.
|