lua-users home
lua-l archive

[Date Prev][Date Next][Thread Prev][Thread Next] [Date Index] [Thread Index]


Read and write YAML format files with Lua.

I am happy to announce release 6.0 of lyaml.

lyaml's home page is at http://github.com/gvvaughan/lyaml and for
this releaseswe have new LDoc generated API documentation at
http://gvvaughan.github.io/lyaml.

## Noteworthy changes in release 6.0 (2015-07-27) [stable]

### New Features

  - `lyaml.load` now correctly reads a !!bool tagged scalar from a
    YAML document, or an implicit bool value, according to
    [the specification][boolspec].

    ```yaml
    %TAG ! tag:yaml.org,2002:
    ---
    truthy:
      - !bool Y
      - !bool y
      - !bool True
      - !bool "on"
    falsey:
      - !bool n
      - !bool OFF
      - !bool garbage
    ```

  - `lyaml.load` now correctly reads a !!float tagged scalar from a
    YAML document, or an implicit float value, according to
    [the specification][floatspec].

  - `lyaml.load` now correctly reads a !!int tagged scalar from a
    YAML document, or an implicit integer value, according to
    [the specification][intspec].

  - `lyaml.load` now supports the !!merge key type according to
    [the specification][mergespec].

    ```yaml
    - &MERGE { x: 1, y: 2 }
    - &OVERRIDE { x: 0, z: 1 }
    -
      << : [&MERGE, &OVERRIDE]
      z: 3
    ```

    The anchored tables remain in the document too, so this results in
    the following Lua table:

    ```lua
    {                           -- START_STREAM
      {                         -- START_DOCUMENT
        { x = 1, y = 2 },       -- MERGE
        { x = 0, z = 1 },       -- OVERRIDE
        { x = 1, y = 2, z = 3}, -- <<<
      }                         -- END_DOCUMENT
    }                           -- END_STREAM
    ```

### Bug fixes

  - Multi-line strings were previously being dumped using single quotes
    which caused the dumped YAML to break.

    For example, { foo = "a\nmultiline\nstring" } would get dumped as:

    ```yaml
    foo: 'a

    multiline

    string'
    ```

    Note the extra line-breaks in between each line. This also causes
    YAML parsing to fail (since the blank lines didn't have the expected
    indentation).

    This patch fixes the dump to use the YAML literal syntax for any
    multi-line strings so the same example gets dumped as:

    ```yaml
    foo: |-
      a
      multiline
      string
    ```

  - `lyaml.load` now correctly reads the !!null tag in a YAML
    document as an `lyaml.null` reference, identical to the "~"
    shorthand syntax, according to [the specification][nullspec].

### Incompatible Changes

  - `lyaml.load` now takes a table of options as an optional second
    argument, not a simple boolean to determine whether all documents
    should be returned from the stream.  For now, a `true` second
    argument will be converted to the modern equivalent:

    ```lua
    lyaml.load (document, { all = true })
    ```

  - `lyaml.dump` now takes a table of options as an optional second
    argument, not an initial table of anchors.  For now, a second
    argument without any new API keys will be converted to the modern
    equivalent:

    ```lua
    lyaml.dump (t, { anchors = arg2 })
    ```

Install it with LuaRocks, using:

    luarocks install lyaml 6.0


[boolspec]:  http://yaml.org/type/bool.html
[floatspec]: http://yaml.org/type/float.html
[intspec]:   http://yaml.org/type/int.html
[mergespec]: http://yaml.org/type/merge.html
[nullspec]:  http://yaml.org/type/null.html