YAML

8.12

YAML🔗ℹ

Erik Silkensen <eriksilkensen@gmail.com>

package: yaml

This module provides utilities for parsing and emitting data in the YAML data serialization format. The implementation is hosted at GitHub and is based on PyYAML. See the YAML web site for more information about YAML.

1 YAML Expressions🔗ℹ

procedure
(yaml? v) → boolean?
v : any/c

Returns #t if v is a YAML expression, #f otherwise.

This module defines a subset of Racket values that can be represented as or constructed from YAML, and this predicate checks for such values.

The following table shows how the standard YAML tags, in addition to a number of Racket-specific tags, correspond to values in Racket.

YAML tag		Racket type
!!map		(hash/c yaml? yaml?)
!!omap, !!pairs		(listof (cons/c yaml? yaml?))
!!set		(set/c yaml?)
!!seq		(listof yaml?)
!!binary		bytes?
!!bool		boolean?
!!float		inexact-real?
!!int		exact-integer?
!!null		yaml-null?
!!str		string?
!!timestamp		date?
!!racket/pair		(cons/c yaml? yaml?)
!!racket/vector		(vector/c yaml?)
!!racket/symbol		symbol?

This module can be extended with support for application-specific tags using custom representers and constructors, and this predicate checks for those values as well.

parameter
(yaml-null) → any/c
(yaml-null null) → void?
null : any/c

A parameter that determines the value that corresponds to a YAML “null” (or empty scalar) value. It is 'null by default.

procedure
(yaml-null? v) → boolean?
v : any/c

Returns #t if v is equal to (yaml-null), #f otherwise.

Examples:

