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-файл в кодировке UTF-8 и возвращает соответствующую структуру данных.

Параметры:

• ПутьКФайлу (Строка) - путь к YAML-файлу

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

• Произвольный - распарсенная структура данных или массив документов

Пример:

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

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

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

Параметры:

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

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

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

Пример:

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

ЗаписатьВФайл(ПутьКФайлу, Значение)

Сериализует данные в YAML-формат и записывает результат в файл в кодировке UTF-8.

Параметры:

• ПутьКФайлу (Строка) - путь к YAML-файлу
• Значение (Произвольный) - данные для сериализации

Пример:

Парсер = Новый ПарсерYaml();
Данные = Новый Структура("ключ", "значение");
Парсер.ЗаписатьВФайл("config.yaml", Данные);

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

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

• ✅ Строки (с кавычками и без)
• ✅ Числа (целые и вещественные)
• ✅ Булевы значения (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. Многострочные литералы - | и > стили, chomping и indentation indicators
5. Flow Style - инлайн массивы [1, 2, 3] и объекты {key: value}
6. Пустые коллекции - [], {}, неявные пустые значения
7. Комментарии - строки с #
8. Якоря и ссылки - &anchor, *anchor, <<: *anchor
9. Смешанные типы - комбинации различных структур
10. Сложные структуры - глубокая вложенность и композиции
11. YAML сериализация - полная поддержка записи в YAML формат
12. Базовое экранирование строк - \n, \t, \r, \", \\, \/, \b, \f
13. Unicode поддержка - \uXXXX и \xXX последовательности
14. Обработка ошибок - валидация синтаксиса и информативные сообщения
15. Пробелы, табуляция и explicit keys - сценарии из YAML Test Suite
16. YAML директивы - %YAML, tag handles и связанные проверки
17. Файловые операции - чтение YAML из файла и запись YAML в файл

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

1. Расширение удобства API
   • Настройки форматирования сериализатора
   • Дополнительные вспомогательные методы для документов YAML

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

• Улучшение парсинга очень больших файлов - контроль памяти и времени на больших YAML
• Сложные ключи - расширение пользовательских сценариев поверх explicit keys

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

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

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

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

• Всего тестов: 418 обнаружено
• Пройдено: 418 тестов (100%)
• Пропущено: 0 тестов
• Покрытие: основные возможности YAML 1.2

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

# Все тесты
oneunit e

# Конкретная категория
oneunit e --tagsInclude flow    # Flow Style тесты
oneunit e --tagsInclude anchor  # Якоря и ссылки
oneunit e --tagsInclude literal # Многострочные литералы
oneunit e --tagsInclude error   # Обработка ошибок

Нагрузочные тесты

Для проверки работы на больших YAML в utils есть отдельные сценарии. Они генерируют документ из 5000 элементов с вложенными массивами и соответствиями, затем проверяют десериализацию или сериализацию.

# Десериализация большого YAML (~665 КБ)
oscript -measure utils/load-deserialize.os

# Сериализация большого объекта в YAML (~665 КБ)
oscript -measure utils/load-serialize.os

Контрольный прогон на текущем окружении:

utils/load-deserialize.os: 5000 элементов, 664976 байт, 00:00:17.4475616
utils/load-serialize.os:   5000 элементов, 664976 байт, 00:00:03.1080556

Оба сценария завершаются успешно. По результатам проверки срочная оптимизация не требуется: сериализация работает быстро для текущего объема, десериализация ожидаемо дороже и остается кандидатом только для будущей точечной оптимизации при росте требований к большим файлам.

📄 Лицензия

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

👨‍💻 Автор

Egor Ivanov - e.ivanov@1cdevelopers.ru

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

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

---