/nyaml

A lisp native YAML parser

Primary LanguageCommon LispMIT LicenseMIT

NYAML a Native YAML parser for Common Lisp

NYAML allows parsing YAML documents without relying on libyaml.

API

Generic Function PARSE
Syntax

parse input &key multi-document-pparsed-document

Arguments and Values
  • input A pathname or an input-stream or a string

  • multi-document-p a boolean indicating if the input may contain multiple documents

Description

parse consumes and parses the entire input as a YAML file.

If input is a string, it parses it as is.

If input is a stream with an element-type that is a subtype of character then the entire stream is parsed as a string.

If input is a stream of element-type '(unsigned-byte 8) the encoding is detected per the YAML specification, and then it is decoded and parsed as a string.

Mapping of YAML types to Lisp

This is configurable (see below) but the default is:

  • null:null

  • boolT and NIL

  • seqsimple-vector

  • intinteger

  • floatdouble-float; infinity and NaN depend on the Lisp implementation and may signal an error

  • maphash-table with test equal

  • strstring

Variable *NULL*
Initial Value

:NULL

Description

The value that null objects from YAML will be parsed as

Variable *FALSE*
Initial Value

NIL

Description

The value that false boolean objects from YAML will be parsed as

Variable *MAKE-MAP*
Initial Value

A function that creates an empty hash-table with test of cl:equal

Description

Called whenever a map is encountered in the YAML parse tree

Variable *MAP-INSERT*
Initial Value

A function that inserts a key into a hash-table and returns the table

Description

A function with a lambda list of (map key value) that takes an existing map created with make-map, and returns a new map that includes a mapping from key to value. May modify the map argument.

This is called for every map entry encountered in the YAML parse tree

Variable *LIST-TO-SEQ*
Initial Value

A function that coerces its argument to a simple-vector

Description

A function with a lambda list of (list) that takes a list of items and returns the sequence representation for that list.

This is called once for every sequence in the YAML parse tree

Limitations

  • NYAML is not a streaming parser; it reads the entire stream into memory before parsing and will parse all YAML documents in the stream at once.

  • The entire stream must be valid YAML; NYAML cannot e.g. parse a non-YAML file with a YAML header

  • Not all tag processing is currently implemented; tags are parsed, but often ignored. (cl-yaml seems to ignore tags, FWIW)

Known Incompatibilities with cl-yaml

  • The default types for parsing objects are different; [], null, and false produce respectively as #(), :null, and nil. In cl-yaml they are all produce nil. These are all dynamically configurable and there is a convenience macro with-cl-yaml-semantics that establishes a dynamic environment that acts more like cl-yaml

  • Bare "-" characters inside flows are not parsed as scalars; some YAML parsers (including libyaml) allow this, others do not. The specification seems pretty clear that it’s disallowed. An example that is accepted by cl-yaml but not nyaml is [-,-].

  • Empty documents are parsed as null rather than the empty-string. This is currently not configurable, but could probably be made configurable if it causes real-world problems.

TODOs

  • The YAML output currently has zero tests