Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/camertron/yaml-write-stream
An easy, streaming way to generate YAML.
https://github.com/camertron/yaml-write-stream
Last synced: 18 days ago
JSON representation
An easy, streaming way to generate YAML.
- Host: GitHub
- URL: https://github.com/camertron/yaml-write-stream
- Owner: camertron
- Created: 2014-09-24T06:19:27.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2016-08-03T22:33:52.000Z (over 8 years ago)
- Last Synced: 2024-11-04T00:42:00.522Z (2 months ago)
- Language: Ruby
- Size: 21.5 KB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: History.txt
Awesome Lists containing this project
README
yaml-write-stream
=================
[](http://travis-ci.org/camertron/yaml-write-stream)
An easy, streaming way to generate YAML.
## Installation
`gem install yaml-write-stream`
## Usage
```ruby
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:
```ruby
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:
```ruby
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:
```ruby
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:
```ruby
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:
```ruby
YamlWriteStream.open('path/to/file.yml') do |writer|
writer.write_map do |map_writer|
...
end
end
```
Stateful:
```ruby
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