The cl-yaml Reference Manual

Table of Contents

The cl-yaml Reference Manual

This is the cl-yaml Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Mar 25 17:44:47 2020 GMT+0.

1 Introduction

cl-yaml

A YAML parser and emitter built on top of libyaml. Uses the cl-libyaml library.

Usage

The yaml package exports three functions:

• (parse string-or-pathname): Parses a string or a pathname into Lisp values.
• (emit value stream): Emit a Lisp value into a stream.
• (emit-to-string value): Emit a Lisp value into a string.

Parsing

CL-USER> (yaml:parse "[1, 2, 3]")
(1 2 3)

CL-USER> (yaml:parse "{ a: 1, b: 2 }")
{"a" => 1, "b" => 2}

CL-USER> (yaml:parse "- Mercury
- Venus
- Earth
- Mars")
("Mercury" "Venus" "Earth" "Mars")

CL-USER> (yaml:parse "foo
---
bar" :multi-document-p t)
(:DOCUMENTS "foo" "bar")

Emitting

CL-USER> (yaml:emit-to-string (list 1 2 3))
"[1, 2, 3]"

CL-USER> (yaml:emit-to-string
           (alexandria:alist-hash-table '(("a" . 1)
                                          ("b" . 2))))
"{ b: 2, a: 1 }"

CL-USER> (yaml:emit (list t 123 3.14) *standard-output*)
[true, 123, 3.14]

Documentation

Type Mapping

cl-yaml uses YAML's Core Schema to map YAML values to Lisp types an vice versa. A table showing the correspondence of values and types is shown below:

| YAML type | Lisp type | | ---------- | ----------------- | | Null | nil | | Boolean | t and nil | | Integer | Integer | | Float | Double float | | String | String | | List | List | | Map | Hash table | | Document | (:document ...) |

IEEE Floating Point Support

Common Lisp doesn't natively support the IEEE special floating point values: NaN (Not a number), positive infinity and negative infinity are unrepresentable in portable Common Lisp. Since YAML allows documents to include these values, we have to figure out what to do with them. cl-yaml supports multiple float strategies.

The default strategy is :keyword, which uses keywords to represent these values. The strategy can be customized by setting the value of yaml.float:*float-strategy* to one of the following keywords:

1. :error: The simplest approach, simply signal the condition yaml.error:unsupported-float-value whenever a NaN or infinity value is encountered.

2. :keyword: Use keywords to represent the different values, i.e.: :NaN for NaN, :+Inf for positive infinity and :-Inf for negative infinity.

3. :best-effort: Use implementation-specific values whenever possible, fall back on :keyword in unsupported implementations. On SBCL and Allegro Common Lisp, NaN and infinity can be represented.

License

Copyright (c) 2013-2015 Fernando Borretti

Licensed under the MIT License.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 cl-yaml

Maintainer

Fernando Borretti <eudoxiahp@gmail.com>

Author

Fernando Borretti <eudoxiahp@gmail.com>

Home Page

https://github.com/eudoxia0/cl-yaml

Source Control

(:git "git@github.com:eudoxia0/cl-yaml.git")

Bug Tracker

https://github.com/eudoxia0/cl-yaml/issues

License

MIT

Description

A YAML parser and emitter.

Long Description

# cl-yaml

[](https://travis-ci.org/eudoxia0/cl-yaml)
[](https://coveralls.io/r/eudoxia0/cl-yaml?branch=master) [](http://quickdocs.org/cl-yaml/)

A YAML parser and emitter built on top of [libyaml][libyaml]. Uses the
[cl-libyaml][cl-libyaml] library.

# Usage

The ‘yaml‘ package exports three functions:

* ‘(parse string-or-pathname)‘: Parses a string or a pathname into Lisp values.
* ‘(emit value stream)‘: Emit a Lisp value into a stream.
* ‘(emit-to-string value)‘: Emit a Lisp value into a string.

## Parsing

“‘lisp
CL-USER> (yaml:parse "[1, 2, 3]")
(1 2 3)

CL-USER> (yaml:parse "{ a: 1, b: 2 }")
{"a" => 1, "b" => 2}

CL-USER> (yaml:parse "- Mercury
- Venus
- Earth
- Mars")
("Mercury" "Venus" "Earth" "Mars")

CL-USER> (yaml:parse "foo
—
bar" :multi-document-p t)
(:DOCUMENTS "foo" "bar")
“‘

## Emitting

“‘lisp
CL-USER> (yaml:emit-to-string (list 1 2 3))
"[1, 2, 3]"

CL-USER> (yaml:emit-to-string
(alexandria:alist-hash-table ’(("a" . 1)
("b" . 2))))
"{ b: 2, a: 1 }"

CL-USER> (yaml:emit (list t 123 3.14) *standard-output*)
[true, 123, 3.14]
“‘

# Documentation

## Type Mapping

cl-yaml uses YAML’s [Core Schema][core-schema] to map YAML values to Lisp types
an vice versa. A table showing the correspondence of values and types is shown
below:

| YAML type | Lisp type |
| ———- | —————– |
| Null | ‘nil‘ |
| Boolean | ‘t‘ and ‘nil‘ |
| Integer | Integer |
| Float | Double float |
| String | String |
| List | List |
| Map | Hash table |
| Document | ‘(:document ...)‘ |

## IEEE Floating Point Support

Common Lisp doesn’t natively support the IEEE special floating point values: NaN
(Not a number), positive infinity and negative infinity are unrepresentable in
portable Common Lisp. Since YAML allows documents to include these values, we
have to figure out what to do with them. cl-yaml supports multiple float
strategies.

The default strategy is ‘:keyword‘, which uses keywords to represent these
values. The strategy can be customized by setting the value of
‘yaml.float:*float-strategy*‘ to one of the following keywords:

1. ‘:error‘: The simplest approach, simply signal the condition
‘yaml.error:unsupported-float-value‘ whenever a NaN or infinity value is
encountered.

2. ‘:keyword‘: Use keywords to represent the different values, i.e.: ‘:NaN‘ for
NaN, ‘:+Inf‘ for positive infinity and ‘:-Inf‘ for negative infinity.

3. ‘:best-effort‘: Use implementation-specific values whenever possible, fall
back on ‘:keyword‘ in unsupported implementations. On SBCL and Allegro Common
Lisp, NaN and infinity can be represented.

[core-schema]: http://www.yaml.org/spec/1.2/spec.html#id2804923
[libyaml]: http://pyyaml.org/wiki/LibYAML
[cl-libyaml]: https://github.com/eudoxia0/cl-libyaml

# License

Copyright (c) 2013-2015 Fernando Borretti

Licensed under the MIT License.

Version

0.1

Dependencies

• cl-libyaml
• alexandria
• cl-ppcre
• parse-number

Source

cl-yaml.asd (file)

Component

src (module)

3 Modules

Modules are listed depth-first from the system components tree.

3.1 cl-yaml/src

Parent

cl-yaml (system)

Location

src/

Components

• error.lisp (file)
• float.lisp (file)
• scalar.lisp (file)
• parser.lisp (file)
• emitter.lisp (file)
• yaml.lisp (file)

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.

4.1 Lisp

4.1.1 cl-yaml.asd

Location

cl-yaml.asd

Systems

cl-yaml (system)

4.1.2 cl-yaml/src/error.lisp

Parent

src (module)

Location

src/error.lisp

Packages

yaml.error

Exported Definitions

• column (method)
• line (method)
• message (method)
• parsing-error (condition)
• unsupported-float-value (condition)
• yaml-error (condition)

4.1.3 cl-yaml/src/float.lisp

Dependency

error.lisp (file)

Parent

src (module)

Location

src/float.lisp

Packages

yaml.float

Exported Definitions

• *float-strategy* (special variable)
• negative-infinity (function)
• not-a-number (function)
• positive-infinity (function)

Internal Definitions

*sbcl-nan-value* (special variable)

4.1.4 cl-yaml/src/scalar.lisp

Dependency

float.lisp (file)

Parent

src (module)

Location

src/scalar.lisp

Packages

yaml.scalar

Exported Definitions

parse-scalar (function)

Internal Definitions

• +false+ (special variable)
• +false-names+ (special variable)
• +float-scanner+ (special variable)
• +hex-integer-scanner+ (special variable)
• +integer-scanner+ (special variable)
• +nan-names+ (special variable)
• +negative-infinity-scanner+ (special variable)
• +null+ (special variable)
• +null-names+ (special variable)
• +octal-integer-scanner+ (special variable)
• +positive-infinity-scanner+ (special variable)
• +quoted-scalar-styles+ (special variable)
• +true-names+ (special variable)

4.1.5 cl-yaml/src/parser.lisp

Dependency

scalar.lisp (file)

Parent

src (module)

Location

src/parser.lisp

Packages

yaml.parser

Exported Definitions

• parse-string (function)
• register-mapping-converter (function)
• register-scalar-converter (function)
• register-sequence-converter (function)

Internal Definitions

• +mapping-converters+ (special variable)
• +scalar-converters+ (special variable)
• +sequence-converters+ (special variable)
• convert-mapping (function)
• convert-scalar (function)
• convert-sequence (function)
• mapping-converter (function)
• parse-tokens (function)
• parse-yaml (function)
• scalar-converter (function)
• sequence-converter (function)
• signal-reader-error (function)

4.1.6 cl-yaml/src/emitter.lisp

Dependency

parser.lisp (file)

Parent

src (module)

Location

src/emitter.lisp

Packages

yaml.emitter

Exported Definitions

• document-end-event (function)
• document-start-event (function)
• emit (function)
• emit-document (macro)
• emit-mapping (macro)
• emit-object (generic function)
• emit-object (method)
• emit-object (method)
• emit-object (method)
• emit-object (method)
• emit-scalar (function)
• emit-sequence (macro)
• emit-stream (macro)
• emit-to-string (function)
• encode (generic function)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• mapping-end-event (function)
• mapping-start-event (function)
• print-scalar (generic function)
• print-scalar (method)
• print-scalar (method)
• print-scalar (method)
• print-scalar (method)
• print-scalar (method)
• print-scalar (method)
• print-scalar (method)
• scalar-event (function)
• sequence-end-event (function)
• sequence-start-event (function)
• stream-end-event (function)
• stream-start-event (function)
• with-emitter-to-stream (macro)
• with-emitter-to-string (macro)

Internal Definitions

• foreign-emitter (function)
• foreign-event (function)

4.1.7 cl-yaml/src/yaml.lisp

Dependency

emitter.lisp (file)

Parent

src (module)

Location

src/yaml.lisp

Packages

cl-yaml

Exported Definitions

• emit (function)
• emit-to-string (function)
• parse (generic function)
• parse (method)
• parse (method)

5 Packages

Packages are listed by definition order.

5.1 yaml.error

YAML errors.

Source

error.lisp (file)

Use List

common-lisp

Exported Definitions

• column (generic function)
• column (method)
• line (generic function)
• line (method)
• message (generic function)
• message (method)
• parsing-error (condition)
• unsupported-float-value (condition)
• yaml-error (condition)

5.2 yaml.float

Handle IEEE floating point values.

Source

float.lisp (file)

Use List

common-lisp

Exported Definitions

• *float-strategy* (special variable)
• negative-infinity (function)
• not-a-number (function)
• positive-infinity (function)

Internal Definitions

*sbcl-nan-value* (special variable)

5.3 yaml.scalar

Parser for scalar values.

Source

scalar.lisp (file)

Use List

common-lisp

Exported Definitions

parse-scalar (function)

Internal Definitions

• +false+ (special variable)
• +false-names+ (special variable)
• +float-scanner+ (special variable)
• +hex-integer-scanner+ (special variable)
• +integer-scanner+ (special variable)
• +nan-names+ (special variable)
• +negative-infinity-scanner+ (special variable)
• +null+ (special variable)
• +null-names+ (special variable)
• +octal-integer-scanner+ (special variable)
• +positive-infinity-scanner+ (special variable)
• +quoted-scalar-styles+ (special variable)
• +true-names+ (special variable)

5.4 yaml.parser

The YAML parser.

Source

parser.lisp (file)

Use List

common-lisp

Exported Definitions

• parse-string (function)
• register-mapping-converter (function)
• register-scalar-converter (function)
• register-sequence-converter (function)

Internal Definitions

• +mapping-converters+ (special variable)
• +scalar-converters+ (special variable)
• +sequence-converters+ (special variable)
• convert-mapping (function)
• convert-scalar (function)
• convert-sequence (function)
• mapping-converter (function)
• parse-tokens (function)
• parse-yaml (function)
• scalar-converter (function)
• sequence-converter (function)
• signal-reader-error (function)

5.5 yaml.emitter

The YAML emitter.

Source

emitter.lisp (file)

Use List

common-lisp

Exported Definitions

• document-end-event (function)
• document-start-event (function)
• emit (function)
• emit-document (macro)
• emit-mapping (macro)
• emit-object (generic function)
• emit-object (method)
• emit-object (method)
• emit-object (method)
• emit-object (method)
• emit-scalar (function)
• emit-sequence (macro)
• emit-stream (macro)
• emit-to-string (function)
• encode (generic function)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• encode (method)
• mapping-end-event (function)
• mapping-start-event (function)
• print-scalar (generic function)
• print-scalar (method)
• print-scalar (method)
• print-scalar (method)
• print-scalar (method)
• print-scalar (method)
• print-scalar (method)
• print-scalar (method)
• scalar-event (function)
• sequence-end-event (function)
• sequence-start-event (function)
• stream-end-event (function)
• stream-start-event (function)
• with-emitter-to-stream (macro)
• with-emitter-to-string (macro)

Internal Definitions

• foreign-emitter (function)
• foreign-event (function)

5.6 cl-yaml

The main YAML interface.

Source

yaml.lisp (file)

Nickname

yaml

Use List

common-lisp

Exported Definitions

• emit (function)
• emit-to-string (function)
• parse (generic function)
• parse (method)
• parse (method)

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

6.1 Exported definitions

6.1.1 Special variables

Special Variable: *float-strategy*

Package

yaml.float

Source

float.lisp (file)

6.1.2 Macros

Macro: emit-document (EMITTER &rest REST &key VERSION-DIRECTIVE TAG-DIRECTIVE-START TAG-DIRECTIVE-END IMPLICIT) &body BODY

Package

yaml.emitter

Source

emitter.lisp (file)

Macro: emit-mapping (EMITTER &rest REST &key ANCHOR TAG IMPLICIT STYLE) &body BODY

Package

yaml.emitter

Source

emitter.lisp (file)

Macro: emit-sequence (EMITTER &rest REST &key ANCHOR TAG IMPLICIT STYLE) &body BODY

Package

yaml.emitter

Source

emitter.lisp (file)

Macro: emit-stream (EMITTER &key ENCODING) &body BODY

Package

yaml.emitter

Source

emitter.lisp (file)

Macro: with-emitter-to-stream (EMITTER-VAR OUTPUT-STREAM) &rest BODY

Package

yaml.emitter

Source

emitter.lisp (file)

Macro: with-emitter-to-string (EMITTER-VAR) &rest BODY

Package

yaml.emitter

Source

emitter.lisp (file)

6.1.3 Functions

Function: document-end-event EVENT &key IMPLICIT

Package

yaml.emitter

Source

emitter.lisp (file)

Function: document-start-event EVENT &key VERSION-DIRECTIVE TAG-DIRECTIVE-START TAG-DIRECTIVE-END IMPLICIT

Package

yaml.emitter

Source

emitter.lisp (file)

Function: emit VALUE STREAM

Emit a value to a stream.

Package

yaml.emitter

Source

emitter.lisp (file)

Function: emit VALUE STREAM

Package

cl-yaml

Source

yaml.lisp (file)

Function: emit-scalar EMITTER VALUE &rest REST &key ANCHOR TAG PLAIN-IMPLICIT QUOTED-IMPLICIT STYLE

Package

yaml.emitter

Source

emitter.lisp (file)

Function: emit-to-string VALUE

Emit a value to string.

Package

yaml.emitter

Source

emitter.lisp (file)

Function: emit-to-string VALUE

Package

cl-yaml

Source

yaml.lisp (file)

Function: mapping-end-event EVENT

Package

yaml.emitter

Source

emitter.lisp (file)

Function: mapping-start-event EVENT &key ANCHOR TAG IMPLICIT STYLE

Package

yaml.emitter

Source

emitter.lisp (file)

Function: negative-infinity ()

Package

yaml.float

Source

float.lisp (file)

Function: not-a-number ()

Package

yaml.float

Source

float.lisp (file)

Function: parse-scalar STRING &optional STYLE

Parse a YAML scalar string into a Lisp scalar value.

Package

yaml.scalar

Source

scalar.lisp (file)

Function: parse-string YAML-STRING

Package

yaml.parser

Source

parser.lisp (file)

Function: positive-infinity ()

Package

yaml.float

Source

float.lisp (file)

Function: register-mapping-converter TAG CONVERTER

Package

yaml.parser

Source

parser.lisp (file)

Function: register-scalar-converter TAG CONVERTER

Package

yaml.parser

Source

parser.lisp (file)

Function: register-sequence-converter TAG CONVERTER

Package

yaml.parser

Source

parser.lisp (file)

Function: scalar-event EVENT VALUE LENGTH &key ANCHOR TAG PLAIN-IMPLICIT QUOTED-IMPLICIT STYLE

Package

yaml.emitter

Source

emitter.lisp (file)

Function: sequence-end-event EVENT

Package

yaml.emitter

Source

emitter.lisp (file)

Function: sequence-start-event EVENT &key ANCHOR TAG IMPLICIT STYLE

Package

yaml.emitter

Source

emitter.lisp (file)

Function: stream-end-event EVENT

Package

yaml.emitter

Source

emitter.lisp (file)

Function: stream-start-event EVENT &key ENCODING

Package

yaml.emitter

Source

emitter.lisp (file)

6.1.4 Generic functions

Generic Function: column CONDITION

Package

yaml.error

Methods

Method: column (CONDITION parsing-error)

Source

error.lisp (file)

Generic Function: emit-object EMITTER OBJ

Emit YAML representation of obj

Package

yaml.emitter

Source

emitter.lisp (file)

Methods

Method: emit-object EMITTER (OBJ float)

Method: emit-object EMITTER (OBJ integer)

Method: emit-object EMITTER (OBJ string)

Method: emit-object EMITTER (OBJ symbol)

Generic Function: encode VALUE STREAM

Write the YAML corresponding to value to a stream.

Package

yaml.emitter

Source

emitter.lisp (file)

Methods

Method: encode (TABLE hash-table) STREAM

Encode a hash table.

Method: encode (VECTOR vector) STREAM

Encode a vector.

Method: encode (LIST list) STREAM

Encode a list.

Method: encode (STRING string) STREAM

Encode a string.

Method: encode (FLOAT float) STREAM

Encode a float.

Method: encode (INTEGER integer) STREAM

Encode an integer.

Method: encode (TRUE (eql nil)) STREAM

Encode false.

Method: encode (TRUE (eql t)) STREAM

Encode true.

Generic Function: line CONDITION

Package

yaml.error

Methods

Method: line (CONDITION parsing-error)

Source

error.lisp (file)

Generic Function: message CONDITION

Package

yaml.error

Methods

Method: message (CONDITION parsing-error)

Source

error.lisp (file)

Generic Function: parse INPUT &key MULTI-DOCUMENT-P

Parse a YAML string or a pathname to a YAML file into Lisp data.

Package

cl-yaml

Source

yaml.lisp (file)

Methods

Method: parse (INPUT pathname) &key MULTI-DOCUMENT-P

Method: parse (INPUT string) &key MULTI-DOCUMENT-P

Generic Function: print-scalar SCALAR

Convert a scalar object into its printed representation

Package

yaml.emitter

Source

emitter.lisp (file)

Methods

Method: print-scalar (SCALAR double-float)

Method: print-scalar (SCALAR single-float)

Method: print-scalar (SCALAR integer)

Method: print-scalar (SCALAR string)

Method: print-scalar (SCALAR symbol)

Method: print-scalar (SCALAR (eql nil))

Method: print-scalar (SCALAR (eql t))

6.1.5 Conditions

Condition: parsing-error ()

An error when parsing a YAML file.

Package

yaml.error

Source

error.lisp (file)

Direct superclasses

yaml-error (condition)

Direct methods

• column (method)
• line (method)
• message (method)

Direct slots

Slot: message

The error message.

Initargs

:message

Readers

message (generic function)

Slot: line

The line where the error happened.

Initargs

:line

Readers

line (generic function)

Slot: column

The column where the error happened.

Initargs

:column

Readers

column (generic function)

Condition: unsupported-float-value ()

This condition is signalled when the parser receives an IEEE
floating point special value it cannot parse. This is only signalled when the floating point strategy is :error.

Package

yaml.error

Source

error.lisp (file)

Direct superclasses

yaml-error (condition)

Condition: yaml-error ()

The base class of all YAML conditions.

Package

yaml.error

Source

error.lisp (file)

Direct superclasses

condition (condition)

Direct subclasses

• parsing-error (condition)
• unsupported-float-value (condition)

6.2 Internal definitions

6.2.1 Special variables

Special Variable: *sbcl-nan-value*

Package

yaml.float

Source

float.lisp (file)

Special Variable: +false+

The falsehood constant. Nil by default.

Package

yaml.scalar

Source

scalar.lisp (file)

Special Variable: +false-names+

Package

yaml.scalar

Source

scalar.lisp (file)

Special Variable: +float-scanner+

Package

yaml.scalar

Source

scalar.lisp (file)

Special Variable: +hex-integer-scanner+

Package

yaml.scalar

Source

scalar.lisp (file)

Special Variable: +integer-scanner+

Package

yaml.scalar

Source

scalar.lisp (file)

Special Variable: +mapping-converters+

Package

yaml.parser

Source

parser.lisp (file)

Special Variable: +nan-names+

Package

yaml.scalar

Source

scalar.lisp (file)

Special Variable: +negative-infinity-scanner+

Package

yaml.scalar

Source

scalar.lisp (file)

Special Variable: +null+

The NULL constant. Nil by default.

Package

yaml.scalar

Source

scalar.lisp (file)

Special Variable: +null-names+

Package

yaml.scalar

Source

scalar.lisp (file)

Special Variable: +octal-integer-scanner+

Package

yaml.scalar

Source

scalar.lisp (file)

Special Variable: +positive-infinity-scanner+

Package

yaml.scalar

Source

scalar.lisp (file)

Special Variable: +quoted-scalar-styles+

Package

yaml.scalar

Source

scalar.lisp (file)

Special Variable: +scalar-converters+

Package

yaml.parser

Source

parser.lisp (file)

Special Variable: +sequence-converters+

Package

yaml.parser

Source

parser.lisp (file)

Special Variable: +true-names+

Package

yaml.scalar

Source

scalar.lisp (file)

6.2.2 Functions

Function: convert-mapping HASHTABLE TAG

Package

yaml.parser

Source

parser.lisp (file)

Function: convert-scalar STRING TAG &optional STYLE

Package

yaml.parser

Source

parser.lisp (file)

Function: convert-sequence LIST TAG

Package

yaml.parser

Source

parser.lisp (file)

Function: foreign-emitter EMITTER

Package

yaml.emitter

Source

emitter.lisp (file)

Function: foreign-event EMITTER

Package

yaml.emitter

Source

emitter.lisp (file)

Function: mapping-converter TAG

Package

yaml.parser

Source

parser.lisp (file)

Function: parse-tokens VECTOR

Package

yaml.parser

Source

parser.lisp (file)

Function: parse-yaml INPUT

Parse a YAML string, returning a list of tokens.

Package

yaml.parser

Source

parser.lisp (file)

Function: scalar-converter TAG

Package

yaml.parser

Source

parser.lisp (file)

Function: sequence-converter TAG

Package

yaml.parser

Source

parser.lisp (file)

Function: signal-reader-error PARSER

Package

yaml.parser

Source

parser.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types