CL-RemiYaml

Bindings for libyaml, as well as a high-level YAML parser and emitter.

CL-RemiYaml is maintained by one person, Remilia Scarlet! If you want to support her and CL-RemiYaml, you can buy her a coffee on Ko-Fi, or support her through Liberapay. Support is greatly appreciated for this volunteer effort ^_^

Overview

This is based on the (now archived) cl-yaml and cl-libyaml libraries by Fernando Borretti (eudoxia0). It has been updated with a few fixes and API adjustments by Remilia Scarlet, and is NOT considered a drop-in replacement for cl-yaml, but is very similar.

Dependencies

• CFFI
• Alexandria
• CL-PPCRE
• parse-number

Releases

Releases can be found on the wiki.

Usage

The cl-remiyaml package (nickname: yaml) exports a few useful functions:

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

Type Mapping

CL-RemiYaml 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	:null
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-RemiYaml 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-strategy* to one of the following keywords:

1. :error: The simplest approach, simply signal the condition yaml: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.

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)))
           :pretty t)
"---
b: 2
a: 1"

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

How do I contribute?

1. Go to https://fossil.cyberia9.org/cl-remiyaml and clone the Fossil repository.
2. Create a new branch for your feature.
3. Push locally to the new branch.
4. Create a bundle with Fossil that contains your changes.
5. Get in contact with me.

Contributors

• Remilia Scarlet - maintainer
  • Homepage: https://remilia.sdf.org/
  • Fediverse: @remilia@social.cyberia9.org
  • Email: zremiliaz@postzeoz.jpz My real address does not contain Z's
• Fernando Borretti - original creator
  • cl-yaml
  • cl-libyaml

License

CL-RemiYaml is under the GNU Affero General Public License version 3.