Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-json

Source of release 0.6.1

0.6.1 / README.md

# luce-json

Structured JSON encoding and decoding for [Luce](https://github.com/dymokomi/luce) and
[luce-base](https://github.com/dymokomi/luce-base). A standalone package: it depends only on
the embedded standard library (`memory`, `interop`, `strings`, `utf8`, `math`).

## Use it

Declare the dependency relative to your own manifest:

```toml
[package]
name = "demo"

[dependencies]
luce_json = "../luce-json"
```

```luce
from luce_json import json
import memory

pub func main(arguments: str[]) -> i32!:
    with memory.heap:
        # Encode: build a value, then read its UTF-8 text.
        let object = try new json.Value()
        defer free(object)
        defer object.close()
        try object.set_integer("count", 42)
        try object.set_text("name", "luce")
        print(object.encode())                       # {"count":42,"name":"luce"}

        # Decode: parse text into a queryable document.
        let document = try json.decode(object.encode())
        defer document.release()
        let root = (try document.get()).root()
        let count = (root.member("count") else trap("count")).integer() else -1
        print(f"{count}")                            # 42
    return 0
```

## Encoding

`json.Value()` creates an object; `Value.array()`, `text`, `integer`, `number`, `boolean` and
`null` construct the other values. Containers take `set`/`append`; objects also have
`set_text`, `set_integer`, `set_number`, `set_boolean`. Containers snapshot inserted values,
so a later change to a child never mutates its parent or forms a cycle. `encode()` borrows the
value's UTF-8 text until the next mutation or close. All growth is bounded and transactional.

## Decoding

`json.decode(text, maximum_bytes = 1 MiB)` parses one complete JSON value into an owned
`Document`. `document.root()` returns a `View` cursor:

| Method | Answers |
| --- | --- |
| `kind()` | `Kind.object`, `.array`, `.string`, `.number`, `.boolean` or `.null` |
| `length()` | member/element count of an object or array |
| `member(name)` | the named object member, or `none` |
| `at(index)` | the array element at `index`, or `none` |
| `text()` | a string's decoded UTF-8 (escapes and surrogate pairs resolved), or `none` |
| `integer()` / `number()` | a number as `i64` / `f64`, or `none` |
| `boolean()` | a boolean, or `none` |
| `is_null()` | whether the value is JSON `null` |

Views are borrowed and valid until the document closes. Malformed input fails with
`json.invalid`; input larger than the limit fails with `json.limit_exceeded`.

## Test

`./test.sh` runs the unit tests through both backends and a consumer round-trip. Set
`LUCE_BASE` to your compiler; it defaults to a sibling `../luce-base` checkout.

## License

Dual-licensed under Apache-2.0 or MIT, at your option.