json — `n_pbt_json` #

← Referencia de componentes · Índice de la guía

Construir un JSON tipo por tipo — texto, número, booleano, arreglo, objeto anidado — con el escapado hecho por usted, y luego leer uno a lo largo de una ruta: of_load, of_get_string, of_type, of_count. Un solo objeto construye sus peticiones y lee sus respuestas. Todo en PowerScript puro: sin página, sin motor, PowerBuilder 10 incluido.

▶ Verlo en vivo — Aplicación de demostración, mosaico JSON: los resultados, el código que los produce y esta página, lado a lado.

En resumen #

n_pbt_json es autoinstantiate: se declara como variable local, sin create ni destroy. Es el mismo objeto que, internamente, construye las cargas útiles enviadas al motor — ahora ofrecido a su código, del lado de construcción y de lectura.

Inicio rápido #

Construir una carga útil y luego releer una respuesta — todo cabe en una variable local:

// Local variables
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(/*path*/ "customer", /*value*/ "Ada")
lnv_json.of_set_number(/*path*/ "total", /*value*/ 690.50)
lnv_json.of_set_boolean(/*path*/ "paid", /*value*/ true)

// lnv_json.of_text() -> {"customer":"Ada","total":690.5,"paid":true}

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

Una ruta son las claves desde la raíz unidas por /; el índice de un arreglo es su posición, contada desde 1, como toda posición de la biblioteca: order/lines/1 es la primera línea, order/lines/0 no designa nada. Un segmento vacío (a//b, /a) o un índice 0 sobre un arreglo no designa nada — una escritura lo rechaza con -5 — y una clave que contiene / no es direccionable. Si un objeto escribe la misma clave dos veces, es su PRIMERA aparición la que se lee y se escribe — un navegador conserva la última.

Construir una carga útil #

Método	Función
`of_add_string (string as_path, string as_value)` → `long`	Añade una CADENA, con escape automático, al ARRAY en `as_path`. El array debe existir: ábralo antes con `of_set_raw` y un array vacío. Devuelve `0`, `-4` si `as_path` falta o no es un array, `-5` si un segmento de `as_path` está vacío o es un índice 0 en un array; una cadena nula se escribe vacía (para un `null` JSON: `of_add_raw(as_path, "null")`)
`of_add_boolean (string as_path, boolean ab_value)` → `long`	Añade un BOOLEANO (`true` o `false`, nunca entre comillas) al ARRAY en `as_path`. El array debe existir: ábralo antes con `of_set_raw` y un array vacío. Devuelve `0`, `-4` si `as_path` falta o no es un array, `-5` si un segmento de `as_path` está vacío o es un índice 0 en un array; un valor nulo escribe `null`
`of_add_number (string as_path, long al_value)` → `long`	Añade un NÚMERO (cinco sobrecargas: `integer`, `long`, `longlong`, `decimal`, `double` — un `decimal` y un `longlong` conservan TODAS sus cifras (los céntimos de un importe, la última cifra de un identificador por encima de 2^53), y un literal como `690.50` es un `decimal`, escrito `690.5`) al ARRAY en `as_path`. El array debe existir: ábralo antes con `of_set_raw` y un array vacío. Devuelve `0`, `-4` si `as_path` falta o no es un array, `-5` si un segmento de `as_path` está vacío o es un índice 0 en un array; un valor nulo escribe `null`
`of_add_raw (string as_path, string as_json)` → `long`	Añade un valor YA en JSON (un objeto, un array) del que usted responde al ARRAY en `as_path`. El array debe existir: ábralo antes con `of_set_raw` y un array vacío. Devuelve `0`, `-4` si `as_path` falta o no es un array, `-5` si un segmento de `as_path` está vacío o es un índice 0 en un array; un valor nulo o vacío escribe `null`. La ruta vacía es la RAÍZ: `of_load("[]")` y luego `of_add_raw("", …)` construye un documento que es un array (el cuerpo de una llamada de API por lotes). Añadir muchos elementos seguidos al mismo array sigue siendo rápido
`of_set_array (string as_path, string as_values[])` → `long`	ESCRIBE un ARRAY entero de cadenas en `as_path` desde un array PowerBuilder, cada elemento con escape. Un array vacío escribe uno vacío, un elemento nulo una cadena vacía. Misma regla de ruta y mismos códigos que `of_set_string`
`of_set_members (string as_fragment)` → `long`	Fusiona en la RAÍZ miembros ya formados en otro sitio, unidos por comas. Un fragmento vacío no escribe nada. Devuelve `0`, `-4` si la raíz del documento no es un objeto
`of_clear ( )` → `long`	Vacía el documento para empezar otro objeto con la misma variable. Devuelve `0`
`of_text ( )` → `string`	El documento tal cual (compacto): lo que construyó (`of_add_string`, `of_add_number`...) o cargó (`of_load`), tras cualquier cambio — la salida única, lista para enviar, almacenar o reescribir. `of_pretty` da la forma indentada. `{}` si está vacío; llamarlo no vacía nada

Leer un documento #

Método	Función
`of_load (string as_json)` → `long`	Carga un texto JSON para su lectura. Devuelve `0` si está bien formado, `-5` si el argumento está vacío o en blanco (espacios, tabulaciones, saltos de línea), `-4` si no es JSON válido o anida más de 512 niveles (el documento se descarta entonces). Analiza en PowerScript puro. Un BOM (U+FEFF) al principio, el de un archivo guardado en UTF-8 con BOM, se ignora
`of_is_valid ( )` → `boolean`	Verdadero cuando el objeto contiene un documento: el último `of_load` tuvo éxito, o se ha escrito algo desde entonces. Un valor pasado a `of_set_raw` / `of_add_raw` no se vuelve a comprobar
`of_exists (string as_path)` → `boolean`	Verdadero cuando existe un valor en la ruta dada — distingue un valor presente pero vacío de uno ausente
`of_type (string as_path)` → `string`	El tipo JSON en la ruta: `object`, `array`, `string`, `number`, `boolean`, `null`; vacío si ausente
`of_get_string (string as_path)` → `string`	El valor en la ruta, como texto: una cadena vuelve decodificada, un número/booleano/null como texto, un objeto o arreglo como JSON en bruto (recargable con `of_load`); una clave escrita dos veces se lee en su PRIMERA aparición
`of_get_number (string as_path)` → `double`	El número en la ruta, como `double` — el punto decimal se respeta en cualquier máquina (2.5 es 2,5, no 2). `0` si ausente; el exponente se resuelve (`1e-7`, `2.5E+3`) y se conservan 17 cifras significativas, ceros iniciales del exponente incluidos. Para un importe o un identificador que debe conservar todas sus cifras: `of_get_decimal` o `of_get_longlong`
`of_get_decimal (string as_path)` → `decimal`	El número en la ruta, como `decimal`, reconstruido a partir del TEXTO del número y nunca mediante un `double`: `12345678901234.56` vuelve con sus céntimos, `2.5E-3` vale `0.0025`. 28 cifras significativas como máximo. `0` si ausente, si el valor no es un número, o más allá de lo que cabe en un `decimal`
`of_get_longlong (string as_path)` → `longlong`	El número en la ruta, como entero de 64 bits, reconstruido a partir de su texto y nunca mediante un `double`: un identificador de base de datos como `9007199254740993` vuelve entero. Los decimales se truncan (`2.9` da `2`). `0` si ausente, si el valor no es un número, o fuera del rango de un `longlong`
`of_get_boolean (string as_path)` → `boolean`	El booleano en la ruta: verdadero solo para el literal JSON `true`
`of_count (string as_path)` → `long`	El número de miembros del objeto, o de elementos del arreglo, en la ruta. Devuelve `-1` si el valor es escalar o ausente (distingue un arreglo vacío, `0`, de uno faltante, `-1`). Con `of_name` se recorre un objeto; un arreglo se recorre por su índice en la ruta (`rows/1`, `rows/2`…)
`of_name (string as_path, long al_index)` → `string`	El nombre del miembro n.º `al_index` (desde 1) del objeto en la ruta — para leer las claves de un objeto de forma desconocida. Con `of_count`, recorre el objeto
`of_get_array (string as_path, ref string as_values[])` → `long`	Todos los elementos del arreglo en la ruta, en orden, en `as_values` (vaciado antes) — cada uno como lo lee `of_get_string`: una cadena vuelve decodificada, un número o un booleano como texto, `null` como `""`, un objeto o un arreglo como JSON en bruto (para cargar con `of_load` en otro `n_pbt_json`). `""` es la raíz. Devuelve el número de elementos (`0` para un arreglo vacío), `-4` cuando no hay un arreglo en la ruta (nada, un objeto, un escalar), `-5` con un segmento vacío (`a//b`)
`of_pretty ( )` → `string`	El documento — cargado o construido — re-indentado para la lectura (varias líneas, tabulaciones) — un log, un cuadro de texto. Vacío si no hay ninguno
`of_pretty (long al_indent)` → `string`	El documento — cargado o construido — re-indentado con `al_indent` espacios por nivel (2 y 4 son los anchos habituales). `0` lo escribe compacto, en una línea y sin espacios: el texto más pequeño para almacenar o enviar. Vacío si no hay documento, o si `al_indent` es negativo, mayor que 16 o null. `of_pretty()` sin argumento conserva las tabulaciones

// Local variables
n_pbt_json  lnv_json
string      ls_tags[]
string      ls_compact
long        ll_count

// Read every element of an array at once, then store the document on one line
lnv_json.of_load(/*json*/ '{"customer":{"name":"Ada","tags":["vip","b2b"]}}')
ll_count = lnv_json.of_get_array(/*path*/ "customer/tags", /*values*/ ls_tags)   // 2 : vip, b2b

// The document on one line, without a space : the smallest text to store
ls_compact = lnv_json.of_pretty(/*indent*/ 0)

Modificar un documento #

El lado de escritura cambia el documento cargado en el sitio, luego of_text devuelve el resultado (compacto) — lo que se reescribe. Los setters reemplazan el valor en la ruta, o agregan la última clave cuando falta en un objeto padre. Cada uno devuelve 0, -4 cuando el padre falta o es del tipo equivocado, -5 con una ruta vacía o un índice 0 sobre un array. Un array encontrado en el camino se atraviesa con un índice que EXISTE (items/1/qty añade qty al primer elemento); solo se crea una clave de objeto. Un valor null (número, booleano, JSON en bruto vacío) se escribe null.

Miembro	Función
`of_set_string (string as_path, string as_value)` → `long`	ESCRIBE una cadena en `as_path`, con escape automático. La ruta puede tener VARIOS niveles (`a/b/c`): los que faltan se crean como OBJETOS, y un documento VACÍO pasa a serlo — escribir ES construir. Un valor ya presente se reemplaza, esté donde esté. Devuelve `0`, `-4` si un nivel del camino es un escalar, o un array sin ese índice (un array se atraviesa con un índice existente: `items/1/qty`), `-5` con una ruta vacía, un segmento vacío o un índice 0 sobre un array. Una cadena nula se escribe vacía; para un `null` JSON: `of_set_raw(as_path, "null")`
`of_set_number (string as_path, long al_value)` → `long`	ESCRIBE un NÚMERO en `as_path`, el punto decimal forzado. Cinco sobrecargas: `integer`, `long`, `longlong`, `decimal`, `double` — un `decimal` y un `longlong` conservan TODAS sus cifras (los céntimos de un importe, la última cifra de un identificador por encima de 2^53), y un literal como `690.50` es un `decimal`, escrito `690.5`. Misma regla de ruta y mismos códigos que `of_set_string`; un valor nulo escribe `null`
`of_set_boolean (string as_path, boolean ab_value)` → `long`	ESCRIBE un BOOLEANO en `as_path`: `true` o `false`, nunca entre comillas. Misma regla de ruta y mismos códigos que `of_set_string`; un valor nulo escribe `null`
`of_set_raw (string as_path, string as_json)` → `long`	ESCRIBE en `as_path` un valor YA en JSON — un objeto anidado, un array, `null` — tal cual: usted responde por él. Así se ABRE también un array antes de `of_add_*`. Misma regla de ruta y mismos códigos que `of_set_string`; un valor nulo o vacío escribe `null`
`of_remove (string as_path)` → `long`	Quita el valor en la ruta — un miembro de objeto (su clave y una coma se van con él) o un elemento de arreglo; el resultado sigue siendo válido. Devuelve `0`, `-4` si no hay nada, `-5` con una ruta vacía, un segmento vacío o un índice 0 sobre un array

// Local variables
n_pbt_json  lnv_json

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

// lnv_json.of_text() -> {"name":"Grace","active":true,"count":3}

Alcance. El JSON se analiza en PowerScript puro, sin página ni motor: n_pbt_json sigue siendo autoinstantiate y funciona en todas partes, PowerBuilder 10 incluido. Para XML, vea xml (que se apoya en el motor); para mostrar un JSON como árbol plegable, vea jsontree.