Neslib.Yaml
1.0.0
Neslib.yaml - это библиотека для анализа и излучения YAML и построения документов и потоков YAML.
Neslib.yaml строится на вершине библиотеки Libyaml и работает над:
Для установки:
> git clone --recursive https://github.com/neslib/Neslib.YamlЭта библиотека зависит только от репозитория Neslib, который включен в качестве подмодуля с этим репозиторием.
Для всех платформ, кроме 32-разрядного MacOS, нет зависимостей времени выполнения: библиотека Libyaml связана непосредственно с исполняемым файлом. Для 32-битных MacOS вам необходимо развернуть библиотеку libyaml_mac32.dylib для удаленного пути ContentsMacOS .
Вот очень краткое введение для YAML. Для получения более подробной информации взгляните на официальный сайт YAML или один из многих онлайн-ресурсов, таких как этот.
YAML (короткий для «Ямла не наценка») - это язык сериализации данных. В отличие от многих других подобных текстовых языков (например, JSON и XML), основная цель YAML-быть читаемым человеком, а также легко создавать людьми. Вот почему он обычно используется для файлов конфигурации. Однако его можно использовать для всех видов данных, таких как этот пример из спецификации YAML:
invoice : 34843
date : 2001-01-23
bill-to : &id001
given : Chris
family : Dumars
address :
lines : |
458 Walkman Dr.
Suite #292
city : Royal Oak
state : MI
postal : 48046
ship-to : *id001
product :
- sku : BL394D
quantity : 4
description : Basketball
price : 450.00
- sku : BL4438H
quantity : 1
description : Super Hoop
price : 2392.00
tax : 251.42
total : 4443.52
comments : >
Late afternoon is best.
Backup contact is Nancy
Billsmer @ 338-4338. Документ YAML - это дерево значений, называемое узлами ( TYamlNode в этой библиотеке). Есть 4 вида узлов:
Маркировки похожи на словаря Delphi. Картирование - это коллекция пар/значения. Корневой примечание примерного документа выше представляет собой отображение: оно отображает invoice на значение 34843 и содержит 7 других паров ключей/значения (от date до comments ). Как ключи, так и значения могут быть любым типом YAML, хотя вы, вероятно, хотите придерживаться строк для ключей.
Сопоставления могут быть записаны в блочной нотации (как в примере) или нотации потока (с использованием Curly Braces {} ).
При использовании блочной нотации YAML использует вдали в отступление. Только пространства разрешены для вдавления ( не вкладки). Количество пробелов не имеет значения, пока все значения на одном уровне используют одинаковое количество пробелов. В примере значение ключа bill-to это еще одно картирование. Это отображение с отступом, чтобы указать, что оно принадлежит ключу bill-to .
Последовательности похожи на массивы или списки Delphi. Небольшие последовательности могут быть записаны с использованием нотации потока (с использованием квадратных кронштейнов [] ). Большие или сложные последовательности обычно записываются в блочных обозначениях, как в примере: значение ключа product представляет собой последовательность двух продуктов (баскетбол и супер -обруч). Каждый элемент в последовательности начинается с приборной панели и пространства.
В этом примере каждый продукт в последовательности представляет собой отображение 4 пар клавиш/значения.
Все узлы имеют как минимум два свойства: Tag и Anchor . Теги используются для описания семантического типа узла. Теги не так распространены, поэтому я пропущу их в этом введении. Neslib.yaml обладает полной поддержкой тегов.
Якорь может быть использован для отметки узла в документе. Затем вы можете отправиться обратно в этот узел, используя псевдоним .
Якоря префикс с помощью амперсандов ( & ). В примере значение ключа bill-to есть якорь под названием id001 (Ampersand не является частью имени). Позже в документе, ключ ship-to относится к этому привязку, используя псевдоним (звездочка, за которым следует имя привязки, например, *id001 ). Это способ сказать, что адрес доставки такой же, как и счетный адрес. Обратите внимание, что псевдоним не копирует указанное значение; Это действительно просто относится к другому узлу.
Якоря должны появиться в документе, прежде чем их можно будет ссылаться. Их имена не должны быть уникальными в документе; Если новый якорь объявлен с тем же именем, он заменяет старый якорь.
Скаляры являются самыми простыми типами. Все, что не является отображением, последовательности или псевдонимом, является скалярным. На практике скаляры - это просто струны. Все клавиши в примере выше-скаляры строк, но многие значения также (такие как 34843 , 2001-01-23 и Chris ).
Спецификация YAML 1.1 (которая является тем, что использует Libyaml) рассматривает все эти скаляры как строки, даже если они являются числами или датами, как в этом примере. Вы можете использовать теги, чтобы явно указать, что конкретный скаляр имеет определенное тип.
Запись TYamlNode в этой библиотеке предоставляет такие методы, как ToInteger и ToDouble , чтобы (пытаться) преобразовать в типы Delphi, независимо от любых тегов, которые могут быть прикреплены к узлу.
Скаляры могут быть написаны в разных «стилях»:
| ). В приведенном выше примере значение bill-to.address.lines является буквальным. Любая новая линия в буквальном языке сохраняется.comments в примере.Ямл гораздо больше, но это должно охватывать многие варианты использования.
Основной точкой входа в эту библиотеку является интерфейс IYamlDocument или IYamlStream .
Файл YAML может содержать несколько документов. Если это так, вы должны использовать IYamlStream для его загрузки. Поток - это просто набор документов (типа IYamlDocument ).
Однако в большинстве случаев файл YAML содержит лишь один документ, и его легче начать с IYamlDocument . Загрузка документа легко:
var
Doc: IYamlDocument;
begin
Doc := TYamlDocument.Load( ' invoice.yaml ' );
end ; Вы можете загрузить из файла или потока, или вы можете анализировать текст YAML, используя метод TYamlDocument.Parse .
Теперь вы можете использовать свойство IYamlDocument.Root для проверки документа. Это свойство имеет тип TYamlNode , который является строительным блоком для всех документов.
Tyamlnode реализован как запись, чтобы сохранить его легким. Все узлы являются «владельцами» по документу. Это делает управление памятью полностью автоматическим: как только документ выходит из области, все его узлы будут освобождены автоматически. Это означает, что вы не должны «держаться» за узлами после того, как документ вышел из строя. Это приводит к неопределенному поведению или нарушениям доступа.
Например, чтобы получить доступ к price первого продукта в примере выше, вы можете использовать следующий код:
Price := Doc.Root.Values[ ' product ' ].Nodes[ 0 ].Values[ ' price ' ].ToDouble; Вы используете свойство Values для доступа к значениям с помощью ключа в картировании . Аналогично свойство Nodes используется для доступа к значениям с помощью индекса в последовательности , и один из методов ToXXX может использоваться для преобразования скалярного значения в Delphi DataType.
Чтобы проверить тип узла, вы можете использовать свойство NodeType или одно из свойств IsXXX ( IsMapping , IsScalar и т. Д.).
Вы также можете создать документ YAML с нуля и сохранить его в файл или преобразовать в YAML. Чтобы создать документ YAML, используйте один из методов TYamlDocument.CreateXXX , в зависимости от типа нуждающегося в вам корневого узла. Если вы хотите реконструировать пример документа, вы бы начали с картирования и вызовы:
Doc := TYamlDocument.CreateMapping;Затем вы можете начать добавлять пары ключей/значения:
Doc.Root.AddOrSetValue( ' invoice ' , 34843 );
Doc.Root.AddOrSetValue( ' date ' , ' 2001-01-23 ' ); Метод AddOrSetValue используется для добавления паров ключей/значений в отображение. Если узел не является отображением, то будет повышено исключение EInvalidOperation .
Чтобы добавить некаларное значение, используйте один из других методов AddOrSetXXX :
var
Products: TYamlNode;
begin
Products := Doc.Root.AddOrSetSequence( ' product ' );
end ; Это добавляет последовательность к отображению с ключевым product . Затем вы можете добавить значения в последовательность, используя один из методов AddXXX . Опять же, исключение EInvalidOperation будет поднято, если узел не является последовательности. В примере нам нужно добавить еще одно отображение в эту последовательность:
var
Product: TYamlNode;
begin
Product := Products.AddMapping;
Product.AddOrSetValue( ' sku ' , ' BL394D ' );
Product.AddOrSetValue( ' quantity ' , 4 );
// etc...
end ; После того, как вы построили свой документ, вы можете сохранить его в файл или поток, используя метод Save или преобразовать в YAML, используя метод ToYaml :
var
Yaml: String;
begin
Yaml := Doc.ToYaml;
end ; Вы можете передать дополнительную запись TYamlOutputSettings для настройки форматирования YAML.
В Neslib есть нечто большее, чем описано выше. Для получения более подробной информации вы можете посмотреть на хорошо документ Neslib.Yaml.pas Source File. Дополнительные образцы использования могут быть найдены в модульных тестах, особенно в файле Tests.Neslib.Yaml.Sample.pas .
Neslib.yaml имеет лицензию по упрощенной лицензии BSD.
См. License.txt для деталей.
