Tabla de puntuaciones

Objetos

Un objeto JSON es, por usar terminología de otros lenguajes, un «hash», un «map» o un «diccionario».

JSON define un objeto así:

Un objeto es un conjunto no ordenado de pares nombre/valor. Un objeto empieza con {, llave izquierda, y termina con }, llave derecha. Cada nombre va seguido de : (dos puntos) y los pares nombre/valor se separan con , (coma).

El nombre debe ser un string. Otra palabra para nombre es clave.

El valor puede ser de cualquier tipo de JSON. Distintos valores dentro del mismo objeto pueden ser de tipos diferentes, como en este ejemplo.

{
  "name": "Jane",
  "age": 42,
  "pets": ["cat", "fish"],
  "address": {"street": "123 Main St", "city": "Springfield"}
}

Ten en cuenta que no debe haber una coma después del último par clave-valor.

Crear objetos

Usa llaves para agrupar los pares nombre/valor. Aunque los nombres deben ser strings, no hace falta entrecomillarlos si son similares a un identificador (están formados por caracteres alfanuméricos y guiones bajos, y no empiezan por un dígito).

{name: "Jane", age: 42}

Es válido usar claves que no sean similares a un identificador. Solo tienes que entrecomillarlas.

{"first name": "Jane", "last name": "Lopez", age: 42}

Si el nombre es el resultado de una expresión, la expresión debe ir entre paréntesis.

$ echo "Jane" | jq -Rc '{.: 42}'
# verbose error message ...

$ echo "Jane" | jq -Rc '{(.): 42}'
{"Jane":42}

Indexación

Los valores se obtienen de un objeto con la notación de punto.

{name: "Jane", age: 42} | .age    # => 42

Si no puedes referirte a la clave como un identificador, usa la notación de corchetes.

"name" as $key | {name: "Jane", age: 42} | .$key    # => error
"name" as $key | {name: "Jane", age: 42} | .[$key]  # => "Jane"

Añadir o cambiar pares clave-valor

Para añadir un nuevo par clave-valor a un array, o para actualizar el valor de una clave existente, usa el operador de asignación =, con una expresión de índice en el lado izquierdo.

{name: "Jane", age: 42} | .sport = "tennis" | .age = 21
# => {
#      "name": "Jane",
#      "age": 21,
#      "sport": "tennis"
#    }

El operador + fusiona objetos.

{Richard: 54} + {Jane: 42}
# => {
#      "Richard": 54,
#      "Jane": 42
#    }

Eliminar una clave

Usa la función del para eliminar una clave. Devuelve el objeto actualizado.

{name: "Jane", age: 42} | del(.age)   # => {"name": "Jane"}

El parámetro de del es una expresión de índice (con notación de punto o de corchetes) que se resuelve en una clave del objeto. jq la llama expresión de ruta. No basta con dar simplemente un string.

{name: "Jane", age: 42} | del(name)        # error: name/0 is not defined
{name: "Jane", age: 42} | del("name")      # error: Invalid path expression with result "name"
{name: "Jane", age: 42} | del(.name)       # OK
{name: "Jane", age: 42} | del(.["name"])   # OK

Pertenencia

• Para comprobar si el objeto tiene una clave, usa la función has.

  {name: "Jane", age: 42} as $example
  |
    ($example | has("name")),    # => true
    ($example | has("sport"))    # => false
  

• Comprueba si una clave está en un objeto con in.

  {name: "Jane", age: 42} as $example
  |
    ("name"  | in($example)),    # => true
    ("sport" | in($example))     # => false
  

Enumerar todas las claves

Usa la función keys para obtener un array con todas las claves.

{name: "Jane", age: 42} | keys   # => ["age", "name"]

Ten en cuenta que keys ordena las claves. Para obtener las claves en el orden original, usa keys_unsorted.

No hay ninguna función equivalente para enumerar todos los valores. Sin embargo, el filtro .[] genera los valores del objeto como un flujo, y ese flujo se puede capturar con el constructor de arrays [...].

[{first: "Jane", last: "Lopez", status: "awesome!"} | .[]]
# => ["Jane", "Lopez", "awesome!"]

Iterar

• La función map_values(filter) aplica el filtro a cada valor del objeto.

  {first: "Jane", last: "Lopez", status: "awesome!"}
  | map_values(ascii_upcase)
  # => {"first": "JANE", "last": "LOPEZ", "status": "AWESOME!"}
  

• Para iterar sobre un objeto, primero tenemos que convertirlo en un array de objetos clave-valor. La función to_entries hace eso.

  {name: "Jane", age: 42} | to_entries'
  # => [
  #      {
  #        "key": "name",
  #        "value": "Jane"
  #      },
  #      {
  #        "key": "age",
  #        "value": 42
  #      }
  #    ]
  

  En este punto, podemos usar funciones de iteración de arrays, como map.

• La función from_entries es la inversa: convierte un array de objetos clave-valor en un objeto.

  [
    {"key":"name", "value":"Jane"},
    {"key":"age", "value":42}
  ] | from_entries                  # =>{"name": "Jane", "age": 42}
  

• Para aplicar un filtro a cada par clave-valor de un objeto, usa la función with_entries(filter).

  Por ejemplo, dado un objeto que asocia un nombre a una edad, las claves y los valores se pueden intercambiar así.

  {"Jane": 42, "Richard": 54}
  | with_entries({key: (.value | tostring), value: .key})
  

  produce

  {
    "42": "Jane",
    "54": "Richard"
  }
  

  with_entries(filter) es lo mismo que

  to_entries | map(filter) | from_entries