json-write-stream
json-write-stream copied to clipboard
An easy, streaming way to generate JSON.
json-write-stream
An easy, streaming way to generate JSON.
Installation
gem install json-write-stream
Usage
require 'json-write-stream'
Examples for the Impatient
There are two types of JSON write stream: one that uses blocks and yield
to delimit arrays and objects, and one that's purely stateful. Here are two examples that produce the same output:
Yielding:
stream = StringIO.new
JsonWriteStream.from_stream(stream) do |writer|
writer.write_object do |obj_writer|
obj_writer.write_key_value('foo', 'bar')
obj_writer.write_array('baz') do |arr_writer|
arr_writer.write_element('goo')
end
end
end
Stateful:
stream = StringIO.new
writer = JsonWriteStream.from_stream(stream)
writer.write_object
writer.write_key_value('foo', 'bar')
writer.write_array('baz')
writer.write_element('goo')
writer.close # automatically adds closing punctuation for all nested types
Output:
stream.string # => {"foo":"bar","baz":["goo"]}
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 = JsonWriteStream.from_stream(stream)
writer.write_object
writer.in_object? # => true, currently writing an object
writer.in_array? # => false, not currently writing an array
writer.eos? # => false, the stream is open and the outermost object hasn't been closed yet
writer.close_object # explicitly close the current object
writer.eos? # => true, the outermost object has been closed
writer.write_array # => raises JsonWriteStream::EndOfStreamError
writer.close_array # => raises JsonWriteStream::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
JsonWriteStream also supports streaming to a file via the open
method:
Yielding:
JsonWriteStream.open('path/to/file.json') do |writer|
writer.write_object do |obj_writer|
...
end
end
Stateful:
writer = JsonWriteStream.open('path/to/file.json')
writer.write_object
...
writer.close
Options
JsonWriteStream supports generating "pretty" JSON, i.e. JSON formatted in a more human-readable way. Currently only the stateful writer supports pretty generation. Example:
stream = StringIO.new
writer = JsonWriteStream.from_stream(stream, pretty: true)
writer.write_object
writer.write_key_value('foo', 'bar')
writer.write_array('baz')
writer.write_element('goo')
writer.close
Now stream.string
will contain
{
"foo": "bar",
"baz": [
"goo"
]
}
Requirements
No external requirements.
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