API YAML

Las utilidades para analizar y serializar YAML están disponibles bajo ptool.yaml y p.yaml.

ptool.yaml.parse

v0.4.0 - Introduced.

ptool.yaml.parse(input) analiza una cadena YAML y la convierte en un valor Lua.

• input (string, obligatorio): El texto YAML.
• Devuelve: El valor Lua analizado. La raíz puede ser cualquier tipo YAML compatible.

Asignación de tipos:

• YAML mapping -> tabla Lua
• YAML sequence -> tabla secuencial Lua (base 1)
• YAML string -> cadena Lua
• YAML integer que cabe en i64 -> entero Lua
• Otro YAML number -> número Lua
• YAML boolean -> booleano Lua
• YAML null -> Lua nil

Comportamiento ante errores:

• Se produce un error si input no es una cadena.
• Un error de sintaxis YAML produce un error cuyo mensaje incluye el detalle del analizador.
• También se produce un error si el valor YAML no puede representarse como un valor Lua de ptool, como un mapping con claves no string o un valor con un tag YAML explícito.

Ejemplo:

local data = p.yaml.parse([[
name: ptool
features:
  - yaml
  - repl
stars: 42
]])

print(data.name)
print(data.features[1])
print(data.stars)

ptool.yaml.get

v0.4.0 - Introduced.

ptool.yaml.get(input, path) lee el valor en una ruta específica dentro de un texto YAML.

• input (string, obligatorio): El texto YAML.
• path ((string|integer)[], obligatorio): Un arreglo de ruta no vacío, como {"spec", "template", "metadata", "name"} o {"items", 1, "name"}.
• Devuelve: El valor Lua correspondiente, o nil si la ruta no existe.

Comportamiento:

• Los segmentos de ruta string seleccionan claves de mappings.
• Los segmentos de ruta integer seleccionan elementos de secuencias usando índices Lua base 1.

Ejemplo:

local text = [[
items:
  - name: alpha
  - name: beta
]]

local first_name = p.yaml.get(text, {"items", 1, "name"})
print(first_name)

ptool.yaml.set

Sin publicar - Introducido.

ptool.yaml.set(input, path, value) escribe un valor en una ruta especificada de un texto YAML y devuelve el texto YAML actualizado.

• input (string, obligatorio): El texto YAML.
• path ((string|integer)[], obligatorio): Un arreglo de ruta no vacío.
• value (valor Lua compatible con YAML, obligatorio): El valor que se va a escribir.
• Devuelve: El texto YAML actualizado.

Comportamiento:

• Se reemplazan las claves de mappings y los elementos de secuencias existentes.
• Se crea la clave final del mapping si no existe.
• Las claves intermedias de mappings que falten se crean cuando el siguiente segmento de ruta también es una clave string.
• Las secuencias no se expanden. Todos los índices de secuencia de la ruta deben existir.
• Se produce un error cuando la ruta no puede recorrerse mediante el tipo de mapping o secuencia esperado.

Ejemplo:

local text = [[
service:
  name: api
ports:
  - 8080
]]

text = p.yaml.set(text, {"service", "enabled"}, true)
text = p.yaml.set(text, {"ports", 1}, 9090)

print(text)

ptool.yaml.stringify

v0.4.0 - Introduced.

ptool.yaml.stringify(value) convierte un valor Lua en texto YAML.

• value (valor Lua compatible con YAML, obligatorio): El valor que se va a codificar.
• Devuelve: La cadena YAML codificada.

Comportamiento:

• Los valores deben ser compatibles con YAML mediante el mismo mapeo de valores Lua usado por ptool.json.stringify.
• Las tablas secuenciales Lua se codifican como secuencias YAML.
• Las tablas Lua con claves string se codifican como mappings YAML.

Ejemplo:

local text = p.yaml.stringify({
  project = "ptool",
  features = {"yaml", "lua"},
  stable = true,
})

print(text)

Notas:

• Solo se admite YAML de un único documento.
• Los mappings YAML deben usar claves string.
• Los tags YAML explícitos no están soportados.
• El argumento path de ptool.yaml.get y ptool.yaml.set debe ser un arreglo no vacío de strings y/o enteros positivos.
• Los segmentos integer son base 1 para coincidir con la indexación de arrays de Lua.