nyaml

nyaml copied to clipboard

= NYAML a Native YAML parser for Common Lisp :toc:

NYAML allows parsing https://yaml.org[YAML] documents without relying on libyaml.

== API

Generic Function PARSE:: + Syntax::: parse input &key multi-document-p => parsed-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
• bool -> T and NIL
• seq -> simple-vector
• int -> integer
• float -> double-float; infinity and NaN depend on the Lisp implementation and may signal an error
• map -> hash-table with test equal
• str -> string

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