json — `n_pbt_json` #

← Referência dos componentes · Índice do guia

Construir um JSON tipo a tipo — texto, número, booleano, array, objeto aninhado — com o escape feito por si, e depois ler um ao longo de um caminho: of_load, of_get_string, of_type, of_count. Um único objeto constrói os seus pedidos e lê as suas respostas. Tudo em PowerScript puro: sem página, sem motor, PowerBuilder 10 incluído.

▶ Ver ao vivo — Aplicação de demonstração, mosaico JSON: os resultados, o código que os produz e esta página, lado a lado.

Em resumo #

n_pbt_json é autoinstantiate: declara-se como variável local, sem create nem destroy. É o mesmo objeto que, internamente, constrói os payloads enviados ao motor — agora oferecido ao seu código, do lado da construção e da leitura.

Início rápido #

Construir um payload, depois reler uma resposta — tudo cabe numa variável local:

n_pbt_json  lnv_json
string      ls_customer
double      ld_total

// Write : each member is typed and escaped for you - a path may have levels
lnv_json.of_set_string("customer", "Ada")
lnv_json.of_set_number("total", 690.50)
lnv_json.of_set_boolean("paid", true)
// lnv_json.of_text() -> {"customer":"Ada","total":690.5,"paid":true}

// Read : load a response, reach values by path
lnv_json.of_load('{"order":{"customer":"Ada","total":690.50}}')
IF lnv_json.of_is_valid() THEN
	ls_customer = lnv_json.of_get_string("order/customer")   // Ada
	ld_total    = lnv_json.of_get_number("order/total")     // 690.5
END IF

Um caminho são as chaves desde a raiz unidas por /; o índice de um array é a sua posição, contada a partir de 0: order/lines/0.

Construir um payload #

Método	Função
`of_add_string (string as_path, string as_value) → long`	Acrescenta uma CADEIA, com escape automático, ao ARRAY em `as_path`. O array tem de existir: abra-o primeiro com `of_set_raw` e um array vazio. Devolve `0`, `-4` se `as_path` faltar ou não for um array
`of_add_boolean (string as_path, boolean ab_value) → long`	Acrescenta um BOOLEANO (`true` ou `false`, nunca entre aspas) ao ARRAY em `as_path`. O array tem de existir: abra-o primeiro com `of_set_raw` e um array vazio. Devolve `0`, `-4` se `as_path` faltar ou não for um array
`of_add_number (string as_path, long al_value) → long`	Acrescenta um NÚMERO (três sobrecargas: `integer`, `long`, `double`) ao ARRAY em `as_path`. O array tem de existir: abra-o primeiro com `of_set_raw` e um array vazio. Devolve `0`, `-4` se `as_path` faltar ou não for um array
`of_add_raw (string as_path, string as_json) → long`	Acrescenta um valor JÁ em JSON (um objeto, um array) pelo qual responde ao ARRAY em `as_path`. O array tem de existir: abra-o primeiro com `of_set_raw` e um array vazio. Devolve `0`, `-4` se `as_path` faltar ou não for um array
`of_set_array (string as_path, string as_values[]) → long`	ESCREVE um ARRAY inteiro de cadeias em `as_path` a partir de um array PowerBuilder, cada elemento com escape. Um array vazio escreve um vazio. Mesma regra de caminho e mesmos códigos que `of_set_string`
`of_set_members (string as_fragment) → long`	Funde na RAIZ membros já formados noutro lado, unidos por vírgulas. Um fragmento vazio não escreve nada. Devolve `0`
`of_clear ( )` → `long`	Esvazia o documento para começar outro objeto com a mesma variável. Devolve `0`
`of_text ( )` → `string`	O documento tal como está (compacto): o que construiu (`of_add_string`, `of_add_number`...) ou carregou (`of_load`), após qualquer alteração — a saída única, pronta a enviar, guardar ou reescrever. `of_pretty` dá a forma indentada. `{}` se vazio; chamá-lo não esvazia nada

Ler um documento #

