docs/yaml.md — sigil-yaml

1# (sigil yaml)

3YAML parsing and serialization for Sigil applications.

5## Type Mapping

7| YAML | Scheme |

8|-----------|------------------------------------|

9| mapping | dict: `#{ name: "Alice" }` |

10| sequence | list: `("apple" "banana")` |

11| string | string: `"hello"` |

12| integer | integer: `42` |

13| float | float: `3.14` |

14| true/false| `#t` / `#f` |

15| null | `'null` symbol |

17## Quick Start

19```scheme

20(import (sigil yaml))

22;; Decode YAML strings

23(yaml-decode "name: Alice\nage: 30")

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

26(yaml-decode "- apple\n- banana\n- cherry")

27; => ("apple" "banana" "cherry")

29;; Encode Scheme values to YAML

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

31; => "name: Alice\nage: 30\n"

33(yaml-encode '(1 2 3))

34; => "- 1\n- 2\n- 3\n"

35```

37## Reading and Writing

39### String Convenience Functions

41```scheme

42;; Decode a YAML string

43(yaml-decode "key: value") ; => #{ key: "value" }

45;; Encode to YAML string

46(yaml-encode #{ key: "value" }) ; => "key: value\n"

48;; Flow (inline) style

49(yaml-encode #{ a: 1 b: 2 } flow: #t) ; => "{a: 1, b: 2}"

50```

52### Port-Based I/O

54```scheme

55;; Write YAML to a file

56(call-with-output-file "config.yaml"

57 (lambda (port)

58 (yaml-write #{ name: "Alice" age: 30 } port)))

60;; Read YAML from a file

61(call-with-input-file "config.yaml" yaml-read)

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

63```

65## Scalars

67YAML scalars are automatically resolved to Scheme types:

69```scheme

70(yaml-decode "42") ; => 42 (integer)

71(yaml-decode "3.14") ; => 3.14 (float)

72(yaml-decode "0xFF") ; => 255 (hex integer)

73(yaml-decode "0o10") ; => 8 (octal integer)

74(yaml-decode "true") ; => #t

75(yaml-decode "false") ; => #f

76(yaml-decode "null") ; => 'null

77(yaml-decode "~") ; => 'null

78(yaml-decode ".inf") ; => +infinity

79(yaml-decode ".nan") ; => NaN

80(yaml-decode "hello") ; => "hello" (string)

81```

83### Quoted Strings

85```scheme

86;; Double-quoted (supports escape sequences)

87(yaml-decode "\"line1\\nline2\"") ; => "line1\nline2"

89;; Single-quoted (no escapes except '')

90(yaml-decode "'it''s here'") ; => "it's here"

92;; Quoted strings preserve literal values

93(yaml-decode "\"true\"") ; => "true" (string, not boolean)

94(yaml-decode "'null'") ; => "null" (string, not null)

95```

97## Collections

99### Block Mappings

100

101```scheme

102(yaml-decode "name: Alice\nage: 30")

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

104

105;; Nested

106(yaml-decode "server:\n host: localhost\n port: 8080")

107; => #{ server: #{ host: "localhost" port: 8080 } }

108```

109

110### Block Sequences

111

112```scheme

113(yaml-decode "- apple\n- banana\n- cherry")

114; => ("apple" "banana" "cherry")

115

116;; Sequence of mappings

117(yaml-decode "- name: Alice\n age: 30\n- name: Bob\n age: 25")

118; => (#{ name: "Alice" age: 30 } #{ name: "Bob" age: 25 })

119```

120

121### Flow Collections

122

123```scheme

124;; Inline sequence

125(yaml-decode "[1, 2, 3]")

126; => (1 2 3)

127

128;; Inline mapping

129(yaml-decode "{name: Alice, age: 30}")

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

131

132;; Mixed with block style

133(yaml-decode "items: [1, 2, 3]\npoint: {x: 10, y: 20}")

134; => #{ items: (1 2 3) point: #{ x: 10 y: 20 } }

135```

136

137## Block Scalars

138

139### Literal (`|`) - preserves newlines

140

141```scheme

142(yaml-decode "text: |\n line 1\n line 2\n line 3")

143; text => "line 1\nline 2\nline 3\n"

144```

145

146### Folded (`>`) - joins lines with spaces

147

148```scheme

149(yaml-decode "text: >\n long line\n continues here")

150; text => "long line continues here\n"

151```

152

153### Chomping Indicators

154

155```scheme

156;; Strip (-) removes all trailing newlines

157(yaml-decode "text: |-\n hello") ; text => "hello"

158

159;; Keep (+) preserves trailing newlines

160(yaml-decode "text: |+\n hello\n\nnext: val") ; text => "hello\n\n"

161

162;; Clip (default) keeps one trailing newline

163(yaml-decode "text: |\n hello") ; text => "hello\n"

164```

165

166## Multi-Document

167

168```scheme

169;; Read all documents

170(yaml-decode-all "---\na: 1\n---\nb: 2")

171; => (#{ a: 1 } #{ b: 2 })

172

173;; yaml-read / yaml-decode only reads the first document

174(yaml-decode "---\na: 1\n---\nb: 2")

175; => #{ a: 1 }

176```

177

178## Anchors and Aliases

179

180```scheme

181(yaml-decode "defaults: &def\n color: red\n size: large\nref: *def")

182; => #{ defaults: #{ color: "red" size: "large" }

183; ref: #{ color: "red" size: "large" } }

184```

185

186## Null Handling

187

188Use `yaml-null?` to distinguish null from `#f`:

189

190```scheme

191(yaml-null? (yaml-decode "null")) ; => #t

192(yaml-null? (yaml-decode "~")) ; => #t

193(yaml-null? (yaml-decode "false")) ; => #f

194(yaml-null? #f) ; => #f

195```

196

197## API Reference

198

199| Procedure | Signature | Description |

200|-----------|-----------|-------------|

201| `yaml-read` | `(port) -> any` | Read one YAML document from a port |

202| `yaml-write` | `(value port [indent: N] [flow: bool]) -> void` | Write YAML to a port |

203| `yaml-decode` | `(string) -> any` | Decode a YAML string |

204| `yaml-encode` | `(value [indent: N] [flow: bool]) -> string` | Encode a value as YAML |

205| `yaml-read-all` | `(port) -> list` | Read all documents from a port |

206| `yaml-decode-all` | `(string) -> list` | Decode all documents from a string |

207| `yaml-null?` | `(value) -> boolean` | Check if value is YAML null |