LibYAML binding for Lua, with a fast C implementation for converting between %YAML 1.1 and Lua tables, and a low-level YAML event parser for implementing more intricate YAML document loading.

These functions quickly convert back and forth between Lua tables and %YAML 1.1 format strings.

local lyaml   = require "lyaml"
local t       = lyaml.load (YAML-STRING)
local yamlstr = lyaml.dump (LUA-TABLE)
local null    = lyaml.null ()

Lua tables treat nil valued keys as if they were not there, where YAML explicitly supports null values (and keys!). Lyaml will retain YAML null values as lyaml.null () by default, though it is straight forward to wrap the low level APIs to use nil, subject to the usual caveats of how nil values work in Lua tables.

local emitter = require ("yaml").emitter ()

emitter.emit {type = "STREAM_START"}
for _, event in ipairs (event_list) do
  emitter.emit (event)
end
str = emitter.emit {type = "STREAM_END"}

The yaml.emitter function returns an emitter object that has a single emit function, which you call with event tables, the last STREAM_END event returns a string formatted as a YAML 1.1 document.

local iter = require ("yaml").scanner (YAML-STRING)

for token_table in iter () do
  -- process token table
end

Each time the iterator returned by scanner is called, it returns a table describing the next token of YAML-STRING. See LibYAML's yaml.h for details of the contents and semantics of the various tokens produced by yaml_parser_scan, the underlying call made by the iterator.

LibYAML implements a fast parser in C using yaml_parser_scan, which is also bound to lyaml, and easier to use than the token API above:

local iter = require ("yaml").parser (YAML-STRING)

for event_table in iter () do
  -- process event table
end

Each time the iterator returned by parser is called, it returns a table describing the next event from the "Parse" process of the "Parse, Compose, Construct" processing model described in the YAML 1.1 specification using LibYAML.

Implementing the remaining "Compose" and "Construct" processes in Lua is left as an exercise for the reader -- though, unlike the high-level API, lyaml.parser exposes all details of the input stream events, such as line and column numbers.

There's no need to download an lyaml release, or clone the git repo, unless you want to modify the code. If you use LuaRocks, you can use it to install the latest release from its repository:

luarocks --server=http://rocks.moonscript.org install lyaml

Or from the rockspec in a release tarball:

luarocks make lyaml-?-1.rockspec

To install current git master from GitHub (for testing):

luarocks install http://raw.github.com/gvvaughan/lyaml/release/lyaml-git-1.rockspec

To install without LuaRocks, clone the sources from the repository, and then run the following commands:

cd lyaml
./bootstrap
./configure --prefix=INSTALLATION-ROOT-DIRECTORY
make all check install

The dependencies are listed in the dependencies entry of the file rockspec.conf. You will also need Autoconf, Automake and Libtool.

See INSTALL for instructions for configure.