A biblioteca padrão
Slide 51 de 85
51jsonA biblioteca padrão

JSON

hive.json trata a declaração de um tipo como o próprio schema JSON. Nenhuma das duas chamadas que fazem o trabalho nomeia um formato: encode(value, codec) é uma função nativa, T.decode(text, codec) é o decodificador que uma declaração deriva, e o que diz JSON é o codec entregue a elas, hive.json.codec(). Outro formato é outro codec nesses mesmos dois lugares — hive.crypto.jwtCodec(secret), hive.net.queryParamsCodec(), hive.term.codec() — e um codec é um valor comum, com o tipo hive.codec.Codec<E> dado pelo erro com que decodificar nele falha.

Decodificar responde com um Result<T, hive.json.JsonError> cujo erro carrega o path que falhou, o que era expected e o que foi found. Codificar segue o tipo estático, então não pode falhar. As regras:

  • Campos que o tipo não declara são ignorados; um que falta é erro a menos que tenha um Default; um Str[3] precisa ter exatamente três.
  • Um número só decodifica em um Int quando escrito como um, então 1.0 não decodifica; um Float de 3.0 é codificado como 3.
  • Uma união é uma chave nomeando a variante, {"Circle": {"radius": 5}}, uma variante que não carrega nada é {"Point": {}}, e um null escolhe a primeira variante do tipo que não carrega nada. T.Variant.decode lê a carga de uma variante, para um documento cuja variante você já sabe — então decode não pode ser o nome de um campo.
  • Uma chave escrita duas vezes fica com o último valor, e qualquer coisa depois do documento além de espaço em branco é erro. Um texto que nem é JSON falha em $, esperando "valid JSON".
  • Um mapa e uma Table não têm JSON; envie o conteúdo deles como um vetor de um tipo declarado. Um Secret também não, já que só o reveal o abre.
A declaração é o schema, e o codec é o formato
type Greeting { name: Str }

proc main(): void {
	body := encode(Greeting("ada"), hive.json.codec())
	echo body

	parsed := Greeting.decode(body, hive.json.codec())
	if parsed is Result.Ok(g) {
		echo "olá, {g.name}!"
	}
}
Um documento que não encaixa diz exatamente onde
type Greeting { name: Str  times: Int }

proc main(): void {
	if Greeting.decode("\{\"name\":\"ada\"}", hive.json.codec()) is Result.Error(why) {
		echo "{why.path}: esperava {why.expected}, encontrou {why.found}"
	}
}
Um codec é um valor
type Greeting { name: Str }

// Genérica no tipo de erro do codec, então uma função só escreve qualquer formato.
func written(codec: hive.codec.Codec<E>): Str {
	return encode(Greeting("ada"), codec)
}

proc main(): void {
	asJson := hive.json.codec()
	echo written(asJson)
	echo written(hive.net.queryParamsCodec())
	echo written(hive.term.codec())
}
Uniões, chaves repetidas, e o que vem depois de um documento
type Shape {
	Circle { radius: Int }
	Point
}

type Greeting { name: Str }

proc main(): void {
	echo encode([Shape.Circle(5), Shape.Point()], hive.json.codec())
	if Shape.decode("null", hive.json.codec()) is Result.Ok(s) {
		echo s                                    // {} — a primeira variante que não carrega nada
	}
	if Greeting.decode(`\{"name": "ada", "name": "grace"}`, hive.json.codec()) is Result.Ok(g) {
		echo g.name                               // grace — a última vence
	}
	if Greeting.decode(`\{"name": "ada"} and more`, hive.json.codec()) is Result.Error(why) {
		echo why.expected                         // the end of the document
	}
}