oscript-yaml 🚀

Полнофункциональная библиотека для работы с YAML в экосистеме OneScript/1C. Реализует парсинг и сериализацию YAML с поддержкой основных возможностей стандарта YAML 1.2 включая вложенные структуры, якоря, многострочные литералы и Flow Style синтаксис.

📋 Оглавление

• Установка
• Быстрый старт
• API
• Поддерживаемые возможности
• Статус реализации
• Тестирование

🚀 Установка

opm install oscript-yaml

Или клонируйте репозиторий:

git clone https://github.com/Segate-ekb/oscript-yaml.git

⚡ Быстрый старт

#Использовать oscript-yaml

Парсер = Новый ПарсерYaml();

// Простой пример парсинга
СтрокаYAML = "
| name: John Doe
| age: 30
| active: true
|";

Результат = Парсер.ПрочитатьYaml(СтрокаYAML);
Сообщить(Результат.Получить("name")); // John Doe

// Сериализация в YAML
Данные = Новый Структура;
Данные.Вставить("имя", "Иван Иванов");
Данные.Вставить("возраст", 25);
Данные.Вставить("активен", Истина);

СтрокаYAML = Парсер.ЗаписатьYaml(Данные);
Сообщить(СтрокаYAML);

📚 API

Класс ПарсерYaml

ПрочитатьYaml(СтрокаYaml)

Парсит YAML-строку и возвращает соответствующую структуру данных.

Параметры:

• СтрокаYaml (Строка) - YAML-строка для парсинга

Возвращаемое значение:

• Массив - массив документов yaml

Пример:

Парсер = Новый ПарсерYaml();
Результат = Парсер.ПрочитатьYaml("key: value");

ЗаписатьYaml(Значение)

Сериализует данные в YAML-формат.

Параметры:

• Значение (Произвольный) - данные для сериализации

Возвращаемое значение:

• Строка - YAML-представление данных

Пример:

Парсер = Новый ПарсерYaml();
Данные = Новый Структура("ключ", "значение");
СтрокаYAML = Парсер.ЗаписатьYaml(Данные);
// Результат: "---\nключ: значение"

✅ Поддерживаемые возможности

Базовые типы данных

• ✅ Строки (с кавычками и без)
• ✅ Числа (целые и вещественные)
• ✅ Булевы значения (true, false)
• ✅ Null значения (null, ~)
• ✅ Комментарии (#)
• ✅ Множественные документы (--- и ...)

Структуры данных

• ✅ Соответствия (объекты)
• ✅ Массивы (списки)
• ✅ Вложенные структуры любой глубины
• ✅ Смешанные типы в массивах

Flow Style (инлайн синтаксис)

• ✅ Массивы в квадратных скобках [1, 2, 3]
• ✅ Объекты в фигурных скобках {key: value}
• ✅ Вложенные Flow структуры
• ✅ Пустые коллекции [], {}
• ✅ Смешанный Flow и Block стили

Многострочные литералы

• ✅ Literal style (|) - сохраняет переводы строк
• ✅ Folded style (>) - объединяет строки
• ✅ strip_literal: (|-) - убирает последний перенос строки
• ✅ keep_literal: (|+) - сохраняет финальные переводы строк

Пустые коллекции

• ✅ Пустые массивы в Flow style []
• ✅ Пустые объекты в Flow style {}
• ✅ Неявные пустые значения (Block style)
• ✅ Null значения (null, ~)

Якоря и ссылки

• ✅ Определение якорей &anchor
• ✅ Ссылки на якоря *anchor
• ✅ Слияние объектов <<: *anchor
• ✅ Простые ссылки на скалярные значения

Обработка ошибок

• ✅ Проверка синтаксиса Flow Style
• ✅ Валидация парных скобок и кавычек
• ✅ Информативные сообщения об ошибках

🚧 Статус реализации

✅ Полностью реализовано

1. Базовый парсинг YAML - ключ-значение пары, скалярные типы
2. Массивы Block Style - списки с дефисами
3. Вложенные структуры - многоуровневые объекты любой глубины
4. Многострочные литералы - | и > стили с базовыми модификаторами (28/39 тестов)
5. Flow Style - инлайн массивы [1, 2, 3] и объекты {key: value} (74/79 тестов)
6. Пустые коллекции - [], {}, неявные пустые значения
7. Комментарии - строки с #
8. Якоря и ссылки - &anchor, *anchor, <<: *anchor (22/25 тестов)
9. Смешанные типы - комбинации различных структур
10. Сложные структуры - глубокая вложенность и композиции
11. YAML сериализация - полная поддержка записи в YAML формат
12. Базовое экранирование строк - \n, \t, \r, \", \\, \/, \b, \f (42/45 тестов)
13. Unicode поддержка - \uXXXX и \xXX последовательности
14. Обработка ошибок - валидация синтаксиса и информативные сообщения (58/74 тестов)

🔧 Частично реализовано

1. Обработка пробелов и табуляции - базовая поддержка (75/92 тестов)

   • ✅ Основные случаи отступов
   • 🚧 Сложные случаи с табуляцией в различных контекстах
   • 🚧 Trailing spaces в некоторых сценариях

2. Свернутые блоки (folded style) - частичная поддержка (20/29 тестов)

   • ✅ Базовое складывание строк с >
   • 🚧 Сложные случаи с модификаторами и отступами
   • ✅ Корректная обработка финальных переносов строк

3. YAML директивы - базовая поддержка (19/25 тестов)

   • ✅ Обработка %YAML 1.2
   • 🚧 Валидация версий и дублированных директив
   • 🚧 Обработка ошибок в директивах

🔄 В разработке / Планируется

1. Чтение из файлов - метод ПрочитатьИзФайла(ПутьКФайлу)

   Парсер = Новый ПарсерYaml();
   Результат = Парсер.ПрочитатьИзФайла("config.yaml");

2. Улучшение обработки пробелов и табуляции

   • Корректная обработка табуляции в отступах
   • Валидация смешения пробелов и табов
   • Trailing spaces в потоках

3. Завершение якорей и алиасов

   • Edge cases с алиасами в последовательностях
   • Сложные сценарии merge

📋 Планы развития

• Файловые операции - ПрочитатьИзФайла(), ЗаписатьВФайл()
• Улучшение парсинга пробелов - завершение поддержки табуляции и trailing spaces
• Сложные ключи - поддержка explicit keys

Долгосрочные планы

• Производительность - оптимизация для больших файлов
• Потоковый парсинг - обработка файлов по частям
• Плагины типов - кастомные обработчики данных

🧪 Тестирование

Проект включает обширный набор тестов на основе официального YAML Test Suite:

• Всего тестов: 402 обнаружено
• Пройдено: 355 теста (88.1%)
• Пропущено: 47 тестов (для функций в разработке)
• Покрытие: основные возможности YAML 1.2

Запуск тестов

# Все тесты
oneunit e

# Конкретная категория
oneunit e --tagsInclude flow    # Flow Style тесты (74/79 пройдено)
oneunit e --tagsInclude anchor  # Якоря и ссылки (22/25 пройдено)
oneunit e --tagsInclude literal # Многострочные литералы (28/39 пройдено)
oneunit e --tagsInclude error   # Обработка ошибок (58/74 пройдено)

📄 Лицензия

MIT License - см. файл LICENSE для подробностей.

👨‍💻 Автор

Egor Ivanov - [email protected]

🔗 Полезные ссылки

• YAML спецификация 1.2
• OneScript документация
• Официальный YAML Test Suite
• Тестовый Фреймворк

---