Neslib.Yaml
1.0.0
Neslib.yaml est une bibliothèque pour analyser et émettre YAML et construire des documents et des flux YAML.
Neslib.yaml est construit au sommet de la bibliothèque Libyaml et travaille sur:
Pour installer:
> git clone --recursive https://github.com/neslib/Neslib.YamlCette bibliothèque dépend uniquement du référentiel Neslib, qui est inclus sous forme de sous-module avec ce référentiel.
Pour toutes les plates-formes sauf MacOS 32 bits, il n'y a pas de dépendances d'exécution: la bibliothèque Libyaml est liée directement à l'exécutable. Pour MacOS 32 bits, vous devez déployer la bibliothèque libyaml_mac32.dylib vers le ContentsMacOS .
Voici une très brève introduction pour Yaml. Pour des informations plus détaillées, consultez le site officiel de YAML ou l'une des nombreuses ressources en ligne comme celle-ci.
YAML (abréviation de "Yaml Ain't Bualip Language") est un langage de sérialisation des données. Contrairement à de nombreuses autres langues textuelles similaires (comme JSON et XML), un objectif principal de YAML est d'être lisible par l'homme et aussi facile à créer par les humains. C'est pourquoi il est couramment utilisé pour les fichiers de configuration. Cependant, il peut être utilisé pour toutes sortes de données, comme cet exemple de la spécification 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. Un document YAML est un arbre de valeurs, appelé nœuds ( TYamlNode dans cette bibliothèque). Il y a 4 types de nœuds:
Les mappages sont similaires aux dictionnaires Delphi. Un mappage est une collection de paires de clés / valeur. La note racine de l'exemple de document ci-dessus est un mappage: il mappe la invoice clé à la valeur 34843 et contient 7 autres paires de clés / valeur (de date aux comments ). Les clés et les valeurs peuvent être n'importe quel type YAML, bien que vous souhaitiez probablement vous en tenir aux chaînes pour les clés.
Les mappages peuvent être écrits en notation de bloc (comme dans l'exemple) ou en notation de flux (en utilisant des accolades bouclées {} ).
Lors de l'utilisation de la notation de bloc, YAML utilise l'indentation pour la portée. Seuls les espaces sont autorisés pour l'indentation ( pas des onglets). Le nombre d'espaces n'a pas d'importance tant que toutes les valeurs au même niveau utilisent la même quantité d'espaces. Dans l'exemple, la valeur de la clé bill-to est une autre cartographie. Cette cartographie est en retrait pour indiquer qu'il appartient à la clé bill-to .
Les séquences sont comme des tableaux ou des listes Delphi. De petites séquences peuvent être écrites en utilisant la notation de débit (en utilisant des crochets [] ). Des séquences plus grandes ou complexes sont généralement écrites en notation de bloc comme dans l'exemple: la valeur de la clé product est une séquence de deux produits (un basket-ball et un super-cerceau). Chaque élément de la séquence commence par un tableau de bord et un espace.
Dans cet exemple, chaque produit de la séquence est un mappage de 4 paires de clés / valeur.
Tous les nœuds ont au moins deux propriétés: une Tag et une Anchor . Les balises sont utilisées pour décrire le type sémantique d'un nœud. Les balises ne sont pas si courantes, donc je les sauterai dans cette introduction. Neslib.yaml a cependant un support complet pour les balises.
Une ancre peut être utilisée pour marquer un nœud dans le document. Vous pouvez ensuite vous référer à ce nœud à l'aide d'un alias .
Les ancres sont préfixées avec un ampère & ). Dans l'exemple, la valeur de la clé bill-to a une ancre appelée id001 (l'ampère et ne font pas partie du nom). Plus tard dans le document, la clé ship-to fait référence à cette ancre à l'aide d'un alias (un astérisque suivi du nom d'ancrage, par exemple *id001 ). C'est une façon de dire que l'adresse d'expédition est la même que l'adresse de facturation. Notez qu'un alias ne copie pas la valeur référencée; Il se réfère vraiment à un autre nœud.
Les ancres doivent apparaître dans le document avant de pouvoir être référencées. Leurs noms n'ont pas besoin d'être uniques dans le document; Si une nouvelle ancre est déclarée avec le même nom, elle remplace l'ancienne ancre.
Les scalaires sont les types les plus simples. Tout ce qui n'est pas une cartographie, une séquence ou un alias est un scalaire. En pratique, les scalaires ne sont que des cordes. Toutes les clés de l'exemple ci-dessus sont des scalaires de chaîne, mais beaucoup de valeurs sont également (comme 34843 , 2001-01-23 et Chris ).
La spécification YAML 1.1 (qui est ce que Libyaml utilise) traite tous ces scalaires comme des cordes, même si ce sont des nombres ou des dates comme dans cet exemple. Vous pouvez utiliser des balises pour indiquer explicitement qu'un scalaire spécifique est de type spécifique.
L'enregistrement TYamlNode dans cette bibliothèque fournit des méthodes comme ToInteger et ToDouble pour (essayer de) convertir en types Delphi, indépendamment des balises pouvant être attachées à un nœud.
Les scalars peuvent être écrits dans différents "styles":
| ). Dans l'exemple ci-dessus, la valeur bill-to.address.lines est un littéral. Toutes les nouvelles lignes dans un littéral sont conservées.comments dans l'exemple.Il y a beaucoup plus à Yaml, mais cela devrait couvrir de nombreux cas d'utilisation.
Le point d'entrée principal de cette bibliothèque est l'interface IYamlDocument ou IYamlStream .
Un fichier YAML peut contenir plusieurs documents. Si tel est le cas, vous devez utiliser un IYamlStream pour le charger. Un flux n'est qu'une collection de documents (de type IYamlDocument ).
La plupart du temps cependant, un fichier YAML contient un seul document et il est plus facile de commencer par un IYamlDocument . Le chargement d'un document est facile:
var
Doc: IYamlDocument;
begin
Doc := TYamlDocument.Load( ' invoice.yaml ' );
end ; Vous pouvez charger à partir d'un fichier ou d'un flux, ou vous pouvez analyser le texte YAML à l'aide de la méthode TYamlDocument.Parse .
Vous pouvez maintenant utiliser la propriété IYamlDocument.Root pour inspecter le document. Cette propriété est de type TYamlNode , qui est le bloc de construction de tous les documents.
Tyamlnode est implémenté comme un enregistrement pour le garder léger. Tous les nœuds sont "propriétaires" par un document. Cela rend la gestion de la mémoire entièrement automatique: une fois qu'un document sort de la portée, tous ses nœuds seront libérés automatiquement. Cela signifie cependant que vous ne devriez pas "s'accrocher" aux nœuds après qu'un document soit sorti de la portée. Cela entraîne un comportement non défini ou des violations d'accès.
Par exemple, pour accéder au price du premier produit dans l'exemple ci-dessus, vous pouvez utiliser le code suivant:
Price := Doc.Root.Values[ ' product ' ].Nodes[ 0 ].Values[ ' price ' ].ToDouble; Vous utilisez la propriété Values pour accéder aux valeurs par clé dans le mappage . De même, la propriété Nodes est utilisée pour accéder aux valeurs par index dans une séquence , et l'une des méthodes ToXXX peut être utilisée pour convertir une valeur scalaire en un type de données Delphi.
Pour vérifier le type de nœud, vous pouvez utiliser la propriété NodeType ou l'une des propriétés IsXXX ( IsMapping , IsScalar etc.).
Vous pouvez également créer un document YAML à partir de zéro et l'enregistrer dans un fichier ou le convertir en YAML. Pour créer un document YAML, utilisez l'une des méthodes TYamlDocument.CreateXXX , selon le type de nœud racine dont vous avez besoin. Si vous souhaitez reconstruire l'exemple de document, vous commencez par un mappage et un appel:
Doc := TYamlDocument.CreateMapping;Vous pouvez ensuite commencer à ajouter des paires de clés / valeur:
Doc.Root.AddOrSetValue( ' invoice ' , 34843 );
Doc.Root.AddOrSetValue( ' date ' , ' 2001-01-23 ' ); La méthode AddOrSetValue est utilisée pour ajouter des paires de clés / valeur à un mappage. Si le nœud n'est pas un mappage, une exception EInvalidOperation sera augmentée.
Pour ajouter une valeur non scalaire, utilisez l'une des autres méthodes AddOrSetXXX :
var
Products: TYamlNode;
begin
Products := Doc.Root.AddOrSetSequence( ' product ' );
end ; Cela ajoute une séquence à la cartographie avec le product clé. Vous pouvez ensuite ajouter des valeurs à la séquence en utilisant l'une des méthodes AddXXX . Encore une fois, une exception EInvalidOperation sera soulevée si le nœud n'est pas une séquence. Dans l'exemple, nous devons ajouter une autre cartographie à cette séquence:
var
Product: TYamlNode;
begin
Product := Products.AddMapping;
Product.AddOrSetValue( ' sku ' , ' BL394D ' );
Product.AddOrSetValue( ' quantity ' , 4 );
// etc...
end ; Une fois que vous avez construit votre document, vous pouvez l'enregistrer dans un fichier ou un flux à l'aide de la méthode Save , ou le convertir en YAML en utilisant la méthode ToYaml :
var
Yaml: String;
begin
Yaml := Doc.ToYaml;
end ; Vous pouvez passer un enregistrement TYamlOutputSettings en option pour personnaliser le formatage YAML.
Il y a plus à Neslib.yaml que décrit ci-dessus. Pour plus de détails, vous pouvez consulter le fichier source de Neslib.Yaml.pas . Des échantillons d'utilisation supplémentaires peuvent être trouvés dans les tests unitaires, en particulier dans le fichier Tests.Neslib.Yaml.Sample.pas .
Neslib.YAML est sous licence sous la licence BSD simplifiée.
Voir Licence.txt pour plus de détails.
