NAME

RapidApp::StructuredIO::Writer

SYNOPSIS

  my $writer= Data::StructWriter(out => IO::File->new('> /tmp/foo'), format => json);
  $writer->write( "foo" );
  $writer->write( { a => 1, b => { b_a => 1, b_b => 2 } } );

DESCRIPTION

StructWriter writes structured data as a discrete sequence. The point is then to be able to read back that same sequence without the bother of breaking it back apart.

StructWriter is slightly better than calling Storable::store_fd in a loop because you can easily swap it out for a readable format without having to alter your reader to handle the format change. Another benefit is that the format used to encode the records is compatible with non-blocking I/O. (though to actually do that you need to make an instance of StructWriter::NonBlockAE or StructReader::NonBlockAE, which are implementations using AnyEvent)

StructWriter is also extremely extensible. Just add methods named "_serialize_$format" and they will be available. (But when you design new formats, be sure that you can decode them without a blocking library call...)

The default supported formats are "storable" and "json".

ATTRIBUTES

out

The file handle to which serialized data will be written

format

The format used for serialization. Default implementation supports 'storable' and 'json', with 'storable' as the default.

ATTRIBUTES

$format= $self->format( $format )

Gets or sets the format for the data stream. Valid built-in values are 'json' and 'storable'.

If the format is unsupported, you get an exception. You may set the format as many times as you like before you begin writing, but once the first record has been written, subsequent attempts will throw an exception.

$self->write( $data )

Writes a data structure into the stream. undef is a legal value, and will cause a reader to read undef.

The first time ->write is called, it will also write out a stream header identifying the format used.

SERIALIZE FUNCTIONS

This API is dead-simple. Take a ref to $self, and an arbitrary data structure (possibly undef) and return a scalar containing bytes (not unicode).

Name the method '_serialize_'.$format