175 lines
5.2 KiB
Markdown
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`)*.
|