> (yaml-null? 'null)
#t
> (yaml-null? '())
#f
> (parameterize ([yaml-null '()])
(yaml-null? '()))
#t

2 Reading YAML🔗ℹ

procedure
(read-yaml [ in
#:allow-undefined? allow-undefined?]) → yaml?
in : input-port? = (current-input-port)
allow-undefined? : boolean? = #f

Parses a single document from in and returns a corresponding YAML expression. If the input contains more than one document, an exn:fail:user exception is raised.

The #:allow-undefined? keyword argument controls whether an undefined tag should raise an exception (the default behavior), or be interpreted as either a scalar, sequence, or mapping value.

procedure
(read-yaml* [in]) → (listof yaml?)
in : input-port? = (current-input-port)

Like read-yaml, but parses all documents from in and returns a list of the corresponding YAML expressions. This function accepts all keyword arguments accepted by read-yaml, which have been elided above to simplify the presentation.

procedure
(string->yaml str) → yaml?
  str : string?
procedure
(string->yaml* str) → (listof yaml?)
  str : string?
procedure
(file->yaml path [#:mode mode-flag]) → yaml?
  path : path-string?
  mode-flag : (or/c 'binary 'text) = 'binary
procedure
(file->yaml* path [#:mode mode-flag]) → (listof yaml?)
  path : path-string?
  mode-flag : (or/c 'binary 'text) = 'binary

Wrappers around read-yaml and read-yaml* using with-input-from-string and with-input-from-file. These functions accept all keyword arguments accepted by read-yaml and read-yaml*, which have been elided above to simplify the presentation.

Examples:

> (string->yaml "!invoice {id: 1, total: 251.42}")
string:0:0: could not determine a constructor for the tag
!invoice
> (string->yaml "!invoice {id: 1, total: 251.42}"
                #:allow-undefined? #t)
'#hash(("id" . 1) ("total" . 251.42))
> (string->yaml*
   (string-append
    "# Ranking of 1998 home runs\n"
    "---\n"
    "- Mark McGwire\n"
    "- Sammy Sosa\n"
    "- Ken Griffey\n"
    "\n"
    "# Team ranking\n"
    "---\n"
    "- Chicago Cubs\n"
    "- St. Louis Cardinals\n"))
'(("Mark McGwire" "Sammy Sosa" "Ken Griffey")
  ("Chicago Cubs" "St. Louis Cardinals"))

3 Writing YAML🔗ℹ

procedure
(write-yaml document
[ out
#:canonical? canonical?
#:indent indent
#:width width
#:allow-unicode? allow-unicode?
#:explicit-start? explicit-start?
#:explicit-end? explicit-end?
#:scalar-style scalar-style
#:style style
#:sort-mapping mapping-less-than?
#:sort-mapping-key mapping-extract-key]) → void?
  document : yaml?
  out : output-port? = (current-output-port)
  canonical? : boolean? = #f
  indent : exact-positive-integer? = 2
  width : exact-positive-integer? = 80
  allow-unicode? : boolean? = #f
  explicit-start? : boolean? = #f
  explicit-end? : boolean? = #f
  scalar-style : (or/c #\" #\' #\| #\> 'plain) = 'plain
  style : (or/c 'block 'flow 'best) = 'best
  mapping-less-than? : (or/c (any/c any/c . -> . any/c) #f) = #f
  mapping-extract-key : (any/c . -> . any/c) = identity

Writes a YAML expression to out as text formatted with the keyword arguments.

The #:sort-mapping argument mapping-less-than? can be used to sort the elements of mappings. When it is a function, for any mapping the sorting procedure is essentially

(sort (hash->list mapping)
mapping-less-than?
#:key mapping-extract-key)

Examples:

> (write-yaml 42 #:canonical? #t)
---
!!int "42"
> (write-yaml
   '#hash(("Apple" . 3.99) ("Orange" . 2.15) ("Cherry" . 4.12))
   #:style 'block
   #:sort-mapping string<?
   #:sort-mapping-key car)
Apple: 3.99
Cherry: 4.12
Orange: 2.15

procedure
(write-yaml* documents [out]) → void?
documents : (listof yaml?)
out : output-port? = (current-output-port)

Like write-yaml, but writes a sequence of YAML expressions to out as text formatted with the same keyword arguments. This function accepts all keyword arguments accepted by write-yaml, which have been elided above to simplify the presentation.

procedure
(yaml->string document) → string?
  document : yaml?
procedure
(yaml*->string documents) → string?
  documents : (listof yaml?)
procedure
(yaml->file document path) → void?
  document : yaml?
  path : path-string?
procedure
(yaml*->file documents path) → void?
  documents : (listof yaml?)
  path : path-string?

Wrappers around write-yaml and write-yaml* using with-output-to-string and with-output-to-file. These functions accept all keyword arguments accepted by write-yaml and write-yaml*, which have been elided above to simplify the presentation.

4 Extending YAML🔗ℹ

This module provides a simple API for extending the set of Racket values that can be written to or read from YAML. The idea is to write functions that represent Racket values as and construct them from YAML nodes.

As a running example throughout this section, we will assume the definition of a struct for baseball players, and show how to read and write instances of it in YAML.

> (struct player (name hr avg) #:transparent)

procedure
(node? v) → boolean?
  v : any/c
procedure
(scalar-node? v) → boolean?
  v : any/c
procedure
(sequence-node? v) → boolean?
  v : any/c
procedure
(mapping-node? v) → boolean?
  v : any/c

Returns #t if v is a YAML (scalar, sequence, or mapping) node, #f otherwise.

4.1 Representers🔗ℹ

parameter
(yaml-representers) → (listof yaml-representer?)
(yaml-representers representers) → void?
representers : (listof yaml-representer?)

A parameter that configures user-defined representers to use when writing YAML. It is '() by default.

procedure
(yaml-representer? v) → boolean?
v : any/c

Returns #t if v is a YAML representer, #f otherwise.

procedure
(yaml-representer type? represent) → yaml-representer?
type? : (any/c . -> . boolean?)
represent : (any/c . -> . node?)

Returns a representer that turns values of a given type? into nodes.

Examples:

> (define (represent-player p)
    (define mapping (make-hash))
    (hash-set! mapping "name" (player-name p))
    (hash-set! mapping "hr" (player-hr p))
    (hash-set! mapping "avg" (player-avg p))
    (represent-mapping "!player" mapping))
> (define player-representer
    (yaml-representer player? represent-player))
> (parameterize ([yaml-representers (list player-representer)])
    (write-yaml (player "Mark McGwire" 65 0.278)))
!player {avg: 0.278, name: Mark McGwire, hr: 65}

procedure
(represent-scalar tag str) → scalar-node?
  tag : string?
  str : string?
procedure
(represent-sequence tag lst) → sequence-node?
  tag : string?
  lst : (listof yaml?)
procedure
(represent-mapping tag hash) → mapping-node?
  tag : string?
  hash : (hash/c yaml? yaml?)

Returns a value as a YAML (scalar, sequence, or mapping) node with a given tag.

4.2 Constructors🔗ℹ

parameter
(yaml-constructors) → (listof yaml-constructor?)
(yaml-constructors constructors) → void?
constructors : (listof yaml-constructor?)

A parameter that configures user-defined constructors to use when reading YAML. It is '() by default.

procedure
(yaml-constructor? v) → boolean?
v : any/c

Returns #t if v is a YAML constructor, #f otherwise.

procedure
(yaml-constructor type? tag construct) → yaml-constructor?
  type? : (any/c . -> . boolean?)
  tag : string?
  construct : (node? . -> . yaml?)

Returns a constructor that turns nodes into values of a given type?.

Examples:

> (define (construct-player node)
    (define mapping (construct-mapping node))
    (player (hash-ref mapping "name")
            (hash-ref mapping "hr")
            (hash-ref mapping "avg")))
> (define player-constructor
    (yaml-constructor player? "!player" construct-player))
> (parameterize ([yaml-constructors (list player-constructor)])
    (string->yaml "!player {name: Sammy Sosa, hr: 63, avg: 0.288}"))
(player "Sammy Sosa" 63 0.288)

procedure
(yaml-multi-constructor? v) → boolean?
v : any/c

Returns #t if v is a YAML multi-constructor, #f otherwise.

Note that yaml-multi-constructor? is a subtype of yaml-constructor?.

procedure
(yaml-multi-constructor type?
tag-prefix
construct) → yaml-multi-constructor?
  type? : (any/c . -> . boolean?)
  tag-prefix : string?
  construct : (string? node? . -> . yaml?)

Returns a multi-constructor that turns nodes into values of a given type?.

procedure
(construct-scalar node) → string?
  node : scalar-node?
procedure
(construct-sequence node) → (listof yaml?)
  node : sequence-node?
procedure
(construct-mapping node) → (hash/c yaml? yaml?)
  node : mapping-node?

Constructs a (scalar, sequence, or mapping) value from its YAML node representation.