xml-write-stream

Build Status

An easy, streaming way to generate XML.

Installation

gem install xml-write-stream

Usage

require 'xml-write-stream'

Examples for the Impatient

There are two types of XML write stream: one that uses blocks and yield to write tags, and one that's purely stateful. Here are two examples that produce the same output:

Yielding:

stream = StringIO.new
XmlWriteStream.from_stream(stream) do |writer|
  writer.open_tag('foo', bar: 'baz') do |foo_writer|
    foo_writer.open_tag('no-text')
    foo_writer.write_text('blarg')
  end
end

Stateful:

stream = StringIO.new
writer = XmlWriteStream.from_stream(stream)
writer.open_tag('foo', bar: 'baz')
writer.open_tag('no-text')
writer.close_tag
writer.write_text('blarg')
writer.close  # automatically adds closing tags for all unclosed tags

Output:

stream.string # => <foo bar="baz"><no-text/>blarg</foo>

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 = XmlWriteStream.from_stream(stream)
writer.open_tag('foo')

writer.eos?             # => false, the stream is open and the outermost tag hasn't been closed yet

writer.open_tag         # explicitly close the current tag
writer.eos?             # => true, the outermost tag has been closed

writer.open_tag('foo')  # => raises XmlWriteStream::EndOfStreamError

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

XmlWriteStream also supports streaming to a file via the open method:

Yielding:

XmlWriteStream.open('path/to/file.xml') do |writer|
  writer.open_tag('foo') do |foo_writer|
    ...
  end
end

Stateful:

writer = XmlWriteStream.open('path/to/file.xml')
writer.open_tag('foo')
...
writer.close

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