Todos nós amamos o Ansible, mas o Ansible é YAML. Existem muitos formatos para arquivos de configuração: listas de valores, pares 'chave-valor', arquivos INI, YAML, JSON, XML e muitos outros. No entanto, por algumas razões, de todos eles, o YAML é frequentemente considerado particularmente difícil. Em particular, apesar de seu minimalismo refrescante e de suas impressionantes capacidades para lidar com valores hierárquicos, a sintaxe do YAML pode incomodar com sua abordagem semelhante ao Python em relação a indentação.
Se o YAML te irrita, você pode – e deve! – dar os seguintes 10 passos para reduzir seu desconforto a um nível aceitável e amar o YAML. Como em uma lista verdadeira, nossos dez conselhos começarão do zero, meditação e práticas espirituais ficam a seu critério 😉
0. Faça seu editor funcionar
Não importa qual editor de texto você tenha – certamente existe pelo menos um plugin para trabalhar com YAML. Se você não tiver um, encontre e instale imediatamente. O tempo gasto na busca e na configuração valerá a pena a cada vez que você precisar editar YAML.
Por exemplo, o editor suporta YAML por padrão, enquanto o GNU Emacs precisará de pacotes adicionais, como .
O Emacs no modo YAML e mostrando espaços.
Se seu editor favorito não possui um modo YAML, alguns problemas podem ser solucionados ajustando as configurações. Por exemplo, o editor de texto padrão do GNOME, Gedit, não possui um modo YAML, mas ilumina a sintaxe do YAML por padrão e permite ajustar a indentação:
Configuração de indentação no Gedit.
E o plugin para o Gedit exibe os espaços como pontos, eliminando incertezas sobre os níveis de indentação.
Em outras palavras, dedique tempo para aprender seu editor favorito. Descubra o que ele mesmo ou sua comunidade de desenvolvimento oferecem para trabalhar com YAML e use essas funcionalidades. Você definitivamente não vai se arrepender.
1. Use um linter
Idealmente, linguagens de programação e linguagens de marcação usam uma sintaxe previsível. Os computadores dão conta da previsibilidade, por isso, em 1978, surgiu o conceito de . Se nos últimos 40 anos esse conceito passou despercebido por você e você ainda não usa um linter de YAML, agora é a hora de experimentar o yamllint.
Instalar pode ser feito com o gerenciador de pacotes padrão do Linux. Por exemplo, em 8 ou isso é feito assim:
$ sudo dnf install yamllint
Depois, você apenas executa o yamllint, passando o arquivo YAML para verificação. Veja como fica ao passar um arquivo com erro para o linter:
$ yamllint errorprone.yaml
errorprone.yaml
23:10 erro erro de sintaxe: valores de mapeamento não são permitidos aqui
23:11 erro espaços em branco remanescentes (trailing-spaces)
Os números à esquerda não representam tempo, mas coordenadas do erro: número da linha e coluna. A descrição do erro pode não fazer sentido, mas você sabe exatamente onde ele está. Basta olhar para aquele lugar no código e, provavelmente, tudo ficará claro.
Quando o yamllint não encontra erros no arquivo, nada é exibido na tela. Se a silenciosa ausência de feedback o incomoda e você quer um retorno um pouco maior, pode executar o linter com um comando condicional echo através de um duplo e comercial (&&), assim:
$ yamllint perfect.yaml && echo "OK"
OK
No POSIX, o duplo e comercial só funciona quando o comando anterior retorna 0. E o yamllint retorna exatamente a quantidade de erros encontrados, então toda essa estrutura condicional funciona.
2. Escreva em Python, não em YAML
Se o YAML realmente o irrita, simplesmente não escreva nele, literalmente. Às vezes, o YAML é o único formato que o aplicativo aceita. Mas mesmo assim, não é necessário criar um arquivo YAML. Escreva no que você gosta e depois converta. Por exemplo, para Python, há uma excelente biblioteca e existem dois métodos de conversão: autoconversão e conversão através de scripts.
Autoconversão
Nesse caso, o arquivo de dados também é um script Python que gera YAML. Esse método é mais adequado para pequenos conjuntos de dados. Você apenas escreve os dados JSON em uma variável Python, precede com a diretiva import e, ao final do arquivo, adiciona três linhas para realizar a saída.
#!/usr/bin/python3
import yaml
d={
"glossary": {
"title": "example glossary",
"GlossDiv": {
"title": "S",
"GlossList": {
"GlossEntry": {
"ID": "SGML",
"SortAs": "SGML",
"GlossTerm": "Standard Generalized Markup Language",
"Acronym": "SGML",
"Abbrev": "ISO 8879:1986",
"GlossDef": {
"para": "A meta-markup language, used to create markup languages such as DocBook.",
"GlossSeeAlso": ["GML", "XML"]
},
"GlossSee": "markup"
}
}
}
}
}
f=open('output.yaml','w')
f.write(yaml.dump(d))
f.close
Agora, execute este arquivo em Python e na saída obteremos o arquivo output.yaml:
$ python3 ./example.json
$ cat output.yaml
glossary:
GlossDiv:
GlossList:
GlossEntry:
Abbrev: ISO 8879:1986
Acronym: SGML
GlossDef:
GlossSeeAlso: [GML, XML]
para: Uma linguagem de metamarcação, usada para criar linguagens de marcação como DocBook.
GlossSee: marcação
GlossTerm: Linguagem de Marcação Geral Padrão
ID: SGML
SortAs: SGML
title: S
title: exemplo de glossário
Este é um YAML absolutamente correto, mas o yamllint emitirá um aviso de que ele não começa com —. Bem, isso pode ser facilmente corrigido manualmente ou ligeiramente ajustando o script Python.
Conversão via scripts
Neste caso, primeiro escrevemos em JSON e depois executamos o conversor como um script Python separado, que, como saída, fornece YAML. Em comparação com o anterior, este método se escala melhor, pois a conversão é separada dos dados.
Para começar, vamos criar um arquivo JSON chamado example.json, por exemplo, você pode pegá-lo em :
{
"glossary": {
"title": "exemplo de glossário",
"GlossDiv": {
"title": "S",
"GlossList": {
"GlossEntry": {
"ID": "SGML",
"SortAs": "SGML",
"GlossTerm": "Linguagem de Marcação Generalizada Padrão",
"Acronym": "SGML",
"Abbrev": "ISO 8879:1986",
"GlossDef": {
"para": "Uma linguagem de meta-marcação, usada para criar linguagens de marcação como DocBook.",
"GlossSeeAlso": ["GML", "XML"]
},
"GlossSee": "marcação"
}
}
}
}
}
Em seguida, criaremos um simples script de conversão e o salvaremos como json2yaml.py. Este script importa ambos os módulos — YAML e JSON do Python, além de carregar o arquivo JSON especificado pelo usuário, realizar a conversão e escrever os dados no arquivo output.yaml.
#!/usr/bin/python3
import yaml
import sys
import json
OUT=open('output.yaml','w')
IN=open(sys.argv[1], 'r')
JSON = json.load(IN)
IN.close()
yaml.dump(JSON, OUT)
OUT.close()
Salve este script no caminho do sistema e execute-o conforme necessário:
$ ~/bin/json2yaml.py example.json
3. Parse muitos e frequentemente
Às vezes, é útil olhar para o problema de um ângulo diferente. Se você tem dificuldade em visualizar as relações entre os dados em YAML, pode temporariamente convertê-los em algo mais familiar.
Por exemplo, se você se sente mais confortável trabalhando com listas de dicionários ou com JSON, você pode converter YAML em JSON com apenas dois comandos na interface interativa do Python. Suponha que você tenha um arquivo YAML chamado mydata.yaml, então aqui está como isso ficaria:
$ python3
>>> f=open('mydata.yaml','r')
>>> yaml.load(f)
{'document': 34843, 'date': datetime.date(2019, 5, 23), 'bill-to': {'given': 'Seth', 'family': 'Kenlon', 'address': {'street': '51b Mornington Roadn', 'city': 'Brooklyn', 'state': 'Wellington', 'postal': 6021, 'country': 'NZ'}}, 'words': 938, 'comments': 'Bom artigo. Poderia ser melhor.'}
Você pode encontrar muitos outros exemplos sobre esse assunto. Além disso, há muitos conversores online e parsers locais disponíveis. Portanto, não hesite em reformatar os dados quando vê-los apenas como uma confusão incompreensível.
4. Leia as especificações
Voltando ao YAML após um longo intervalo, é útil visitar e reler as especificações. Se você está com dificuldades com YAML, mas ainda não chegou nas especificações, é hora de corrigir essa situação. As especificações são surpreendentemente bem escritas e os requisitos de sintaxe são ilustrados com muitos exemplos em .
5. Pseudoconfigurações
Ao escrever um livro ou artigo, é sempre útil primeiro elaborar um esboço, mesmo que seja na forma de um índice. O mesmo se aplica ao YAML. Provavelmente, você tem uma ideia dos dados que precisa registrar no arquivo YAML, mas não entende muito bem como conectá-los uns aos outros. Portanto, antes de criar o YAML, desenhe um pseudoconfig.
O pseudoconfig é semelhante ao pseudocódigo, onde não é necessário se preocupar com a estrutura ou com a indentação, as relações "pai-filho", herança e aninhamento. Assim, aqui você desenha iterações de dados à medida que eles vêm à sua cabeça.
Pseudoconfig com a enumeração de programadores (Martin e Tabitha) e suas habilidades (linguagens de programação: Python, Perl, Pascal e Lisp, Fortran, Erlang, respectivamente).
Depois de desenhar o pseudoconfig em uma folha de papel, analise-o cuidadosamente e, se estiver tudo certo, transforme-o em um arquivo YAML válido.
6. O dilema "tabulação ou espaços"
Você terá que resolver o dilema . Não em um sentido global, mas apenas ao nível da sua organização ou pelo menos do projeto. Não importa se o processamento posterior será feito com um script sed, configurações de editores de texto nos computadores dos programadores ou mesmo uma coleta sistemática de recibos de estrita conformidade com as instruções do linters sob ameaça de demissão, todos os membros da sua equipe que, de alguma forma, lidam com YAML, devem obrigatoriamente usar apenas espaços (como exige a especificação YAML).
Em qualquer editor de texto normal, você pode configurar a substituição automática de tabulações por um determinado número de espaços, portanto, não é necessário temer uma revolta dos defensores da tecla Tab .
Como cada inimigo do YAML bem sabe, na tela não há diferença visível entre tabulações e espaços. E quando algo não é visível, geralmente é lembrado por último, depois que todas as outras possíveis questões foram avaliadas, verificadas e corrigidas. Uma hora perdida tentando encontrar uma tabulação incorreta ou um bloco de espaços clama por você precisar urgentemente criar uma política sobre o uso de um ou outro, e, em seguida, implementar uma verificação rigorosa de conformidade (por exemplo, através de um hook do Git para forçar a execução de um linter).
7. Melhor menos, mas melhor (ou mais – isso é menos)
Algumas pessoas gostam de escrever em YAML, pois ele destaca a estrutura. Para isso, elas usam ativamente recuos para enfatizar blocos de dados. É uma espécie de trapaça para simular linguagens de marcação que usam separadores explícitos.
Aqui está um exemplo dessa estruturação a partir de :
# Employee records
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang
Para alguns, essa abordagem ajuda a organizar a estrutura do YAML na mente, enquanto outros se irritam com a quantidade de recuos desnecessários, na opinião deles.
Mas se você é o proprietário de um documento YAML e é responsável por sua manutenção, então você e somente você deve determinar como usar os recuos. Se você se incomoda com grandes recuos, reduza-os ao mínimo possível de acordo com a especificação YAML. Por exemplo, o arquivo acima da documentação do Ansible pode ser reescrito assim sem qualquer perda:
---
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang
8. Use templates
Se ao preencher um arquivo YAML, você comete constantemente os mesmos erros, faz sentido inserir um modelo como comentário. Assim, da próxima vez, você pode simplesmente copiar esse modelo e preenchê-lo com os dados reais, por exemplo:
---
# - <common name>:
# name: Sobrenome Dado
# job: TRABALHO
# skills:
# - LINGUAGEM
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang
9. Use outra coisa
Se o aplicativo não o manter amarrado, talvez seja hora de mudar o YAML para outro formato. Com o tempo, arquivos de configuração podem se tornar complexos e é melhor transformá-los em scripts simples em Lua ou Python.
YAML é uma excelente ferramenta, que muitos apreciam por seu minimalismo e simplicidade, mas não é a única ferramenta em seu arsenal. Portanto, às vezes, é possível abrir mão dele. É fácil encontrar bibliotecas de análise para YAML, então, se você oferecer opções convenientes de migração, seus usuários passarão por essa transição relativamente sem dor.
Se você realmente não pode evitar o YAML, aproveite essas 10 dicas e vença sua aversão ao YAML de uma vez por todas!
Fonte: habr.com
