Files
marqdo/lib/json.mq.md

175 lines
5.2 KiB
Markdown

---
markup: occlusion
title: lib/json
description: JSON parse/stringify (shared EN/ZH import). Not a dict builder — use lib/table.
---
Parse and stringify JSON. For maps/lists prefer GFM tables and lib/table put; do not chain json.set / json.append in new code.
Parse and serialize JSON at the data boundary.
Behavior and limits: Use table for collection operations. JSON boundary rejects unsafe integers, duplicate keys and nonfinite numbers; do not turn opaque handles into guessed records.
This single source file is the usage and development manual. Import it directly, or use marqdo call with a function heading below. Parameter tables give types and defaults; required parameters must be supplied. Return tables are progressive contracts; prose describes failure and limits.
Implementation: [src/host/json.rs](../src/host/json.rs)
For development, keep EN/ZH behavior aligned and compose public libraries first. Add host primitives only at OS or algorithm boundaries and declare their effects. Run marqdo check --narrative-ratio on this file and the real workflows in tests/stdlib_tasks.rs after edits.
## parse
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| text | text | required | Text supplied by the caller |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Parse JSON text into a Marqdo value |
Use `text` as the inputs for this operation.
Effects: pure.
Parse JSON text into a Marqdo value.
Caller: [json.parse] text="{}"
Return *[Parse JSON text into a Marqdo value](> host_json_parse text=`text`)*.
## stringify
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | required | Value to transform or store, without mutating the input |
| indent | any | None | JSON indentation setting; None uses compact output |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | text | Serialize value to JSON text; optional indent |
Use `value`, `indent`=None as the inputs for this operation.
Effects: pure.
Serialize value to JSON text; optional indent.
Return *[Serialize value to JSON text; optional indent](> host_json_stringify value=`value` indent=`indent`)*.
## get
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | required | Value to transform or store, without mutating the input |
| key | text | required | Field name or key required by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Shallow get from JSON object value at key |
Use `value`, `key` as the inputs for this operation.
Effects: pure.
Shallow get from JSON object value at key. Prefer link-index get or table.get in new code.
Return *[Shallow get from JSON object value at key](> host_json_get value=`value` key=`key`)*.
## keys
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | Keys of JSON object value |
Use `value` as the inputs for this operation.
Effects: pure.
Keys of JSON object value.
Return *[Keys of JSON object value](> host_json_keys value=`value`)*.
## quote
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| text | text | required | Text supplied by the caller |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | text | JSON-quote string text (for building request bodies) |
Use `text` as the inputs for this operation.
Effects: pure.
JSON-quote string text (for building request bodies).
Return *[JSON-quote string text (for building request bodies)](> host_json_quote text=`text`)*.
## set
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| map | any | required | Input string-keyed map |
| key | text | required | Field name or key required by this operation |
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Compatibility shallow set |
Use `map`, `key`, `value` as the inputs for this operation.
Effects: pure.
Compatibility shallow set. Prefer table.put / table.set.
Return *[Compatibility shallow set](> host_map_set map=`map` key=`key` value=`value`)*.
## append
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | required | Input list; updates return a new list |
| item | any | required | Element to insert, replace or compare |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | Compatibility append |
Use `list`, `item` as the inputs for this operation.
Effects: pure.
Compatibility append. Prefer table.append.
Return *[Compatibility append](> host_list_append list=`list` item=`item`)*.
## try_parse
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| text | text | required | Text to read, transform or emit as described by this operation |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | map | Return {ok,value,error}; parse failures are recoverable data |
Use `text` as the inputs for this operation.
Effects: pure.
Call this function directly:
```sh
marqdo call lib/json.mq.md try_parse 'text="{"name":"Marqdo","n":2}"' --effects none --json
```
Return {ok,value,error}; parse failures are recoverable data.
Return *[Return {ok,value,error}; parse failures are recoverable data](> host_try_json_parse text=`text`)*.