Conversor de XML para YAML

O YAML 1.2 foi desenhado como um superconjunto do JSON, então aqui não há uma árvore separada. O XML é convertido para a mesma estrutura que a página de XML para JSON produz e um serializador diferente a escreve. Cada decisão de mapeamento daquela página se aplica sem mudança: atributos viram chaves com prefixo, texto que divide um elemento com atributos ou filhos vai sob uma chave de texto, um elemento que aparece duas vezes vira uma sequência, e comentários são descartados.

Uma coisa piora. Em JSON quem consome pelo menos vê colchetes; em YAML a diferença entre um item e dois é um escalar indentado contra uma lista de traços, e ninguém nota isso num diff. Use o campo «sempre um vetor» para qualquer coisa que conceitualmente seja uma lista, para que um documento de um item e um de cinquenta produzam a mesma forma.

<order id="00042">
  <total currency="GBP">19.90</total>
  <line sku="0071">Widget</line>
  <line sku="0072">Gasket</line>
  <country>NO</country>
</order>

order:
  attr_id: '00042'
  total:
    attr_currency: GBP
    text: '19.90'
  line:
    - attr_sku: '0071'
      text: Widget
    - attr_sku: '0072'
      text: Gasket
  country: 'NO'

O YAML 1.1 define o seu tipo booleano por enumeração, e a enumeração é mais larga do que qualquer um espera. A página de tipos publicada lista, literalmente: y, Y, yes, Yes, YES, n, N, no, No, NO, true, True, TRUE, false, False, FALSE, on, On, ON, off, Off, OFF. Cada um desses, sem aspas, carrega como booleano.

A consequência tem nome. Um conjunto de códigos de país ISO recebe NO para a Noruega e o analisador entrega false à aplicação. A mesma lista engole uma coluna Sim/Não exportada de uma planilha e qualquer chave escrita on ou off que devia ser texto. O YAML 1.2 estreitou o esquema central para apenas true e false, mas PyYAML, o Psych do Ruby, o Ansible e boa parte do ferramental de Kubernetes ainda resolvem o conjunto do 1.1, então suponha que ele está todo vivo.

O emissor põe aspas simples em qualquer escalar que casa exatamente com essa lista, incluindo as formas de uma só letra, mais null, Null, NULL e o til. Note a sensibilidade a maiúsculas: yES e nO não estão na lista do 1.1 e não recebem aspas, porque nenhum analisador conforme os lê como booleanos tampouco.

O conjunto booleano é o caso famoso, não o comum. A maioria dos valores que quebram são números que nunca foram números, porque o YAML infere um tipo da grafia de um escalar simples exatamente do jeito que o JSON não faz. Um escalar recebe aspas simples quando casa com o conjunto booleano ou nulo, quando casa com uma gramática de número de JSON (cobrindo 42, 19.90 e 1.10), quando tem um zero à esquerda seguido de mais dígitos, quando está vazio, quando começa por um caractere indicador de YAML como um hífen ou uma cerquilha, ou quando tem espaço em alguma das pontas.

Texto de várias linhas não recebe aspas. Ele vira um escalar de bloco literal introduzido por uma barra vertical com indicador de corte. Literal foi escolhido em lugar do dobrado de propósito: um bloco dobrado reflui quebras de linha simples para espaços, destruindo código e endereços embutidos. O indicador de corte remove a quebra de linha final que um bloco acrescentaria.

Alguns valores ainda saem do emissor sem aspas e podem mudar de tipo rio abaixo. Eles são listados em vez de abafados, porque nenhum emissor que use escalares simples resolveu a inferência de tipos do YAML:

• Números sexagesimais. O YAML 1.1 lê 22:22 como um inteiro em base 60, então uma duração vira 1342 no PyYAML. Um analisador 1.2 como o js-yaml devolve a cadeia, então isso depende de qual lado lê o arquivo.
• Grafias hexadecimais. 0x1F carrega como 31 tanto no YAML 1.1 quanto no esquema central do 1.2, então um código de cor hexadecimal precisa de aspas.
• Datas. 2024-01-05 casa com o tipo timestamp do YAML, então js-yaml e PyYAML ambos lhe entregam um objeto de data em vez de uma cadeia.
• Escalares de bloco cuja primeira linha está indentada mais que as linhas seguintes, o que acontece quando uma seção CDATA preserva espaços iniciais. O conserto do YAML é um indicador de indentação explícito depois da barra vertical, que este emissor não escreve.

Esta é a única preparação que vale a pena fazer. Os padrões foram escolhidos para JSON, onde são seguros, e o YAML tem uma gramática mais rigorosa para chaves do que para valores.

O prefixo de atributos padrão é @_ e a chave de texto padrão é #text. Em YAML, @ é um indicador reservado com o qual um escalar simples não pode começar, então uma chave @_id faz o documento não ser analisável: o js-yaml relata «bad indentation of a mapping entry» e o PyYAML relata um caractere que não pode iniciar nenhum token. Um # inicial é pior porque não falha. Uma linha dizendo #text: 19.90 é um comentário, então o arquivo carrega e o valor simplesmente não está lá.

Os dois campos ficam na linha de controles acima do editor. Ponha o prefixo em algo simples como attr_ e a chave de texto em text, e toda chave da saída será um nome YAML comum. Chaves que precisam de aspas por outros motivos, como soap:Body, recebem aspas automaticamente, porque dois-pontos não são legítimos numa chave nua.

Dois passos: analisar o XML com segurança, e então serializar com um dumper a quem você disse para pôr aspas como deve. A metade do XML precisa das bandeiras de entidade de sempre, porque os padrões em Java e .NET resolvem um DOCTYPE. A metade do YAML pede atenção porque os dumpers divergem em quão agressivamente põem aspas.