O presente documento tem a intenção de explicar, de forma objetiva, o que é YAML, bem como se estrutura um arquivo .yml.
Para atingir esse fim, utilizarei de comentários à ordenação de um arquivo comum, para explicar cada parte.
--- Todo arquivo, ou bloco no fluxo, inicia por três hifens.
# Todo comentário é precedido por ‘#’.
Definição: YAML é o acrônimo de YAML Ain’t Markup Language¹. A linguagem tem o intuito de representar todos os dados, de forma adequada, utilizando-se para isto da combinação de listas, hashes (mapas) e dados escalares (valores simples).
A sua sintaxe é estruturada de maneira a permitir a fácil leitura e compreensão por pessoas e o fácil mapeamento pelos tipos de dados comumente encontrados na maior parte das linguagens de alto-nível.
Sua notação é baseada em indentação e um conjunto de caracteres sigil distintos dos que são usados pelo XML, fazendo com que as duas linguagens, YAML e XML, sejam facilmente compostas uma na outra.
YAML utiliza a codificação de caracteres unicode (UTF-8 ou UTF-16);
A estrutura do documento utiliza a identação com espaços em branco, não sendo permitido o uso de caracteres de tabulação para este fim;
Os itens das listas são iniciados por hífen nos títulos e serão alocados cada um em uma linha, ou entre colchetes. Neste último caso, os itens serão separados por uma vírgula seguida de espaço;
As chaves são sucedidas por dois pontos, seguido por um espaço. Tal como em “Uma Chave Qualquer: valor” e serão alocadas uma por linha . Uma outra forma de alinhar as chaves, também chamadas de ‘valores associativos’, é inseri-las entre chaves, separando-as co vírgula e espaço.
Um valor de um vetor associativo vem precedida por um sinal interrogação (? ), o que permite que se construam chaves complexas sem ambiguidade.
Nas aspas duplas, os caracteres especiais podem ser representados com sequências de escape similares a da linguagem de programação C, que começam com uma barra invertida.
Pode-se incluir múltiplos documentos dentro de um único fluxo, separando-os por três traços ( --- ); os três pontos ( ... ) indicam o fim de um documento dentro de um fluxo.
Os comentários são encabeçados por cerquilha ( # ) e continuam até o final da linha.
Os documentos YAML podem ser precedidos por diretivas compostas por um sinal de porcentagem ( % ) seguidos de um nome e parâmetros delimitados por um espaço.
A diretiva %YAML é utilizada para identificar a versão do YAML em um documento.
A diretiva %TAG é utilizada como atalho para prefixos de URIs.
YAML requer que as vírgulas e pontos sejam utilizados como separadores nas listas seguidos por um espaço, de forma que os valores escalares que contenham sinais de pontuação possam se representar sem a necessidade de utilizar aspas.
Exemplos de linguagens Markup: XML, HTML, XHTML.
¹ Markup Language é uma forma de anotação de texto que permite que as funções sintáticas sejam perceptíveis e distinguíveis. Na área de tecnlogia é usada para codificar o dado, determinando a forma como será interpretado pela máquina (sua função), bem como estabelecer (em alguns casos) como se dará a sua apresentação.
² *Características retiradas da Wikipédia: https://pt.wikipedia.org/wiki/YAML *.
… # Todo arquivo, ou bloco no fluxo, finaliza com três pontos.
O objeto raiz em um arquivo YAML, que se estende por toda a sua estrutura, tem a função de um mapa. Em outras linguagens, seria equivalente a um dicionário, hash, ou objeto.
esta_é_uma_chave: um valor # Aqui inserimos o valor que define a chave
esta_é_outra_chave: um outro valor # Aqui inserimos o valor que específica a função descrita.
esta_chave_tem_um_valor_numerico: 100 # Se um atributo numérico se faz necessário, ele é inserido tal como se mostra.
esta_chave_tem_a_escrita_cientifica: 1e+12 # Se for necessário, podemos usar da escrita científica, sem correr risco de não interpretação do nosso código.
esta_chave_recebe_o_valor_boleano: true # Podemos usar de valores da lógica boleana, se preciso.
esta_chave_recebe_o_valor_nulo: null # Se uma nulidade precisar ser especificada, podemos fazê-lo sem falhas.
esta chave é escrita com espaço: valor # A string pode ser escrita com espaço, sem a necessidade _ para interligar suas partes.
As strings não precisam se escritas entre aspas. Porém, podemos usá-las com aspas simples ou duplas, caso queiramos. Por exemplo:
string_01: 'Uma string, entre aspas simples.'
string_02: "Uma string, entre aspas duplas."
Veja o exemplo abaixo, para melhor compreender. Nele temos um código de tradução de uma aplicação financeira:
pt-BR: action_reasons: opening_balance: 'Saldo Inicial' account_payment_via_app: 'Pagamento de conta via aplicativo' transfer_between_XurumelasPay_accounts: 'Transferência entre contas XurumelasPay' lottery_withdrawal: 'Saque na lotérica' lottery_deposit: 'Depósito na lotérica' receipt_via_XurumelasCesta_partner: 'Recebimento via XurumelasCesta' cell_phone_recharge: 'Recarga de Celular' deposit: 'Depósito' reversal: 'Estorno de Pagamento' ted: 'TED para outros bancos' fee: 'Taxa de transação'
Não é muito usual, mas você pode escrever as chaves entre aspas, também.
"Esta é uma chave, escrita entre aspas": a string está sem.
Podemos escrever as nossas chaves em estilo de blocos, que nada mais são que o agrupamento de linhas sequenciais.
Os blocos podem ser ‘Literais’ ou ‘Compactos’. Para escrever uma chave de bloco literal, devemos utilizar o pipe ( | ); para bloco compacto, usamos o sinal de maior ( > ).
Todo texto inserido aqui, será o valor da chave, em estilo de bloco literal, que terá preservada a quebra de linhas, que fizermos. O bloco literal terá sua estrutura mantida até o ponto em que modificarmos a indentação do código. As linhas que receberem o novo padrão, formarão um novo bloco e terão a sua estrutura mantida e a indentação preservada. Atente para o fato de que estas linhas terão quatro espaços em seu início, para estabelecer sua notação. Isto vale para novos níveis criados. :)
estilo_compacto: >
Todo esse bloco de texto será o valor de ‘estilo_compacto’, mas esta
vez, todas as novas linhas serão substituídas com espaço simples.
Linhas em branco, como acima, são convertidas em um caractere de nova linha. Linhas 'mais-indentadas' mantém suas novas linhas também - este texto irá aparecer em duas linhas.
Espero que essas informações possam-lhes serem úteis e ajudarem nas atividades diárias.
