docs/json.md — sigil-json

1# JSON

3> Bidirectional conversion between JSON and Scheme values.

5```scheme

6(import (sigil json))

7```

9## Type Mapping

11| JSON | Scheme |

12|--------|----------------------------|

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

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

15| string | string: `"hello"` |

16| number | number: `42`, `3.14` |

17| true | `#t` |

18| false | `#f` |

19| null | `'null` symbol |

21## json-encode

23Convert a Scheme value to a JSON string.

25```scheme

26;; Objects (dicts or alists)

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

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

30(json-encode '((name . "Alice") (age . 30)))

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

33;; Arrays

34(json-encode #[1 2 3])

35; => "[1,2,3]"

37;; Primitives

38(json-encode "hello") ; => "\"hello\""

39(json-encode 42) ; => "42"

40(json-encode #t) ; => "true"

41(json-encode 'null) ; => "null"

43;; Pretty-print with indentation

44(json-encode #{ a: 1 b: #[2 3] } indent: #t)

45; => "{\n \"a\": 1,\n \"b\": [\n 2,\n 3\n ]\n}"

47(json-encode #{ x: 1 } indent: 4) ; 4-space indent

48```

50## json-decode

52Parse a JSON string into Scheme values.

54```scheme

55;; Objects become dicts

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

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

59;; Arrays become arrays

60(json-decode "[1, 2, 3]")

61; => #[1 2 3]

63;; Nested structures

64(json-decode "{\"user\": {\"name\": \"Bob\"}, \"scores\": [10, 20]}")

65; => #{ user: #{ name: "Bob" } scores: #[10 20] }

67;; Primitives

68(json-decode "true") ; => #t

69(json-decode "null") ; => null (symbol)

70(json-decode "3.14") ; => 3.14

72;; Convert to alist if needed

73(dict->alist (json-decode "{\"x\": 1}"))

74; => ((x . 1))

75```

77## json-read / json-write

79Port-based I/O for streaming to files or sockets.

81```scheme

82;; Write to file

83(call-with-output-file "data.json"

84 (lambda (port)

85 (json-write #{ name: "Alice" } port)))

87;; Read from file

88(call-with-input-file "data.json" json-read)

90;; Write to stdout

91(json-write #{ x: 1 y: 2 } (current-output-port))

93;; Pretty-print to port

94(json-write data port indent: #t)

95```

97## json-null?

99Check if a value is JSON null (the symbol `'null`).

100

101```scheme

102(json-null? 'null) ; => #t

103(json-null? #f) ; => #f (false is not null)

104(json-null? '()) ; => #f

105

106(json-null? (json-decode "null")) ; => #t

107(json-null? (json-decode "false")) ; => #f

108```

109

110## Common Patterns

111

112### Parse API Response

113

114```scheme

115(import (sigil json)

116 (sigil http))

117

118(let* ((response (http-get "https://api.example.com/users"))

119 (data (json-decode (http-response-body response))))

120 (dict-ref data users:))

121```

122

123### Build API Request

124

125```scheme

126(let ((body (json-encode #{ name: "Alice" email: "[email protected]" })))

127 (http-post "https://api.example.com/users"

128 body

129 '(("Content-Type" . "application/json"))))

130```

131

132### Read Config File

133

134```scheme

135(define (read-config path)

136 (call-with-input-file path json-read))

137

138(let ((config (read-config "config.json")))

139 (dict-ref config database:))

140```