YAML

Version: 5.3

YAML

(require (planet esilkensen/yaml:1:=0))

This module provides utilities for parsing and emitting data in the YAML data serialization format to and from Racket values. See the YAML web site for more information about YAML. The implementation is ported from PyYAML.

1 Examples

As a quick introduction, this section shows an example of using the module to go from Racket values to YAML and back again.

The write-yaml procedure turns a Racket value into YAML output. Here it displays a sequence of mappings in flow style (by default):

> (write-yaml
   '(#hash(("name" . "Mark McGwire")
           ("hr" . 65)
           ("avg" . 0.278))
     #hash(("name" . "Sammy Sosa")
           ("hr" . 63)
           ("avg" . 0.288))))
- {hr: 65, avg: 0.278, name: Mark McGwire}
- {hr: 63, avg: 0.288, name: Sammy Sosa}

The string->yaml procedure turns YAML text into a Racket value. Here it constructs the same sequence of mappings from above, where this time the YAML is in block style:

> (string->yaml
   (string-append
    "- name: Mark McGwire\n"
    "  hr:   65\n"
    "  avg:  0.278\n"
    "- name: Sammy Sosa\n"
    "  hr:   63\n"
    "  avg:  0.288\n"))
'(#hash(("name" . "Mark McGwire") ("avg" . 0.278) ("hr" . 65))
  #hash(("name" . "Sammy Sosa") ("avg" . 0.288) ("hr" . 63)))

The yaml-struct macro defines a struct that can be written to and read from YAML:

> (yaml-struct player (name hr avg) #:transparent)
> (write-yaml (player "Mark McGwire" 65 0.278))
!!struct:player {hr: 65, avg: 0.278, name: Mark McGwire}
> (string->yaml
"!!struct:player {hr: 65, avg: 0.278, name: Mark McGwire}")
(player "Mark McGwire" 65 0.278)

2 YAML Expressions

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

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

This library defines a subset of Racket values that can be represented as YAML strings, and this predicate checks for such values. A YAML expression is one of:

the value of (yaml-null)
(or/c boolean? string? exact-integer? inexact-real? date?)
(cons/c yaml? yaml?)
a nonempty (listof yaml?)
a nonempty (hash/c yaml? yaml?)
a nonempty (set/c yaml?)
a yaml-struct? whose fields are all yaml?

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

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

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

Returns #t if v is an instance of a YAML structure, #f otherwise.

syntax
(yaml-struct id maybe-super (field ...)
struct-option ...)

Creates a new structure that can be used as a YAML expression. This macro expands to a call to struct that uses #:methods to register itself with the YAML implementation.

3 Reading YAML

procedure
(read-yaml [source-name in]) → yaml?
source-name : any/c = 'input
in : input-port? = (current-input-port)

Parses the first YAML document from in and returns the corresponding YAML expression in Racket. The source-name is used to identify the source of the input in error messages.

procedure
(read-yaml* [source-name in]) → (listof yaml?)
source-name : any/c = 'input
in : input-port? = (current-input-port)

Like read-yaml, but parses all YAML documents from in and returns a list of the corresponding YAML expressions in Racket.

procedure
(string->yaml str) → yaml?
str : string?

Equivalent to

(with-input-from-string str
(λ () (read-yaml 'string)))

procedure
(string->yaml* str) → (listof yaml?)
str : string?

Equivalent to

(with-input-from-string str
(λ () (read-yaml* 'string)))

4 Writing YAML

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

Equivalent to

(write-yaml* (list document) out ....)

Accepts the same keyword arguments as write-yaml* (represented above by ....).

procedure
(write-yaml* documents
[ out
#:canonical canonical
#:indent indent
#:width width
#:explicit-start explicit-start
#:explicit-end explicit-end
#:scalar-style scalar-style
#:style style]) → void?
  documents : (listof yaml?)
  out : output-port? = (current-output-port)
  canonical : boolean? = #f
  indent : exact-positive-integer? = 2
  width : exact-positive-integer? = 80
  explicit-start : boolean? = #f
  explicit-end : boolean? = #f
  scalar-style : (or/c #\" #\' #\| #\> 'plain) = 'plain
  style : (or/c 'block 'flow 'best) = 'best

Writes a sequence of Racket YAML expressions to out as YAML text formatted with the keyword arguments. See the YAML specification for more information on style.

procedure
(yaml->string document) → string?
document : yaml?

Equivalent to

(with-output-to-string
(λ () (write-yaml document ....)))

Accepts the same keyword arguments as write-yaml (represented above by ....).

procedure
(yaml*->string documents) → string?
documents : (listof yaml?)

Equivalent to

(with-output-to-string
(λ () (write-yaml* documents ....)))

Accepts the same keyword arguments as write-yaml* (represented above by ....).