JSON

JSON #

json defines utilities for converting Starlark values to/from JSON strings. The most recent IETF standard for JSON is https://www.ietf.org/rfc/rfc7159.txt .

Functions #

encode(x) string #

The encode function accepts one required positional argument, which it converts to JSON by cases:

  • A Starlark value that implements Go’s standard json.Marshal interface defines its own JSON encoding.
  • None, True, and False are converted to null, true, and false, respectively.
  • Starlark int values, no matter how large, are encoded as decimal integers. Some decoders may not be able to decode very large integers.
  • Starlark float values are encoded using decimal point notation, even if the value is an integer. It is an error to encode a non-finite floating-point value.
  • Starlark strings are encoded as JSON strings, using UTF-16 escapes.
  • a Starlark IterableMapping (e.g. dict) is encoded as a JSON object. It is an error if any key is not a string.
  • any other Starlark Iterable (e.g. list, tuple) is encoded as a JSON array.
  • a Starlark HasAttrs (e.g. struct) is encoded as a JSON object. It an application-defined type matches more than one the cases describe above, (e.g. it implements both Iterable and HasFields), the first case takes precedence. Encoding any other value yields an error.

Examples #

Basic

Encode a Starlark dict to a JSON string.

load('json', 'encode')
print(encode({'a': 1, 'b': 2}))
# Output: {"a":1,"b":2}

decode(x[, default]) string #

The decode function has one required positional parameter, a JSON string. It returns the Starlark value that the string denotes.

  • Numbers are parsed as int or float, depending on whether they contain a decimal point.
  • JSON objects are parsed as new unfrozen Starlark dicts.
  • JSON arrays are parsed as new unfrozen Starlark lists. If x is not a valid JSON string, the behavior depends on the “default” parameter: if present, Decode returns its value; otherwise, Decode fails.

Examples #

Basic

Decode a JSON string to a Starlark dict.

load('json', 'decode')
print(decode('{"a":10,"b":20}'))
# Output: {'a': 10, 'b': 20}

indent(str, *, prefix="", indent="\t") string #

The indent function pretty-prints a valid JSON encoding, and returns a string containing the indented form. It accepts one required positional parameter, the JSON string, and two optional keyword-only string parameters, prefix and indent, that specify a prefix of each new line, and the unit of indentation.

Examples #

Basic

Indent a JSON string.

load('json', 'indent')
print(indent('{"a":10,"b":20}', indent="  "))
# Output:
# {
#   "a": 10,
#   "b": 20
# }

dumps(obj, indent=0) string #

The dumps function converts a Starlark value to a JSON string, and returns it. It accepts one required positional parameter, the Starlark value, and one optional integer parameter, indent, that specifies the unit of indentation.

Examples #

Basic

Dump a Starlark dict to a JSON string with indentation.

load('json', 'dumps')
print(dumps({'a': 10, 'b': 20}, indent=2))
# Output:
# {
#   "a": 10,
#   "b": 20
# }