yaml-write-stream
An easy, streaming way to generate YAML.
Installation
gem install yaml-write-stream
Usage
require 'yaml-write-stream'
Examples for the Impatient
There are two types of YAML write stream: one that uses blocks and yield
to delimit arrays (sequences) and objects (maps), and one that's purely stateful. Here are two examples that produce the same output:
Yielding:
stream = StringIO.new
YamlWriteStream.from_stream(stream) do |writer|
writer.write_map do |map_writer|
map_writer.write_key_value('foo', 'bar')
map_writer.write_sequence('baz') do |seq_writer|
seq_writer.write_element('goo')
end
end
end
Stateful:
stream = StringIO.new
writer = YamlWriteStream.from_stream(stream)
writer.write_map
writer.write_key_value('foo', 'bar')
writer.write_sequence('baz')
writer.write_element('goo')
writer.close # automatically adds closing punctuation for all nested types
Output:
stream.string # => foo: bar\nbaz:\n- goo\n
Yielding Writers
As far as yielding writers go, the example above contains everything you need. The stream will be automatically closed when the outermost block terminates.
Stateful Writers
Stateful writers have a number of additional methods:
stream = StringIO.new
writer = YamlWriteStream.from_stream(stream)
writer.write_map
writer.in_map? # => true, currently writing a map
writer.in_sequence? # => false, not currently writing a sequence
writer.eos? # => false, the stream is open and the outermost map hasn't been closed yet
writer.close_map # explicitly close the current map
writer.eos? # => true, the outermost map has been closed
writer.write_sequence # => raises YamlWriteStream::EndOfStreamError
writer.close_sequence # => raises YamlWriteStream::NotInArrayError
writer.closed? # => false, the stream is still open
writer.close # close the stream
writer.closed? # => true, the stream has been closed
Writing to a File
YamlWriteStream also supports streaming to a file via the open
method:
Yielding:
YamlWriteStream.open('path/to/file.yml') do |writer|
writer.write_map do |map_writer|
...
end
end
Stateful:
writer = YamlWriteStream.open('path/to/file.yml')
writer.write_map
...
writer.close # also closes the underlying stream
If you'd rather not close the underlying stream, you can call #flush
instead, which will add necessary closing punctuation but leave the stream open. Once a yaml write stream has been flushed, it should NOT be written to again. Treat flushed streams as if they were closed.
Requirements
Only Ruby 1.9 or greater is supported (requires the Psych emitter).
Running Tests
bundle exec rake
should do the trick. Alternatively you can run bundle exec rspec
, which does the same thing.
Authors
- Cameron C. Dutro: http://github.com/camertron