README.md — sigil-json

1# sigil-json

3JSON parsing and generation for [Sigil](https://codeberg.org/sigil/sigil).

5Bidirectional conversion between JSON and native Scheme types (dicts,

6arrays, strings, numbers, booleans) with port-based I/O for reading and

7writing JSON streams.

9This package was extracted from the sigil monorepo — the in-tree history

10under `packages/sigil-json/` is preserved here as `master`.

12## Usage

14```scheme

15(import (sigil json))

17;; Encode

18(json-encode #{ name: "Alice" age: 30 })

19; => "{\"name\":\"Alice\",\"age\":30}"

21;; Decode

22(json-decode "{\"name\":\"Alice\",\"age\":30}")

23; => #{ name: "Alice" age: 30 }

25;; Path lookup

26(json-get-in (json-decode "{\"a\":{\"b\":42}}") '(a b))

27; => 42

28```

30## Type Mapping

32| JSON | Scheme |

33|--------|----------------------------|

34| object | dict: `#{ name: "Alice" }` |

35| array | array: `#[1 2 3]` |

36| string | string: `"hello"` |

37| number | number: `42`, `3.14` |

38| true | `#t` |

39| false | `#f` |

40| null | `'null` symbol |

42JSON `null` decodes as the symbol `'null` (not `#f`). When a field may be

43JSON null, normalize it explicitly — see `docs/json.md` for the pattern.

45## API

47### `(sigil json)`

49| Procedure | Purpose |

50|-----------|---------|

51| `json-encode` | Scheme value → JSON string |

52| `json-decode` | JSON string → Scheme value |

53| `json-read` / `json-write` | Port-based streaming I/O |

54| `json-get-in` | Path lookup into a decoded value |

56See `docs/json.md` for full details.

58## Dependencies

60- `sigil-stdlib`

62Consumed here as a `from-git` ref pinned to `^0.13.1` against the sigil

63monorepo.

65## Build

67```sh

68sigil deps install

69sigil build

70```

72## Testing

74```sh

75sigil test

76```

78## License

80BSD-3-Clause.