Neslib.Yaml
1.0.0
Neslib.yaml é uma biblioteca para analisar e emitir YAML e construir documentos e fluxos da YAML.
Neslib.yaml está construído na biblioteca da Líbia e trabalha em:
Para instalar:
> git clone --recursive https://github.com/neslib/Neslib.YamlEsta biblioteca depende apenas do repositório NESLIB, que é incluído como submódulo com este repositório.
Para todas as plataformas, exceto o MacOS de 32 bits, não há dependências em tempo de execução: a biblioteca da Líbia está vinculada diretamente ao executável. Para o MacOS de 32 bits, você precisa implantar a biblioteca libyaml_mac32.dylib no ContentsMacOS .
Aqui está uma introdução muito breve para a YAML. Para informações mais detalhadas, consulte o site oficial da YAML ou um dos muitos recursos on-line como este.
A YAML (abreviação de "Yaml não é marcada com a linguagem") é uma linguagem de serialização de dados. Ao contrário de muitos outros idiomas semelhantes baseados em texto (como JSON e XML), um objetivo principal da YAML é ser legível por humanos e também fácil de criar pelos seres humanos. É por isso que é comumente usado para arquivos de configuração. No entanto, ele pode ser usado para todos os tipos de dados, como este exemplo da especificação 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. Um documento YAML é uma árvore de valores, chamada nós ( TYamlNode nesta biblioteca). Existem 4 tipos de nós:
Os mapeamentos são semelhantes aos dicionários Delphi. Um mapeamento é uma coleção de pares de chave/valor. A nota raiz do documento de amostra acima é um mapeamento: ele mapeia a invoice principal para o valor 34843 e contém 7 outros pares de chave/valor (da date para comments ). As teclas e os valores podem ser qualquer tipo de YAML, embora você provavelmente queira manter strings para chaves.
Os mapeamentos podem ser gravados na notação de bloco (como no exemplo) ou notação de fluxo (usando aparelhos encaracolados {} ).
Ao usar a notação de bloco, a YAML usa o recuo para o escopo. Somente espaços são permitidos para o indentação ( não guias). O número de espaços não importa, desde que todos os valores no mesmo nível usem a mesma quantidade de espaços. No exemplo, o valor da chave bill-to é outro mapeamento. Esse mapeamento é recuado para indicar que pertence à chave bill-to .
As seqüências são como matrizes ou listas Delphi. Pequenas seqüências podem ser escritas usando a notação de fluxo (usando colchetes quadrados [] ). Sequências maiores ou complexas geralmente são escritas em notação de bloco, como no exemplo: o valor da chave product é uma sequência de dois produtos (um basquete e super argolas). Cada item na sequência começa com um painel e um espaço.
Neste exemplo, cada produto na sequência é um mapeamento de 4 pares de chave/valor.
Todos os nós têm pelo menos duas propriedades: uma Tag e uma Anchor . As tags são usadas para descrever o tipo semântico de um nó. As tags não são tão comuns, então vou ignorá -las nesta introdução. Neslib.yaml tem suporte total para tags.
Uma âncora pode ser usada para marcar um nó no documento. Mais tarde, você pode consultar este nó usando um alias .
As âncoras são prefixadas com um ampersand ( & ). No exemplo, o valor da chave bill-to tem uma âncora chamada id001 (o AMPERSAND não faz parte do nome). Posteriormente, o documento, a tecla ship-to a-referência a essa âncora usando um alias (um asterisco seguido pelo nome da âncora, por exemplo, *id001 ). Essa é uma maneira de dizer que o endereço de entrega é o mesmo que o endereço de cobrança. Observe que um alias não copia o valor referenciado; Realmente apenas se refere a outro nó.
As âncoras devem aparecer no documento antes que possam ser referenciadas. Seus nomes não precisam ser únicos no documento; Se uma nova âncora for declarada com o mesmo nome, ele substituirá a âncora antiga.
Os escalares são os tipos mais simples. Tudo o que não é um mapeamento, sequência ou alias é um escalar. Na prática, os escalares são apenas cordas. Todas as chaves no exemplo acima são escalares de cordas, mas muitos dos valores também são (como 34843 , 2001-01-23 e Chris ).
A especificação YAML 1.1 (que é o que a Líbia usa) trata todos esses escalares como strings, mesmo que sejam números ou datas, como neste exemplo. Você pode usar tags para afirmar explicitamente que um escalar específico é de um tipo específico.
O registro TYamlNode nesta biblioteca fornece métodos como ToInteger e ToDouble para (tente) converter para os tipos Delphi, independentemente de quaisquer tags que possam ser anexadas a um nó.
Os escalares podem ser escritos em diferentes "estilos":
| ). No exemplo acima, o valor bill-to.address.lines é literal. Quaisquer novas linhas em um literal são preservadas.comments no exemplo.Há muito mais no YAML, mas isso deve cobrir muitos casos de uso.
O principal ponto de entrada para esta biblioteca é a interface IYamlDocument ou IYamlStream .
Um arquivo YAML pode conter vários documentos. Se for esse o caso, você deve usar um IYamlStream para carregá -lo. Um fluxo é apenas uma coleção de documentos (do tipo IYamlDocument ).
Na maioria das vezes, porém, um arquivo YAML contém apenas um único documento e é mais fácil começar com um IYamlDocument . Carregar um documento é fácil:
var
Doc: IYamlDocument;
begin
Doc := TYamlDocument.Load( ' invoice.yaml ' );
end ; Você pode carregar de um arquivo ou fluxo ou analisar o texto YAML usando o método TYamlDocument.Parse .
Agora você pode usar a propriedade IYamlDocument.Root para inspecionar o documento. Esta propriedade é do tipo TYamlNode , que é o bloco de construção para todos os documentos.
O TyamlNode é implementado como um registro para mantê-lo leve. Todos os nós são "proprietários" por um documento. Isso torna o gerenciamento da memória totalmente automático: uma vez que um documento sai do escopo, todos os seus nós serão libertados automaticamente. Isso significa que você não deve "se apegar" a nós depois que um documento foi esgotado do escopo. Fazer isso resulta em comportamento indefinido ou violações de acesso.
Por exemplo, para acessar o price do primeiro produto no exemplo acima, você pode usar o seguinte código:
Price := Doc.Root.Values[ ' product ' ].Nodes[ 0 ].Values[ ' price ' ].ToDouble; Você usa a propriedade Values para acessar valores por chave no mapeamento . Da mesma forma, a propriedade Nodes é usada para acessar valores por índice em uma sequência , e um dos métodos ToXXX pode ser usado para converter um valor escalar em um tipo de dados Delphi.
Para verificar o tipo de nó, você pode usar a propriedade NodeType ou uma das propriedades IsXXX ( IsMapping , IsScalar etc.).
Você também pode criar um documento YAML a partir do zero e salvá -lo em um arquivo ou convertê -lo em YAML. Para criar um documento YAML, use um dos métodos TYamlDocument.CreateXXX , dependendo do tipo de nó raiz necessário. Se você deseja reconstruir o documento de exemplo, começaria com um mapeamento e ligue para:
Doc := TYamlDocument.CreateMapping;Você pode começar a adicionar pares de chave/valor:
Doc.Root.AddOrSetValue( ' invoice ' , 34843 );
Doc.Root.AddOrSetValue( ' date ' , ' 2001-01-23 ' ); O método AddOrSetValue é usado para adicionar pares de chave/valor a um mapeamento. Se o nó não for um mapeamento, será aumentada uma exceção EInvalidOperation .
Para adicionar um valor não escalar, use um dos outros métodos AddOrSetXXX :
var
Products: TYamlNode;
begin
Products := Doc.Root.AddOrSetSequence( ' product ' );
end ; Isso adiciona uma sequência ao mapeamento com o principal product . Você pode adicionar valores à sequência usando um dos métodos AddXXX . Novamente, uma exceção EInvalidOperation será aumentada se o nó não for uma sequência. No exemplo, precisamos adicionar outro mapeamento a esta sequência:
var
Product: TYamlNode;
begin
Product := Products.AddMapping;
Product.AddOrSetValue( ' sku ' , ' BL394D ' );
Product.AddOrSetValue( ' quantity ' , 4 );
// etc...
end ; Depois de construir seu documento, você pode salvá -lo em um arquivo ou fluxo usando o método Save ou convertê -lo para YAML usando o método ToYaml :
var
Yaml: String;
begin
Yaml := Doc.ToYaml;
end ; Você pode passar por um registro opcional TYamlOutputSettings para personalizar a formatação YAML.
Há mais para Neslib.yaml do que o descrito acima. Para obter mais detalhes, você pode observar o arquivo de origem bem-documental Neslib.Yaml.pas . Amostras de uso adicional podem ser encontradas nos testes de unidade, especialmente nos Tests.Neslib.Yaml.Sample.pas .
Neslib.yaml é licenciado sob a licença BSD simplificada.
Consulte License.txt para obter detalhes.
