Neslib.Yaml
1.0.0
Neslib.yaml ist eine Bibliothek zum Analysieren und Ausgang von YAML und dem Bau von YAML -Dokumenten und Streams.
Neslib.yaml ist auf der Biyaml -Bibliothek aufgebaut und arbeitet an:
Zu installieren:
> git clone --recursive https://github.com/neslib/Neslib.YamlDiese Bibliothek hängt nur vom Neslib -Repository ab, das mit diesem Repository als Submodul enthalten ist.
Für alle Plattformen mit Ausnahme von MacOS 32-Bit gibt es keine Laufzeitabhängigkeiten: Die Biyaml-Bibliothek ist direkt mit der ausführbaren Datei verknüpft. Für macOS 32-Bit müssen Sie die libyaml_mac32.dylib -Bibliothek für den Remote- ContentsMacOS bereitstellen.
Hier ist eine sehr kurze Einführung für Yaml. Detailliertere Informationen finden Sie in der offiziellen YAML-Website oder einer der vielen Online-Ressourcen wie dieser.
YAML (kurz für "Yaml Ain't Markup -Sprache") ist eine Datenserialisierungssprache. Im Gegensatz zu vielen anderen ähnlichen textbasierten Sprachen (wie JSON und XML) ist es ein Hauptziel von YAML, von Menschen lesbar und auch leicht zu kreieren. Deshalb wird es üblicherweise für Konfigurationsdateien verwendet. Es kann jedoch für alle Arten von Daten verwendet werden, wie beispielsweise dieses Beispiel aus der YAML -Spezifikation:
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. Ein YAML -Dokument ist ein Wertebaum, der als Knoten bezeichnet wird ( TYamlNode in dieser Bibliothek). Es gibt 4 Arten von Knoten:
Zuordnungen ähneln den Delphi -Wörterbüchern. Eine Zuordnung ist eine Sammlung von Schlüssel-/Wertpaaren. Der Stammnotiz des obigen Beispieldokuments ist eine Zuordnung: Es ordnet die invoice auf den Wert 34843 ab und enthält 7 weitere Schlüssel-/Wertpaare (von date bis zu comments ). Sowohl Schlüssel als auch Werte können jeder YAML -Typ sein, obwohl Sie sich wahrscheinlich an Saiten für Schlüssel halten möchten.
Zuordnungen können in der Blocknotation (wie im Beispiel) oder in der Flussnotation (unter Verwendung von Curly Braces {} ) geschrieben werden.
Bei der Verwendung von Blocknotation verwendet YAML Einrückung zum Scoping. Für Einrückungen sind nur Leerzeichen zulässig ( nicht für die Registerkarten). Die Anzahl der Leerzeichen spielt keine Rolle, solange alle Werte auf derselben Ebene die gleiche Menge an Räumen verwenden. Im Beispiel ist der Wert des bill-to Schlüssels eine weitere Zuordnung. Diese Zuordnung ist eingerückt, um anzuzeigen, dass sie zur bill-to Schlüssel gehört.
Sequenzen sind wie Delphi -Arrays oder Listen. Kleine Sequenzen können unter Verwendung von Flow -Notation (unter Verwendung von quadratischen Klammern [] ) geschrieben werden. Größere oder komplexe Sequenzen werden normalerweise wie im Beispiel in Blocknotation geschrieben: Der Wert des product ist eine Folge von zwei Produkten (ein Basketball und Super -Hoop). Jedes Element in der Sequenz beginnt mit einem Armaturenbrett und einem Raum.
In diesem Beispiel ist jedes Produkt in der Sequenz eine Zuordnung von 4 Schlüssel-/Wertpaaren.
Alle Knoten haben mindestens zwei Eigenschaften: einen Tag und einen Anchor . Tags werden verwendet, um den semantischen Typ eines Knotens zu beschreiben. Tags sind nicht so häufig, also werde ich sie in dieser Einführung überspringen. Neslib.yaml hat jedoch die volle Unterstützung für Tags.
Ein Anker kann verwendet werden, um einen Knoten im Dokument zu markieren. Sie können sich später mit einem Alias auf diesen Knoten beziehen.
Anker werden mit einem Verstärker vorangestellt ( & ). Im Beispiel hat der Wert des bill-to Schlüssels einen Anker namens id001 (der Ampers und ist nicht Teil des Namens). Später im Dokument bezieht sich der ship-to -Taste mit einem Alias auf diesen Anker (ein Stern, gefolgt vom Ankernamen, z. B. *id001 ). Dies ist eine Möglichkeit zu sagen, dass die Versandadresse die gleiche wie die Abrechnungsadresse entspricht. Beachten Sie, dass ein Alias den referenzierten Wert nicht kopiert. Es bezieht sich wirklich nur auf einen anderen Knoten.
Anker müssen im Dokument erscheinen, bevor sie verwiesen werden können. Ihre Namen müssen innerhalb des Dokuments nicht eindeutig sein. Wenn ein neuer Anker mit demselben Namen deklariert wird, ersetzt er den alten Anker.
Skalare sind die einfachsten Typen. Alles, was kein Mapping, eine Sequenz oder ein Alias ist, ist ein Skalar. In der Praxis sind Skalare nur Saiten. Alle Schlüssel im obigen Beispiel sind String-Skalare, aber viele Werte sind ebenfalls (z. B. 34843 , 2001-01-23 und Chris ).
Die YAML 1.1 -Spezifikation (die Libyaml verwendet) behandelt alle diese Skalare als Zeichenfolgen, auch wenn es sich wie in diesem Beispiel Zahlen oder Daten handelt. Sie können Tags verwenden, um explizit anzugeben, dass ein bestimmter Skalar einen bestimmten Typ hat.
Der TYamlNode -Datensatz in dieser Bibliothek enthält Methoden wie ToInteger und ToDouble , um sie in Delphi -Typen zu konvertieren, unabhängig von Tags, die möglicherweise an einen Knoten angehängt werden können.
Skalare können in verschiedenen "Stilen" geschrieben werden:
| ). Im obigen Beispiel ist der Wert bill-to.address.lines ein wörtlicher. Alle neuen Zeilen in einem buchstäblichen sind erhalten.comments im Beispiel verwendet.Yaml hat noch viel mehr, aber dies sollte viele Anwendungsfälle abdecken.
Der Haupteintrittspunkt dieser Bibliothek ist das IYamlDocument oder IYamlStream -Schnittstellen.
Eine YAML -Datei kann mehrere Dokumente enthalten. Wenn dies der Fall ist, sollten Sie einen IYamlStream verwenden, um ihn zu laden. Ein Stream ist nur eine Sammlung von Dokumenten (vom Typ IYamlDocument ).
Meistens enthält eine YAML -Datei nur ein einzelnes Dokument und es ist einfacher, mit einem IYamlDocument zu beginnen. Das Laden eines Dokuments ist einfach:
var
Doc: IYamlDocument;
begin
Doc := TYamlDocument.Load( ' invoice.yaml ' );
end ; Sie können aus einer Datei oder einem Stream geladen oder YAML -Text mit der Methode TYamlDocument.Parse analysieren.
Sie können jetzt die Eigenschaft IYamlDocument.Root verwenden, um das Dokument zu inspizieren. Diese Eigenschaft ist vom Typ TYamlNode , der Baustein für alle Dokumente ist.
Tyamlnode wird als Datensatz implementiert, um es leicht zu halten. Alle Knoten sind "Eigentümer" von einem Dokument. Dies macht die Speicherverwaltung vollautomatisch: Sobald ein Dokument aus dem Umfang ausgeht, werden alle seine Knoten automatisch befreit. Dies bedeutet jedoch, dass Sie nach einem Dokument nicht an Knoten "festhalten" sollten. Dies führt zu undefinierten Verhaltens- oder Zugriffsverstößen.
Um beispielsweise im obigen Beispiel auf den price des ersten Produkts zugreifen zu können, können Sie den folgenden Code verwenden:
Price := Doc.Root.Values[ ' product ' ].Nodes[ 0 ].Values[ ' price ' ].ToDouble; Sie verwenden die Values -Eigenschaft, um auf Werte zuzugreifen, indem Sie den Schlüssel in der Zuordnung des Mappings aufnehmen. Ebenso wird die Eigenschaft Nodes verwendet, um auf Werte nach Index in einer Sequenz zuzugreifen, und eine der ToXXX -Methoden kann verwendet werden, um einen skalaren Wert in einen Delphi -Datentyp zu konvertieren.
Um den Typ eines Knotens zu überprüfen, können Sie die NodeType -Eigenschaft oder eine der IsXXX -Eigenschaften ( IsMapping , IsScalar usw.) verwenden.
Sie können auch ein YAML -Dokument von Grund auf erstellen und in einer Datei speichern oder in YAML konvertieren. Um ein YAML -Dokument zu erstellen, verwenden Sie je nach Art des Stammknotens, den Sie benötigen, eines der TYamlDocument.CreateXXX -Methoden. Wenn Sie das Beispieldokument rekonstruieren möchten, beginnen Sie mit einer Zuordnung und rufen Sie an:
Doc := TYamlDocument.CreateMapping;Sie können dann anfangen, Schlüssel-/Wertpaare hinzuzufügen:
Doc.Root.AddOrSetValue( ' invoice ' , 34843 );
Doc.Root.AddOrSetValue( ' date ' , ' 2001-01-23 ' ); Mit der AddOrSetValue -Methode wird ein Mapping Taste/Wert -Paare hinzugefügt. Wenn der Knoten keine Zuordnung ist, wird eine Ein EInvalidOperation -Ausnahme angehoben.
Verwenden Sie eine der anderen AddOrSetXXX -Methoden, um einen nicht-scalararischen Wert hinzuzufügen:
var
Products: TYamlNode;
begin
Products := Doc.Root.AddOrSetSequence( ' product ' );
end ; Dies fügt der Zuordnung mit dem product eine Sequenz hinzu. Mit einer der AddXXX -Methoden können Sie der Sequenz Werte hinzufügen. Auch hier wird eine Ein EInvalidOperation -Ausnahme angehoben, wenn der Knoten keine Sequenz ist. Im Beispiel müssen wir dieser Sequenz eine weitere Zuordnung hinzufügen:
var
Product: TYamlNode;
begin
Product := Products.AddMapping;
Product.AddOrSetValue( ' sku ' , ' BL394D ' );
Product.AddOrSetValue( ' quantity ' , 4 );
// etc...
end ; Sobald Sie Ihr Dokument konstruiert haben, können Sie es mit der Save in einer Datei oder einem Stream speichern oder mit der ToYaml -Methode in YAML konvertieren:
var
Yaml: String;
begin
Yaml := Doc.ToYaml;
end ; Sie können einen optionalen TYamlOutputSettings -Datensatz übergeben, um die YAML -Formatierung anzupassen.
Neslib.yaml hat mehr als oben beschrieben. Weitere Informationen finden Sie in der Quelldatei Neslib.Yaml.pas . Zusätzliche Verwendungsproben finden Sie in den Unit -Tests, insbesondere in den Tests.Neslib.Yaml.Sample.pas .
Neslib.yaml ist unter der vereinfachten BSD -Lizenz lizenziert.
Einzelheiten siehe Lizenz.txt.
