Neslib.Yaml
1.0.0
Neslib.yaml es una biblioteca para analizar y emitir YAML y construir documentos y corrientes Yaml.
Neslib.yaml se construye en la parte superior de la biblioteca de Libyaml y trabaja en:
Para instalar:
> git clone --recursive https://github.com/neslib/Neslib.YamlEsta biblioteca solo depende del repositorio de Neslib, que se incluye como submódulo con este repositorio.
Para todas las plataformas, excepto MacOS de 32 bits, no hay dependencias de tiempo de ejecución: la biblioteca LibyAml está vinculada directamente al ejecutable. Para MacOS de 32 bits, debe implementar la biblioteca libyaml_mac32.dylib a la ruta remota ContentsMacOS .
Aquí hay una breve introducción para YAML. Para obtener información más detallada, eche un vistazo al sitio oficial de YAML o uno de los muchos recursos en línea, como este.
Yaml (abreviatura de "Yaml Ain't Markup Language") es un lenguaje de serialización de datos. A diferencia de muchos otros idiomas similares basados en texto (como JSON y XML), un objetivo principal de YAML es ser legible por los humanos y también fácil de crear por humanos. Es por eso que se usa comúnmente para archivos de configuración. Sin embargo, se puede usar para todo tipo de datos, como este ejemplo de la especificación 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 documento YAML es un árbol de valores, llamado nodos ( TYamlNode en esta biblioteca). Hay 4 tipos de nodos:
Las asignaciones son similares a los diccionarios de Delphi. Una asignación es una colección de pares de clave/valor. La nota raíz del documento de muestra anterior es una asignación: asigna la invoice de clave al valor 34843 y contiene otros 7 pares de clave/valor (desde date hasta comments ). Tanto las claves como los valores pueden ser de cualquier tipo YAML, aunque probablemente desee mantener las cuerdas para las teclas.
Las asignaciones se pueden escribir en notación de bloque (como en el ejemplo) o notación de flujo (usando aparatos {} ).
Al usar notación de bloque, Yaml usa sangría para el alcance. Solo se permiten espacios para la sangría ( no pestañas). El número de espacios no importa siempre que todos los valores al mismo nivel usen la misma cantidad de espacios. En el ejemplo, el valor de la clave bill-to es otra mapeo. Este mapeo está sangrado para indicar que pertenece a la clave bill-to .
Las secuencias son como matrices o listas de Delphi. Se pueden escribir pequeñas secuencias utilizando notación de flujo (usando soportes cuadrados [] ). Las secuencias más grandes o complejas generalmente se escriben en notación de bloque como en el ejemplo: el valor de la clave product es una secuencia de dos productos (un baloncesto y un Super Hoop). Cada elemento en la secuencia comienza con un tablero y un espacio.
En este ejemplo, cada producto en la secuencia es una asignación de 4 pares de clave/valor.
Todos los nodos tienen al menos dos propiedades: una Tag y un Anchor . Las etiquetas se utilizan para describir el tipo semántico de un nodo. Las etiquetas no son tan comunes, por lo que las omitiré en esta introducción. Sin embargo, Neslib.yaml tiene soporte completo para las etiquetas.
Se puede usar un ancla para marcar un nodo en el documento. Luego, luego puede referirse a este nodo usando un alias .
Los anclajes tienen un prefijo con un ampersand ( & ). En el ejemplo, el valor de la clave bill-to tiene un ancla llamado id001 (el ampersand no es parte del nombre). Más adelante en el documento, la tecla ship-to se refiere a este ancla usando un alias (un asterisco seguido del nombre del ancla, por ejemplo, *id001 ). Esta es una forma de decir que la dirección de envío es la misma que la dirección de facturación. Tenga en cuenta que un alias no copia el valor referenciado; Realmente solo se refiere a otro nodo.
Los anclajes deben aparecer en el documento antes de que puedan ser referenciados. Sus nombres no tienen que ser únicos dentro del documento; Si se declara un nuevo ancla con el mismo nombre, reemplaza el ancla antigua.
Los escalares son los tipos más simples. Todo lo que no es un mapeo, secuencia o alias es un escalar. En la práctica, los escalares son solo cuerdas. Todas las claves del ejemplo anterior son escalares de cadena, pero muchos de los valores también son (como 34843 , 2001-01-23 y Chris ).
La especificación YAML 1.1 (que es lo que usa Libyaml) trata todos estos escalares como cadenas, incluso si son números o fechas como en este ejemplo. Puede usar etiquetas para afirmar explícitamente que un escalar específico es de un tipo específico.
El registro TYamlNode en esta biblioteca proporciona métodos como ToInteger y ToDouble a (intente) convertir a los tipos de Delphi, independientemente de cualquier etiqueta que pueda conectarse a un nodo.
Los escalares se pueden escribir en diferentes "estilos":
| ). En el ejemplo anterior, el valor bill-to.address.lines es literal. Se conservan cualquier nueva línea en un literal.comments en el ejemplo.Hay mucho más en YAML, pero esto debería cubrir muchos casos de uso.
El principal punto de entrada a esta biblioteca es la interfaz IYamlDocument o IYamlStream .
Un archivo YAML puede contener múltiples documentos. Si ese es el caso, debe usar un IYamlStream para cargarlo. Una transmisión es solo una colección de documentos (de tipo IYamlDocument ).
Sin embargo, la mayoría de las veces, un archivo YAML contiene solo un documento y es más fácil comenzar con un IYamlDocument . Cargar un documento es fácil:
var
Doc: IYamlDocument;
begin
Doc := TYamlDocument.Load( ' invoice.yaml ' );
end ; Puede cargar desde un archivo o transmisión, o puede analizar el texto YAML utilizando el método TYamlDocument.Parse .
Ahora puede usar la propiedad IYamlDocument.Root para inspeccionar el documento. Esta propiedad es de tipo TYamlNode , que es el bloque de construcción para todos los documentos.
Tyamlnode se implementa como un registro para mantenerlo a la luz. Todos los nodos son "propietario" por un documento. Esto hace que la gestión de la memoria sea completamente automática: una vez que un documento sale del alcance, todos sus nodos se liberarán automáticamente. Sin embargo, esto significa que no debe "aferrarse" a los nodos después de que un documento se haya quedado sin alcance. Hacerlo resulta en comportamiento indefinido o violaciones de acceso.
Por ejemplo, para acceder al price del primer producto en el ejemplo anterior, puede usar el siguiente código:
Price := Doc.Root.Values[ ' product ' ].Nodes[ 0 ].Values[ ' price ' ].ToDouble; Utiliza la propiedad Values para acceder a valores por clave en la asignación . Del mismo modo, la propiedad Nodes se usa para acceder a los valores por índice en una secuencia , y uno de los métodos ToXXX se puede utilizar para convertir un valor escalar en un tipo de datos de Delphi.
Para verificar el tipo de nodo, puede usar la propiedad NodeType o una de las propiedades IsXXX ( IsMapping , IsScalar , etc.).
También puede crear un documento YAML desde cero y guardarlo en un archivo o convertirlo en YAML. Para crear un documento YAML, use uno de los métodos TYamlDocument.CreateXXX , dependiendo del tipo de nodo raíz que necesita. Si desea reconstruir el documento de ejemplo, comenzará con una asignación y llame::
Doc := TYamlDocument.CreateMapping;Luego puede comenzar a agregar pares de clave/valor:
Doc.Root.AddOrSetValue( ' invoice ' , 34843 );
Doc.Root.AddOrSetValue( ' date ' , ' 2001-01-23 ' ); El método AddOrSetValue se usa para agregar pares de clave/valor a una asignación. Si el nodo no es un mapeo, entonces se planteará una excepción de EInvalidOperation .
Para agregar un valor no escalar, use uno de los otros métodos AddOrSetXXX :
var
Products: TYamlNode;
begin
Products := Doc.Root.AddOrSetSequence( ' product ' );
end ; Esto agrega una secuencia al mapeo con el product clave. Luego puede agregar valores a la secuencia utilizando uno de los métodos AddXXX . Nuevamente, se planteará una excepción EInvalidOperation si el nodo no es una secuencia. En el ejemplo, necesitamos agregar otra asignación a esta secuencia:
var
Product: TYamlNode;
begin
Product := Products.AddMapping;
Product.AddOrSetValue( ' sku ' , ' BL394D ' );
Product.AddOrSetValue( ' quantity ' , 4 );
// etc...
end ; Una vez que haya construido su documento, puede guardarlo en un archivo o transmitir usando el método Save , o convertirlo en YAML usando el método ToYaml :
var
Yaml: String;
begin
Yaml := Doc.ToYaml;
end ; Puede pasar un registro opcional TYamlOutputSettings para personalizar el formato YAML.
Hay más en neslib.yaml que el descrito anteriormente. Para obtener más detalles, puede ver el archivo de origen Neslib.Yaml.pas bien documentado. Se pueden encontrar muestras de uso adicionales en las pruebas unitarias, especialmente en el archivo Tests.Neslib.Yaml.Sample.pas .
Neslib.yaml tiene licencia bajo la licencia BSD simplificada.
Consulte License.txt para más detalles.
