NAME

Data::Sofu::Binary - Interface to various binary drivers

DESCRIPTION

This module can be used to convert complex data structures and SofuObject trees to binary files and streams.

Synopsis

        use Data::Sofu qw/readSofu writeSofuBinary/;
        my $tree = [%ENV];
        $tree->{Foo}=@INC;
        writeSofuBinary("env.sofu",$tree); #Write as a binary sofu file
        my $tree2=readSofu("env.sofu"); #Reading doesn't care if its binary or normal sofu.

        #Or using just this module:
        my $tree = [%ENV];
        $tree->{Foo}=@INC;
        require Data::Sofu::Binary;
        my $bsofu=Data::Sofu::Binary->new();
        my $bstream = $bsofu->pack($tree);
        my $tree2=$bsofu->read(\$tree); # This can only read binary data.

        #More detailed:
        writeSofuBinary("env.sofu",$tree,$comments,$encoding,$byteorder,$mark); #For details on these parameters see the pack() Method.

SYNTAX

This Module is pure OO, exports nothing

Binary Drivers

These are the known binary drivers (for now):

"000_002_000_000"

Data::Sofu::Binary::Bin0200

Sofu binary version 0.2.0.0 Driver.

Note

Data::Sofu's writeBinary will always take the latest stable one.

METHODS

These Methods are also avaiable for the returned binary driver.

Also see the Data::Sofu::Binary::Bin0200 or whatever driver you are using for more methods.

new([DRIVER])

Creates a new Binary Driver using DRIVER or the latest one available.

        require Data::Sofu::Binary;
        $bsofu = Data::Sofu::Binary->new(); #Using the latest.
        $bsofu = Data::Sofu::Binary->new("000_002_000_000"); Taking a specific one.
        #You can call it directly:
        require C<Data::Sofu::Binary::Bin0200>;
        $bsofu = C<Data::Sofu::Binary::Bin0200>->new(); #The same

warn()

Internal method, will throw an exception containing a stacktrace and the offset of the file where it happened.

die()

Internal method, will throw an exception containing a stacktrace and the offset of the file where it happened.

open(FILE)

A helper method to open files

File can be:

A filename, (the file will be opened in raw mode)

a filehandle, (will be set to binmode)

or a scalarref (data will be written to/form the referenced scalar

openout(FILE)

Same as open() for output.

get(AMOUNT)

Internal method, used to read AMOUNT bytes from the filestream.

unpackHeader()

Internal method, determines endianess and version the binary file was written in.

Returns ByteOrderMark and Sofu Version.

read(FILE)

Reads FILE in binary mode and returns a perl datastructure (Hashes, Arrays, Scalars)

See open() for info on the FILE parameter.

Loads automatically the right driver for FILE, no matter what driver is in use right now. But it will keep the current driver if it can read it.

Will not change the driver you are currently using!

load(FILE)

Reads FILE in binary mode and returns a Sofu datastructure (Data::Sofu::Object's, Maps, Lists and Values)

See open() for info on the FILE parameter.

Loads automatically the right driver for FILE, no matter what driver is in use right now. But it will keep the current driver if it can read it.

Will not change the driver you are currently using!

`write(FILE,TREE,[COMMENTS,[ENCODING,[BYTEORDER,[SOFUMARK,[...]]]]])`

Writes TREE to FILE.

See open() for FILE.

See pack() for COMMENTS,ENCODING,BYTEORDER,SOFUMARK,...

TREE can be a perl datastructure or a Data::Sofu::Object or derived.

`pack(TREE,[COMMENTS,[ENCODING,[BYTEORDER,[SOFUMARK,[...]]]]])`

This method is implemented only in the driver, but it is important to discuss the arguments here.

Note: These arguments are the ones used in drivers up to the default Data::Sofu::Binary::Bin0200. Later drivers might add more arguments (therefore ...), and earlier drivers might support fewer.

        print FH, $bsofu->pack(readSofu("something.sofu"),getSofucomments(),"UTF-32","LE","0.4");

TREE