(sigil yaml)

YAML parsing and serialization for Sigil applications.

Type Mapping

Quick Start

(import (sigil yaml))

;; Decode YAML strings
(yaml-decode "name: Alice\nage: 30")
; => #{ name: "Alice" age: 30 }

(yaml-decode "- apple\n- banana\n- cherry")
; => ("apple" "banana" "cherry")

;; Encode Scheme values to YAML
(yaml-encode #{ name: "Alice" age: 30 })
; => "name: Alice\nage: 30\n"

(yaml-encode '(1 2 3))
; => "- 1\n- 2\n- 3\n"

Reading and Writing

String Convenience Functions

;; Decode a YAML string
(yaml-decode "key: value")  ; => #{ key: "value" }

;; Encode to YAML string
(yaml-encode #{ key: "value" })  ; => "key: value\n"

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

Port-Based I/O

;; Write YAML to a file
(call-with-output-file "config.yaml"
  (lambda (port)
    (yaml-write #{ name: "Alice" age: 30 } port)))

;; Read YAML from a file
(call-with-input-file "config.yaml" yaml-read)
; => #{ name: "Alice" age: 30 }

Scalars

YAML scalars are automatically resolved to Scheme types:

(yaml-decode "42")      ; => 42 (integer)
(yaml-decode "3.14")    ; => 3.14 (float)
(yaml-decode "0xFF")    ; => 255 (hex integer)
(yaml-decode "0o10")    ; => 8 (octal integer)
(yaml-decode "true")    ; => #t
(yaml-decode "false")   ; => #f
(yaml-decode "null")    ; => 'null
(yaml-decode "~")       ; => 'null
(yaml-decode ".inf")    ; => +infinity
(yaml-decode ".nan")    ; => NaN
(yaml-decode "hello")   ; => "hello" (string)

Quoted Strings

;; Double-quoted (supports escape sequences)
(yaml-decode "\"line1\\nline2\"")  ; => "line1\nline2"

;; Single-quoted (no escapes except '')
(yaml-decode "'it''s here'")  ; => "it's here"

;; Quoted strings preserve literal values
(yaml-decode "\"true\"")   ; => "true" (string, not boolean)
(yaml-decode "'null'")     ; => "null" (string, not null)

Collections

Block Mappings

(yaml-decode "name: Alice\nage: 30")
; => #{ name: "Alice" age: 30 }

;; Nested
(yaml-decode "server:\n  host: localhost\n  port: 8080")
; => #{ server: #{ host: "localhost" port: 8080 } }

Block Sequences

(yaml-decode "- apple\n- banana\n- cherry")
; => ("apple" "banana" "cherry")

;; Sequence of mappings
(yaml-decode "- name: Alice\n  age: 30\n- name: Bob\n  age: 25")
; => (#{ name: "Alice" age: 30 } #{ name: "Bob" age: 25 })

Flow Collections

;; Inline sequence
(yaml-decode "[1, 2, 3]")
; => (1 2 3)

;; Inline mapping
(yaml-decode "{name: Alice, age: 30}")
; => #{ name: "Alice" age: 30 }

;; Mixed with block style
(yaml-decode "items: [1, 2, 3]\npoint: {x: 10, y: 20}")
; => #{ items: (1 2 3) point: #{ x: 10 y: 20 } }

Block Scalars

Literal (|) - preserves newlines

(yaml-decode "text: |\n  line 1\n  line 2\n  line 3")
; text => "line 1\nline 2\nline 3\n"

Folded (>) - joins lines with spaces

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

Chomping Indicators

;; Strip (-) removes all trailing newlines
(yaml-decode "text: |-\n  hello")  ; text => "hello"

;; Keep (+) preserves trailing newlines
(yaml-decode "text: |+\n  hello\n\nnext: val")  ; text => "hello\n\n"

;; Clip (default) keeps one trailing newline
(yaml-decode "text: |\n  hello")  ; text => "hello\n"

Multi-Document

;; Read all documents
(yaml-decode-all "---\na: 1\n---\nb: 2")
; => (#{ a: 1 } #{ b: 2 })

;; yaml-read / yaml-decode only reads the first document
(yaml-decode "---\na: 1\n---\nb: 2")
; => #{ a: 1 }

Anchors and Aliases

(yaml-decode "defaults: &def\n  color: red\n  size: large\nref: *def")
; => #{ defaults: #{ color: "red" size: "large" }
;       ref: #{ color: "red" size: "large" } }

Null Handling

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

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

API Reference