Método	Função
`of_load (string as_json)` → `long`	Carrega um texto JSON para leitura. Devolve `0` se bem formado, `-5` se o argumento estiver vazio, `-4` se não for JSON válido (o documento é então descartado). Analisa em PowerScript puro
`of_is_valid ( )` → `boolean`	Verdadeiro quando o último `of_load` foi bem-sucedido
`of_exists (string as_path)` → `boolean`	Verdadeiro quando existe um valor no caminho dado — distingue um valor presente mas vazio de um ausente
`of_type (string as_path)` → `string`	O tipo JSON no caminho: `object`, `array`, `string`, `number`, `boolean`, `null`; vazio se ausente
`of_get_string (string as_path)` → `string`	O valor no caminho, como texto: uma string volta descodificada, um número/booleano/null como texto, um objeto ou array como JSON em bruto (recarregável com `of_load`)
`of_get_number (string as_path)` → `double`	O número no caminho, como `double` — o ponto decimal é respeitado em qualquer máquina (2.5 é 2,5, não 2). `0` se ausente
`of_get_boolean (string as_path)` → `boolean`	O booleano no caminho: verdadeiro apenas para o literal JSON `true`
`of_count (string as_path)` → `long`	O número de membros do objeto, ou de elementos do array, no caminho. Devolve `-1` se o valor for escalar ou ausente (distingue um array vazio, `0`, de um em falta, `-1`)
`of_name (string as_path, long al_index)` → `string`	O nome do membro n.º `al_index` (a partir de 1) do objeto no caminho — para ler as chaves de um objeto de forma desconhecida. Com `of_count`, percorre o objeto
`of_pretty ( )` → `string`	O documento carregado, reindentado para leitura (várias linhas, tabulações) — um log, uma caixa de texto. Vazio se nada de válido estiver carregado

Modificar um documento #

O lado de escrita altera o documento carregado no lugar, depois of_text devolve o resultado (compacto) — o que se reescreve. Os setters substituem o valor no caminho, ou acrescentam a última chave quando falta a um objeto pai. Cada um devolve 0, -4 quando o pai falta ou é do tipo errado, -5 num caminho vazio.

Membro	Função
`of_set_string (string as_path, string as_value) → long` → `long`	ESCREVE uma cadeia em `as_path`, com escape automático. O caminho pode ter VÁRIOS níveis (`a/b/c`): os que faltam são criados como OBJETOS, e um documento VAZIO passa a sê-lo — escrever É construir. Um valor já presente é substituído, onde quer que esteja. Devolve `0`, `-4` se um nível do caminho for um escalar ou um array, `-5` com um caminho vazio
`of_set_number (string as_path, long al_value) → long` → `long`	ESCREVE um NÚMERO em `as_path`, o ponto decimal forçado. Três sobrecargas: `integer`, `long`, `double`. Mesma regra de caminho e mesmos códigos que `of_set_string`
`of_set_boolean (string as_path, boolean ab_value) → long` → `long`	ESCREVE um BOOLEANO em `as_path`: `true` ou `false`, nunca entre aspas. Mesma regra de caminho e mesmos códigos que `of_set_string`
`of_set_raw (string as_path, string as_json) → long` → `long`	ESCREVE em `as_path` um valor JÁ em JSON — um objeto aninhado, um array, `null` — tal como está: responde por ele. É também assim que se ABRE um array antes de `of_add_*`. Mesma regra de caminho e mesmos códigos que `of_set_string`
`of_remove (string as_path)` → `long`	Remove o valor no caminho — um membro de objeto (a sua chave e uma vírgula vão com ele) ou um elemento de array; o resultado permanece válido

n_pbt_json  lnv_json

// Load, edit in place, then read back the ONE document with of_text
lnv_json.of_load('{"name":"Ada","active":false}')
lnv_json.of_set_string("name", "Grace")   // replace
lnv_json.of_set_boolean("active", true)
lnv_json.of_set_number("count", 3)        // added : the key was absent
// lnv_json.of_text() -> {"name":"Grace","active":true,"count":3}

Âmbito. O JSON analisa-se em PowerScript puro, sem página nem motor: n_pbt_json continua autoinstantiate e funciona em todo o lado, PowerBuilder 10 incluído. Para XML, veja xml (que assenta no motor); para mostrar um JSON como árvore recolhível, veja jsontree.