Todos nós amamos o Ansible, mas o Ansible é o YAML. Existem muitos formatos para arquivos de configuração: listas de valores, pares parâmetro-valor, arquivos INI, YAML, JSON, XML e muitos outros. No entanto, por várias razões, dentre todas elas, a YAML é frequentemente considerada particularmente difícil. Em particular, apesar de seu minimalismo refrescante e recursos impressionantes para trabalhar com valores hierárquicos, a sintaxe YAML pode ser irritante com sua abordagem de indentação semelhante ao Python.
Se o YAML o enfurece, você pode - e deve! - Siga as 10 etapas a seguir para reduzir sua irritação a um nível aceitável e adorar o YAML. Como deve estar nesta lista, nossas dez dicas serão numeradas do zero, acrescentamos meditação e práticas espirituais à vontade ;-)
0. Faça seu editor funcionar
Não importa que tipo de editor de texto você tenha - para ele, com certeza, há pelo menos um plugin para trabalhar com o YAML. Se você não tiver um, localize e instale imediatamente. O tempo gasto na pesquisa e configuração será recompensado várias vezes sempre que você precisar editar o YAML.
Por exemplo, o editor
Atom suporta YAML por padrão, mas o GNU Emacs precisará instalar pacotes adicionais, por exemplo,
modo yaml .
Emacs no modo YAML e espaços de exibição.Se o seu editor favorito não tiver o modo YAML, alguns dos problemas poderão ser resolvidos trabalhando com as configurações. Por exemplo, o editor de texto Gedit padrão para GNOME não possui o modo YAML, mas o padrão é destacar a sintaxe YAML e permite configurar o recuo:
Configurações de recuo do Gedit.E o
plug- in
drawspaces do Gedit exibe os espaços como pontos, eliminando ambiguidades com os níveis de indentação.
Em outras palavras, reserve um tempo para estudar seu editor favorito. Descubra o que ele ou sua comunidade de desenvolvimento está oferecendo para trabalhar com o YAML e use esses recursos. Você definitivamente não vai se arrepender.
1. Use um linter (linter)
Idealmente, as linguagens de programação e marcação usam sintaxe previsível. Os computadores fazem um bom trabalho de previsibilidade; portanto, em 1978, o conceito de
ponte apareceu . Se, durante 40 anos de sua existência, passou por você e você ainda não usa o YAML-linter, é hora de tentar o yamllint.
Você pode instalar o
yamllint usando o gerenciador de pacotes padrão do Linux. Por exemplo, no
Red Hat Enterprise Linux 8 ou no
Fedora, isso é feito assim:
$ sudo dnf install yamllint
Em seguida, basta executar o yamllint, passando o arquivo YAML para verificação. Aqui está o que parece se você passar um arquivo de erro para o linter:
$ yamllint errorprone.yaml errorprone.yaml 23:10 error syntax error: mapping values are not allowed here 23:11 error trailing spaces (trailing-spaces)
Os números à esquerda não são de tempo, mas as coordenadas do erro: número da linha e da coluna. A descrição do erro pode não lhe dizer nada, mas você sabe exatamente onde está. Basta olhar para este lugar no código e, provavelmente, tudo ficará claro.
Quando o yamllint não encontra erros no arquivo, nada é exibido. Se você tem medo desse silêncio e deseja um pouco mais de feedback, pode iniciar o linter com o comando eco condicional através do duplo e comercial (&&), assim:
$ yamllint perfect.yaml && echo "OK" OK
No POSIX, um duplo e comercial é acionado se, e somente se, o comando anterior retornar 0. E yamllint retorna o número de erros encontrados, portanto toda essa construção condicional funciona.
2. Escreva em Python, não em YAML
Se o YAML realmente o irritar, simplesmente não escreva nele, literalmente. Acontece que o YAML é o único formato percebido pelo aplicativo. Mas, nesse caso, não é necessário criar um arquivo YAML. Escreva sobre o que você gosta e depois converta. Por exemplo, para Python, há uma excelente biblioteca
pyyaml e dois métodos de conversão completos: autoconversão e conversão baseada em script.
Auto-conversão
Nesse caso, o arquivo de dados também é um script Python que gera YAML. Este método é mais adequado para pequenos conjuntos de dados. Você simplesmente grava dados JSON em uma variável Python, prefixa-os com a diretiva de importação e adiciona três linhas no final do arquivo para implementar 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 esse arquivo em Python e o arquivo de saída é output.yaml:
$ python3 ./example.json $ cat output.yaml glossary: GlossDiv: GlossList: GlossEntry: Abbrev: ISO 8879:1986 Acronym: SGML GlossDef: GlossSeeAlso: [GML, XML] para: A meta-markup language, used to create markup languages such as DocBook. GlossSee: markup GlossTerm: Standard Generalized Markup Language ID: SGML SortAs: SGML title: S title: example glossary
Isso é YAML absolutamente correto, mas o yamllint avisará que ele não começa com ---. Bem, isso pode ser facilmente corrigido manualmente ou script Python ligeiramente modificado.
Converter via scripts
Nesse caso, primeiro escrevemos em JSON e, em seguida, executamos o conversor na forma de um script Python separado, que gera YAML na saída. Comparado com o anterior, esse método é melhor dimensionado porque a conversão é separada por dados.
Primeiro, crie o arquivo JSON example.json, por exemplo, você pode
acessá- lo em
json.org :
{ "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" } } } } }
Em seguida, crie um conversor de script simples e salve-o com o nome json2yaml.py. Esse script importa os dois módulos - YAML e JSON Python, e também baixa o arquivo JSON especificado pelo usuário, executa a conversão e grava 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 conforme necessário:
$ ~/bin/json2yaml.py example.json
3. Analise muito e frequentemente
Às vezes, é útil olhar para o problema de um ângulo diferente. Se você achar difícil imaginar os relacionamentos entre os dados no YAML, poderá transformá-los temporariamente em algo mais familiar.
Por exemplo, se você estiver confortável trabalhando com listas de dicionário ou com JSON, o YAML poderá ser convertido em JSON com apenas dois comandos no shell interativo do Python. Suponha que você tenha um arquivo YAML mydata.yaml, aqui está como ele 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 Road\n', 'city': 'Brooklyn', 'state': 'Wellington', 'postal': 6021, 'country': 'NZ'}}, 'words': 938, 'comments': 'Good article. Could be better.'}
Muitos outros exemplos podem ser encontrados sobre esse assunto. Além disso, existem muitos conversores online e analisadores locais. Portanto, não hesite em reformatar os dados quando vir apenas neles um hash incompreensível.
4. Leia as especificações
Voltando ao YAML após um longo intervalo, é útil ir para
yaml.org e reler as especificações. Se você tiver dificuldades com o YAML, mas suas mãos não atingiram as especificações, é hora de corrigir essa situação. As especificações são surpreendentemente fáceis de escrever e os requisitos de sintaxe são ilustrados por um grande número de exemplos no
Capítulo 6 .
5. Pseudoconfigs
Ao escrever um livro ou artigo, é sempre útil esboçar um plano preliminar, pelo menos na forma de um índice. O mesmo acontece com o YAML. Provavelmente, você imagina quais dados precisa gravar no arquivo YAML, mas não entende realmente como relacioná-los. Portanto, antes de esculpir o YAML, desenhe uma pseudo-configuração.
A pseudo-configuração é semelhante ao pseudo-código, onde você não precisa se preocupar com estrutura ou indentação, relacionamentos pai-filho, herança e aninhamento. Então está aqui: você desenha iterações de dados à medida que elas surgem em sua cabeça.
Uma pseudo-configuração listando programadores (Martin e Tabitha) e suas habilidades (linguagens de programação: Python, Perl, Pascal e Lisp, Fortran, Erlang, respectivamente).Depois de desenhar uma pseudo-configuração em um pedaço de papel, analise-o cuidadosamente e, se tudo estiver em ordem, formate-o como um arquivo YAML válido.
6. A guia ou dilema do dilema
Você precisa resolver o dilema
"abas ou espaços?" . Não no sentido global, mas apenas no nível da sua organização, ou pelo menos em um projeto. Não importa se o pós-processamento pelo script sed é usado, a configuração dos editores de texto nas máquinas dos programadores ou o recebimento geral de recibos por estrita observância das instruções do linter sob a ameaça de demissão, mas todos os membros de sua equipe que de alguma forma se relacionam com o YAML devem Use apenas espaços (conforme exigido pela especificação YAML).
Em qualquer editor de texto normal, você pode definir as guias de AutoCorreção com um número especificado de espaços, para não ter medo dos motins da
guia .
Como todo odiador do YAML está ciente, a diferença entre guias e espaços não é visível na tela. E quando algo não está visível, isso geralmente é lembrado por último, depois de ter sido classificado, verificado e eliminado todos os outros problemas possíveis. O tempo gasto para procurar uma curva de tabulação ou um bloco de espaços simplesmente clama que você precisa criar urgentemente uma política para usar um ou outro e, em seguida, implementar uma verificação concreta reforçada de sua conformidade (por exemplo, por meio de um gancho Git para execução forçada no linter).
7. Melhor menos é melhor (ou mais é menos)
Algumas pessoas gostam de escrever no YAML porque isso enfatiza a estrutura. Ao mesmo tempo, eles usam ativamente o recuo para destacar os blocos de dados. Esse é um tipo de golpe para simular linguagens de marcação que usam delimitadores explícitos.
Aqui está um exemplo dessa estruturação da
documentação do
Ansible :
# 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 opção ajuda a decompor a estrutura YAML na cabeça; pelo contrário, incomoda outros com muito recuo indesejável, na opinião deles.
Mas se você é o proprietário de um documento YAML e é responsável por sua manutenção,
você e somente você deve determinar como usar o recuo. Se você estiver incomodado com um grande recuo, mantenha-os no mínimo possível, de acordo com a especificação YAML. Por exemplo, o arquivo acima da documentação do Ansible pode ser reescrito sem nenhuma perda como esta:
--- - martin: name: Martin D'vloper job: Developer skills: - python - perl - pascal - tabitha: name: Tabitha Bitumen job: Developer skills: - lisp - fortran - erlang
8. Use espaços em branco
Se você repetir constantemente os mesmos erros ao preencher o arquivo YAML, faz sentido inserir um modelo em branco nele como um comentário. Da próxima vez, será possível simplesmente copiar esta peça de trabalho e inserir dados reais, por exemplo:
--- # - <common name>: # name: Given Surname # job: JOB # skills: # - LANG - 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 mantiver em um estrangulamento, talvez valha a pena alterar o YAML para outro formato. Com o tempo, os arquivos de configuração podem se superar e é melhor convertê-los em scripts simples em Lua ou Python.
O YAML é uma grande coisa que muitas pessoas adoram por seu minimalismo e simplicidade, mas isso está longe de ser a única ferramenta em seu arsenal. Então, às vezes você pode recusar. É fácil para o YAML encontrar bibliotecas de análise; portanto, se você oferecer opções convenientes de migração, seus usuários sobreviverão a essa falha de maneira relativamente simples.
Se você não pode ficar sem o YAML, leve essas 10 dicas para o serviço e derrote sua antipatia pelo YAML de uma vez por todas!