1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
LYAML
=====
[](http://travis-ci.org/gvvaughan/lyaml/builds)
[](https://waffle.io/gvvaughan/lyaml)
[LibYAML] binding for [Lua], with a fast C implementation
for converting between [%YAML 1.1][yaml11] and [Lua] tables,
and a low-level [YAML] event parser for implementing more
intricate [YAML] document loading.
Usage
-----
### High Level API
These functions quickly convert back and forth between Lua tables
and [%YAML 1.1][yaml11] format strings.
```lua
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.
### Low Level APIs
```lua
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][yaml11]
document.
```lua
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:
```lua
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][yaml11] 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.
Installation
------------
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][lyaml] (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][lyaml], and then run the following commands:
```sh
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][L10]. You will also need [Autoconf], [Automake]
and [Libtool].
See [INSTALL] for instructions for `configure`.
[autoconf]: http://gnu.org/s/autoconf
[automake]: http://gnu.org/s/automake
[install]: http://raw.github.com/gvvaughan/lyaml/release/INSTALL
[libtool]: http://gnu.org/s/libtool
[libyaml]: http://pyyaml.org/wiki/LibYAML
[lua]: http://www.lua.org
[luarocks]: http://www.luarocks.org
[lyaml]: http://github.com/gvvaughan/lyaml
[L10]: http://github.com/gvvaughan/lyaml/blob/master/rockspec.conf#L10
[yaml.h]: http://pyyaml.org/browser/libyaml/branches/stable/include/yaml.h
[yaml]: http://yaml.org
[yaml11]: http://yaml.org/spec/1.1/
|
