yaml-write-stream 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c3b944beb4d212490ae2f8900f090869bbbf1783
+  data.tar.gz: 3d69474c75ca853562dd964956b778220335fbf4
+SHA512:
+  metadata.gz: f95dcf646a2930f5459fd021eb0751bca932315269977934ef5e444cc59396091a6d68fa57c527fe86e921dad687661ef2690b99514f691c071e678cdae44c6e
+  data.tar.gz: 075277ab39f967c205400d8a12ca808e81a67df3b375bdd5d63ce45cdc8762e1f8ddb0fa52df57290aa823b4bab35ad809c5869892738a6ad39a17561e882bc2

data/Gemfile

@@ -0,0 +1,14 @@
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem 'pry', '~> 0.9.0'
+  gem 'pry-nav'
+  gem 'rake'
+end
+
+group :test do
+  gem 'rspec'
+  gem 'rr'
+end

data/History.txt

@@ -0,0 +1,3 @@
+== 1.0.0
+
+* Birthday!

data/README.md

@@ -0,0 +1,115 @@
+yaml-write-stream
+=================
+
+[![Build Status](https://travis-ci.org/camertron/yaml-write-stream.svg?branch=master)](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
+```
+
+## 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

data/Rakefile

@@ -0,0 +1,18 @@
+# encoding: UTF-8
+
+require 'rubygems' unless ENV['NO_RUBYGEMS']
+
+require 'bundler'
+require 'rspec/core/rake_task'
+require 'rubygems/package_task'
+
+require './lib/yaml-write-stream'
+
+Bundler::GemHelper.install_tasks
+
+task :default => :spec
+
+desc 'Run specs'
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = './spec/**/*_spec.rb'
+end

data/lib/yaml-write-stream/stateful.rb

@@ -0,0 +1,183 @@
+# encoding: UTF-8
+
+class YamlWriteStream
+  class NotInMapError < StandardError; end
+  class NotInSequenceError < StandardError; end
+  class EndOfStreamError < StandardError; end
+
+  class StatefulWriter
+    attr_reader :emitter, :stream, :stack, :closed, :first
+    alias :closed? :closed
+
+    def initialize(emitter, stream)
+      @emitter = emitter
+      @stream = stream
+      @stack = []
+      @closed = false
+      after_initialize
+      @first = true
+    end
+
+    def after_initialize
+      @first = true
+    end
+
+    def close
+      # psych gets confused if you open a file and don't at least
+      # pretend to write something
+      write_scalar('') if first
+
+      until stack.empty?
+        if in_map?
+          close_map
+        else
+          close_sequence
+        end
+      end
+
+      emitter.end_document(true)
+      emitter.end_stream
+      stream.close
+      @closed = true
+      nil
+    end
+
+    def write_map(*args)
+      check_eos
+      @first = false
+      current.write_map(*args) if current
+      stack.push(StatefulMappingWriter.new(emitter, stream))
+    end
+
+    def write_sequence(*args)
+      check_eos
+      @first = false
+      current.write_sequence(*args) if current
+      stack.push(StatefulSequenceWriter.new(emitter, stream))
+    end
+
+    def write_key_value(*args)
+      check_eos
+      @first = false
+      current.write_key_value(*args)
+    end
+
+    def write_element(*args)
+      check_eos
+      @first = false
+      current.write_element(*args)
+    end
+
+    def eos?
+      closed? || (!first && stack.size == 0)
+    end
+
+    def in_map?
+      current ? current.is_map? : false
+    end
+
+    def in_sequence?
+      current ? current.is_sequence? : false
+    end
+
+    def close_map
+      if in_map?
+        stack.pop.close
+      else
+        raise NotInMapError, 'not currently writing a map.'
+      end
+    end
+
+    def close_sequence
+      if in_sequence?
+        stack.pop.close
+      else
+        raise NotInSequenceError, 'not currently writing an sequence.'
+      end
+    end
+
+    protected
+
+    def check_eos
+      if eos?
+        raise EndOfStreamError, 'end of stream.'
+      end
+    end
+
+    def current
+      stack.last
+    end
+
+    def write_scalar(value)
+        # value, anchor, tag, plain, quoted, style
+      emitter.scalar(
+        value, nil, nil, true, false, Psych::Nodes::Scalar::ANY
+      )
+    end
+  end
+
+  class StatefulMappingWriter < StatefulWriter
+    def after_initialize
+      # anchor, tag, implicit, style
+      emitter.start_mapping(
+        nil, nil, true, Psych::Nodes::Sequence::BLOCK
+      )
+    end
+
+    def write_map(key)
+      write_scalar(key)
+    end
+
+    def write_sequence(key)
+      write_scalar(key)
+    end
+
+    def write_key_value(key, value)
+      write_scalar(key)
+      write_scalar(value)
+    end
+
+    def close
+      emitter.end_mapping
+    end
+
+    def is_map?
+      true
+    end
+
+    def is_sequence?
+      false
+    end
+  end
+
+  class StatefulSequenceWriter < StatefulWriter
+    def after_initialize
+      # anchor, tag, implicit, style
+      emitter.start_sequence(
+        nil, nil, true, Psych::Nodes::Sequence::BLOCK
+      )
+    end
+
+    def write_element(element)
+      write_scalar(element)
+    end
+
+    def write_map
+    end
+
+    def write_sequence
+    end
+
+    def close
+      emitter.end_sequence
+    end
+
+    def is_map?
+      false
+    end
+
+    def is_sequence?
+      true
+    end
+  end
+end

data/lib/yaml-write-stream/version.rb

@@ -0,0 +1,5 @@
+# encoding: UTF-8
+
+class YamlWriteStream
+  VERSION = "1.0.0"
+end

data/lib/yaml-write-stream/yielding.rb

@@ -0,0 +1,81 @@
+# encoding: UTF-8
+
+class YamlWriteStream
+  class YieldingWriter
+    attr_reader :emitter, :stream, :first
+
+    def initialize(emitter, stream)
+      @emitter = emitter
+      @stream = stream
+      @first = true
+    end
+
+    def close
+      # psych gets confused if you open a file and don't at least
+      # pretend to write something
+      write_scalar('') if first
+      emitter.end_document(true)
+      emitter.end_stream
+      stream.close
+    end
+
+    def write_sequence
+      @first = false
+
+      # anchor, tag, implicit, style
+      emitter.start_sequence(
+        nil, nil, true, Psych::Nodes::Sequence::ANY
+      )
+
+      yield YieldingSequenceWriter.new(emitter, stream)
+      emitter.end_sequence
+    end
+
+    def write_map
+      @first = false
+
+      # anchor, tag, implicit, style
+      emitter.start_mapping(
+        nil, nil, true, Psych::Nodes::Sequence::ANY
+      )
+
+      yield YieldingMappingWriter.new(emitter, stream)
+      emitter.end_mapping
+    end
+
+    protected
+
+    def write_scalar(value)
+      @first = false
+
+        # value, anchor, tag, plain, quoted, style
+      emitter.scalar(
+        value, nil, nil, true, false, Psych::Nodes::Scalar::ANY
+      )
+    end
+  end
+
+  class YieldingMappingWriter < YieldingWriter
+    def write_map(key)
+      write_scalar(key)
+      super()
+    end
+
+    def write_sequence(key)
+      write_scalar(key)
+      super()
+    end
+
+    def write_key_value(key, value)
+      @first = false
+      write_scalar(key)
+      write_scalar(value)
+    end
+  end
+
+  class YieldingSequenceWriter < YieldingWriter
+    def write_element(element)
+      write_scalar(element)
+    end
+  end
+end

data/lib/yaml-write-stream.rb

@@ -0,0 +1,54 @@
+# encoding: UTF-8
+
+require 'psych'
+require 'yaml-write-stream/yielding'
+require 'yaml-write-stream/stateful'
+
+class YamlWriteStream
+  class << self
+    def open(path, encoding = Psych::Parser::UTF8, &block)
+      handle = ::File.open(path, 'w')
+      from_stream(handle, encoding, &block)
+    end
+
+    def from_stream(stream, encoding = Psych::Parser::UTF8)
+      emitter = Psych::Emitter.new(stream)
+      emitter.start_stream(convert_encoding(encoding))
+
+      # version, tag_directives, implicit
+      emitter.start_document([], [], true)
+
+      if block_given?
+        yield writer = YieldingWriter.new(emitter, stream)
+        writer.close
+        nil
+      else
+        StatefulWriter.new(emitter, stream)
+      end
+    end
+
+    private
+
+    def convert_encoding(encoding)
+      case encoding
+        when Encoding
+          case encoding
+            when Encoding::UTF_8
+              Psych::Parser::UTF8
+            when Encoding::UTF_16BE
+              Psych::Parser::UTF16BE
+            when Encoding::UTF_16LE
+              Psych::Parser::UTF16LE
+            else
+              raise ArgumentError, "'#{encoding}' encoding is not supported by Psych."
+          end
+        when Fixnum
+          encoding
+        when String
+          convert_encoding(Encoding.find(encoding))
+        else
+          raise ArgumentError, "encoding of type #{encoding.class} is not supported, please provide an Encoding or a Fixnum."
+      end
+    end
+  end
+end

data/spec/shared_examples.rb

@@ -0,0 +1,30 @@
+# encoding: UTF-8
+
+shared_examples 'a yaml stream' do
+  it 'handles a simple array' do
+    check_roundtrip(['abc'])
+  end
+
+  it 'handles a simple object' do
+    check_roundtrip({ 'foo' => 'bar' })
+  end
+
+  it 'handles one level of array nesting' do
+    check_roundtrip([['def'],'abc'])
+    check_roundtrip(['abc',['def']])
+  end
+
+  it 'handles one level of object nesting' do
+    check_roundtrip({ 'foo' => { 'bar' => 'baz' } })
+  end
+
+  it 'handles one level of mixed nesting' do
+    check_roundtrip({ 'foo' => ['bar', 'baz'] })
+    check_roundtrip([{ 'foo' => 'bar' }])
+  end
+
+  it 'handles multiple levels of mixed nesting' do
+    check_roundtrip({'foo' => ['bar', { 'baz' => 'moo', 'gaz' => ['doo'] }, 'kal'], 'jim' => ['jill', ['john']] })
+    check_roundtrip(['foo', { 'bar' => 'baz', 'moo' => ['gaz', ['jim', ['jill']], 'jam'] }])
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,173 @@
+# encoding: UTF-8
+
+require 'rspec'
+require 'yaml-write-stream'
+require 'shared_examples'
+require 'pry-nav'
+
+RSpec.configure do |config|
+  config.mock_with :rr
+end
+
+class RoundtripChecker
+  class << self
+    include RSpec::Matchers
+
+    def check_roundtrip(obj)
+      stream = StringIO.new
+      writer = create_writer(stream)
+      serialize(obj, writer)
+      writer.close
+      new_obj = Psych.load(stream.string)
+      compare(obj, new_obj)
+    end
+
+    protected
+
+    def create_emitter(stream)
+      Psych::Emitter.new(stream).tap do |emitter|
+        emitter.start_stream(Psych::Parser::UTF8)
+        emitter.start_document([], [], true)
+      end
+    end
+
+    private
+
+    def compare(old_obj, new_obj)
+      expect(old_obj.class).to equal(new_obj.class)
+
+      case old_obj
+        when Hash
+          expect(old_obj.keys).to eq(new_obj.keys)
+
+          old_obj.each_pair do |key, old_val|
+            compare(old_val, new_obj[key])
+          end
+        when Array
+          old_obj.each_with_index do |old_element, idx|
+            compare(old_element, new_obj[idx])
+          end
+        else
+          expect(old_obj).to eq(new_obj)
+      end
+    end
+  end
+end
+
+class YieldingRoundtripChecker < RoundtripChecker
+  class << self
+    def create_writer(stream)
+      YamlWriteStream::YieldingWriter.new(
+        create_emitter(stream), stream
+      )
+    end
+
+    protected
+
+    def serialize(obj, writer)
+      case obj
+        when Hash
+          writer.write_map do |map_writer|
+            serialize_map(obj, map_writer)
+          end
+        when Array
+          writer.write_sequence do |sequence_writer|
+            serialize_sequence(obj, sequence_writer)
+          end
+      end
+    end
+
+    def serialize_map(obj, writer)
+      obj.each_pair do |key, val|
+        case val
+          when Hash
+            writer.write_map(key) do |map_writer|
+              serialize_map(val, map_writer)
+            end
+          when Array
+            writer.write_sequence(key) do |sequence_writer|
+              serialize_sequence(val, sequence_writer)
+            end
+          else
+            writer.write_key_value(key, val)
+        end
+      end
+    end
+
+    def serialize_sequence(obj, writer)
+      obj.each do |element|
+        case element
+          when Hash
+            writer.write_map do |map_writer|
+              serialize_map(element, map_writer)
+            end
+          when Array
+            writer.write_sequence do |sequence_writer|
+              serialize_sequence(element, sequence_writer)
+            end
+          else
+            writer.write_element(element)
+        end
+      end
+    end
+  end
+end
+
+class StatefulRoundtripChecker < RoundtripChecker
+  class << self
+    def create_writer(stream)
+      YamlWriteStream::StatefulWriter.new(
+        create_emitter(stream), stream
+      )
+    end
+
+    protected
+
+    def serialize(obj, writer)
+      case obj
+        when Hash
+          writer.write_map
+          serialize_map(obj, writer)
+          writer.close_map
+        when Array
+          writer.write_sequence
+          serialize_sequence(obj, writer)
+          writer.close_sequence
+      end
+    end
+
+    def serialize_map(obj, writer)
+      obj.each_pair do |key, val|
+        case val
+          when Hash
+            writer.write_map(key)
+            serialize_map(val, writer)
+            writer.close_map
+          when Array
+            writer.write_sequence(key)
+            serialize_sequence(val, writer)
+            writer.close_sequence
+          else
+            writer.write_key_value(key, val)
+        end
+      end
+    end
+
+    def serialize_sequence(obj, writer)
+      obj.each do |element|
+        case element
+          when Hash
+            writer.write_map
+            serialize_map(element, writer)
+            writer.close_map
+          when Array
+            writer.write_sequence
+            serialize_sequence(element, writer)
+            writer.close_sequence
+          else
+            writer.write_element(element)
+        end
+      end
+    end
+  end
+end

data/spec/stateful_spec.rb

@@ -0,0 +1,142 @@
+# encoding: UTF-8
+
+require 'spec_helper'
+
+describe YamlWriteStream::YieldingWriter do
+  let(:stream) do
+    StringIO.new.tap do |io|
+      io.set_encoding(Encoding::UTF_8)
+    end
+  end
+
+  let(:stream_writer) do
+    StatefulRoundtripChecker.create_writer(stream)
+  end
+
+  def check_roundtrip(obj)
+    StatefulRoundtripChecker.check_roundtrip(obj)
+  end
+
+  def utf8(str)
+    str.encode(Encoding::UTF_8)
+  end
+
+  it_behaves_like 'a yaml stream'
+
+  describe '#close' do
+    it 'unwinds the stack, adds appropriate closing punctuation for each unclosed item, and closes the stream' do
+      stream_writer.write_sequence
+      stream_writer.write_element('abc')
+      stream_writer.write_map
+      stream_writer.write_key_value('def', 'ghi')
+      stream_writer.close
+
+      expect(stream.string).to eq(utf8("- abc\n- def: ghi\n"))
+      expect(stream_writer).to be_closed
+      expect(stream).to be_closed
+    end
+  end
+
+  describe '#closed?' do
+    it 'returns false if the stream is still open' do
+      expect(stream_writer).to_not be_closed
+    end
+
+    it 'returns true if the stream is closed' do
+      stream_writer.close
+      expect(stream_writer).to be_closed
+    end
+  end
+
+  describe '#in_map?' do
+    it 'returns true if the writer is currently writing a map' do
+      stream_writer.write_map
+      expect(stream_writer).to be_in_map
+    end
+
+    it 'returns false if the writer is not currently writing a map' do
+      expect(stream_writer).to_not be_in_map
+      stream_writer.write_sequence
+      expect(stream_writer).to_not be_in_map
+    end
+  end
+
+  describe '#in_sequence?' do
+    it 'returns true if the writer is currently writing a sequence' do
+      stream_writer.write_sequence
+      expect(stream_writer).to be_in_sequence
+    end
+
+    it 'returns false if the writer is not currently writing a sequence' do
+      expect(stream_writer).to_not be_in_sequence
+      stream_writer.write_map
+      expect(stream_writer).to_not be_in_sequence
+    end
+  end
+
+  describe '#eos?' do
+    it 'returns false if nothing has been written yet' do
+      expect(stream_writer).to_not be_eos
+    end
+
+    it 'returns false if the writer is in the middle of writing' do
+      stream_writer.write_map
+      expect(stream_writer).to_not be_eos
+    end
+
+    it "returns true if the writer has finished it's top-level" do
+      stream_writer.write_map
+      stream_writer.close_map
+      expect(stream_writer).to be_eos
+    end
+
+    it 'returns true if the writer is closed' do
+      stream_writer.close
+      expect(stream_writer).to be_eos
+    end
+  end
+
+  describe '#close_map' do
+    it 'raises an error if a map is not currently being written' do
+      stream_writer.write_sequence
+      expect(lambda { stream_writer.close_map }).to raise_error(YamlWriteStream::NotInMapError)
+    end
+  end
+
+  describe '#close_sequence' do
+    it 'raises an error if a sequence is not currently being written' do
+      stream_writer.write_map
+      expect(lambda { stream_writer.close_sequence }).to raise_error(YamlWriteStream::NotInSequenceError)
+    end
+  end
+
+  context 'with a closed stream writer' do
+    before(:each) do
+      stream_writer.close
+    end
+
+    describe '#write_map' do
+      it 'raises an error if eos' do
+        expect(lambda { stream_writer.write_map }).to raise_error(YamlWriteStream::EndOfStreamError)
+      end
+    end
+
+    describe '#write_sequence' do
+      it 'raises an error if eos' do
+        expect(lambda { stream_writer.write_map }).to raise_error(YamlWriteStream::EndOfStreamError)
+      end
+    end
+
+    describe '#write_key_value' do
+      it 'raises an error if eos' do
+        expect(lambda { stream_writer.write_key_value('abc', 'def') }).to raise_error(YamlWriteStream::EndOfStreamError)
+      end
+    end
+
+    describe '#write_element' do
+      it 'raises an error if eos' do
+        expect(lambda { stream_writer.write_element('foo') }).to raise_error(YamlWriteStream::EndOfStreamError)
+      end
+    end
+  end
+end

data/spec/yaml-write-stream_spec.rb

@@ -0,0 +1,146 @@
+# encoding: UTF-8
+
+require 'spec_helper'
+require 'tempfile'
+
+describe YamlWriteStream do
+  let(:yielding_writer) { YamlWriteStream::YieldingWriter }
+  let(:stateful_writer) { YamlWriteStream::StatefulWriter }
+  let(:stream_writer) { YamlWriteStream }
+  let(:tempfile) { Tempfile.new('temp') }
+  let(:stream) { StringIO.new }
+
+  def encodings_match?(outputs)
+    flattened = flatten_encodings(outputs)
+    flattened.uniq.size == flattened.size
+  end
+
+  def flatten_encodings(outputs)
+    outputs.map do |encoding, value|
+      bom = case encoding
+        when Encoding::UTF_16LE, Encoding::UTF_16BE
+          [239, 187, 191]
+        else
+          []
+      end
+
+      bom + value
+        .force_encoding(encoding)
+        .encode(Encoding::UTF_8)
+        .bytes
+        .to_a
+    end
+  end
+
+  describe '#from_stream' do
+    it 'yields a yielding stream if given a block' do
+      stream_writer.from_stream(stream) do |writer|
+        expect(writer).to be_a(yielding_writer)
+        expect(writer.stream).to equal(stream)
+      end
+    end
+
+    it 'returns a stateful writer if not given a block' do
+      writer = stream_writer.from_stream(stream)
+      expect(writer).to be_a(stateful_writer)
+      expect(writer.stream).to equal(stream)
+    end
+
+    [Encoding::UTF_8, Encoding::UTF_16LE, Encoding::UTF_16BE].each do |encoding|
+      it "supports specifying a #{encoding.name} encoding" do
+        stream_writer.from_stream(stream, encoding) do |writer|
+          writer.write_map do |map_writer|
+            map_writer.write_key_value('foo', 'bar')
+          end
+        end
+
+        expect(
+          encodings_match?({
+            encoding => stream.string,
+            Encoding::UTF_8 => "foo: bar\n"
+          })
+        ).to eq(true)
+      end
+    end
+
+    it "doesn't support other encodings" do
+      expect(
+        lambda do
+          stream_writer.from_stream(stream, Encoding::US_ASCII)
+        end
+      ).to raise_error(ArgumentError)
+    end
+
+    it 'interprets string encoding names' do
+      stream_writer.from_stream(stream, 'UTF-16BE') do |writer|
+        writer.write_map do |map_writer|
+          map_writer.write_key_value('foo', 'bar')
+        end
+      end
+
+      expect(
+        encodings_match?({
+          Encoding::UTF_16BE => stream.string,
+          Encoding::UTF_8 => "foo: bar\n"
+        })
+      )
+    end
+
+    it 'interprets Psych integer encodings' do
+      stream_writer.from_stream(stream, Psych::Parser::UTF16BE) do |writer|
+        writer.write_map do |map_writer|
+          map_writer.write_key_value('foo', 'bar')
+        end
+      end
+
+      expect(
+        encodings_match?({
+          Encoding::UTF_16BE => stream.string,
+          Encoding::UTF_8 => "foo: bar\n"
+        })
+      )
+    end
+
+    it 'raises an error if an unrecognized type of object is given as encoding' do
+      expect(
+        lambda do
+          stream_writer.from_stream(stream, Object.new)
+        end
+      ).to raise_error(ArgumentError)
+    end
+  end
+
+  describe '#open' do
+    it 'opens a file and yields a yielding stream if given a block' do
+      mock.proxy(File).open(tempfile, 'w')
+      stream_writer.open(tempfile) do |writer|
+        expect(writer).to be_a(yielding_writer)
+        expect(writer.stream.path).to eq(tempfile.path)
+      end
+    end
+
+    it 'opens a file and returns a stateful writer if not given a block' do
+      mock.proxy(File).open(tempfile, 'w')
+      writer = stream_writer.open(tempfile)
+      expect(writer).to be_a(stateful_writer)
+      expect(writer.stream.path).to eq(tempfile.path)
+    end
+
+    [Encoding::UTF_8, Encoding::UTF_16LE, Encoding::UTF_16BE].each do |encoding|
+      it "supports specifying a #{encoding.name} encoding" do
+        stream_writer.open(tempfile, encoding) do |writer|
+          writer.write_map do |map_writer|
+            map_writer.write_key_value('foo', 'bar')
+          end
+        end
+
+        expect(
+          encodings_match?({
+            encoding => stream.string,
+            Encoding::UTF_8 => "foo: bar\n"
+          })
+        ).to eq(true)
+      end
+    end
+  end
+end

data/spec/yielding_spec.rb

@@ -0,0 +1,32 @@
+# encoding: UTF-8
+
+require 'spec_helper'
+
+describe YamlWriteStream::YieldingWriter do
+  let(:stream) do
+    StringIO.new.tap do |io|
+      io.set_encoding(Encoding::UTF_8)
+    end
+  end
+
+  let(:stream_writer) do
+    YieldingRoundtripChecker.create_writer(stream)
+  end
+
+  def check_roundtrip(obj)
+    YieldingRoundtripChecker.check_roundtrip(obj)
+  end
+
+  def utf8(str)
+    str.encode(Encoding::UTF_8)
+  end
+
+  it_behaves_like 'a yaml stream'
+
+  describe '#close' do
+    it 'closes the underlying stream' do
+      stream_writer.close
+      expect(stream).to be_closed
+    end
+  end
+end

data/yaml-write-stream.gemspec

@@ -0,0 +1,18 @@
+$:.unshift File.join(File.dirname(__FILE__), 'lib')
+require 'yaml-write-stream/version'
+
+Gem::Specification.new do |s|
+  s.name     = "yaml-write-stream"
+  s.version  = ::YamlWriteStream::VERSION
+  s.authors  = ["Cameron Dutro"]
+  s.email    = ["camertron@gmail.com"]
+  s.homepage = "http://github.com/camertron"
+
+  s.description = s.summary = "An easy, streaming way to generate YAML."
+
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+
+  s.require_path = 'lib'
+  s.files = Dir["{lib,spec}/**/*", "Gemfile", "History.txt", "README.md", "Rakefile", "yaml-write-stream.gemspec"]
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: yaml-write-stream
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Cameron Dutro
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-09-26 00:00:00.000000000 Z
+dependencies: []
+description: An easy, streaming way to generate YAML.
+email:
+- camertron@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/yaml-write-stream/stateful.rb
+- lib/yaml-write-stream/version.rb
+- lib/yaml-write-stream/yielding.rb
+- lib/yaml-write-stream.rb
+- spec/shared_examples.rb
+- spec/spec_helper.rb
+- spec/stateful_spec.rb
+- spec/yaml-write-stream_spec.rb
+- spec/yielding_spec.rb
+- Gemfile
+- History.txt
+- README.md
+- Rakefile
+- yaml-write-stream.gemspec
+homepage: http://github.com/camertron
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14
+signing_key: 
+specification_version: 4
+summary: An easy, streaming way to generate YAML.
+test_files: []