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

sofu documentation Contained in the sofu distribution.

Index

Code Index:

NAME

Top

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

DESCRIPTION

Top

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

Synopsis

Top

	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

Top

This Module is pure OO, exports nothing

Binary Drivers

Top

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

Top

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

First driver to support: Data::Sofu::Binary::Bin0200

Perl datastructure to pack. Can be a hash, array or scalar (or array of hashes of hashes of arrays or whatever). Anything NOT a hash will be converted to TREE={Value=>TREE};

It can also be a Data::Sofu::Object or derived (Data::Sofu::Map, Data::Sofu::List, Data::Sofu::Value, Data::Sofu::...). Anything not a Data::Sofu::Map will be converted to one (A Map with one attribute called "Value" that holds TREE).

COMMENTS

First driver to support: Data::Sofu::Binary::Bin0200

Comment hash (as returned by Data::Sofu::getSofucomments() or Data::Sofu->new()->comments() after any file was read).

Can be undef or {}.

ENCODING

First driver to support: Data::Sofu::Binary::Bin0200

Specifies the encoding of the strings in the binary sofu file, which can be:

"0" or "UTF-8"

First driver to support: Data::Sofu::Binary::Bin0200

This is default.

Normal UTF-8 encoding (supports almost all chars)

"1" or "UTF-7"

First driver to support: Data::Sofu::Binary::Bin0200

This is default for byteorder = 7Bit (See below)

7Bit encoding (if your transport stream isn't 8-Bit safe

"2" or "UTF-16"

First driver to support: Data::Sofu::Binary::Bin0200

UTF 16 with byte order mark in EVERY string.

Byteoder depends on your machine

"3" or "UTF-16BE"

First driver to support: Data::Sofu::Binary::Bin0200

No BOM, always BigEndian

"4" or "UTF-16LE"

First driver to support: Data::Sofu::Binary::Bin0200

No BOM, always LittleEndian

"5" or "UTF-32"

First driver to support: Data::Sofu::Binary::Bin0200

UTF-32 with byte order mark in EVERY string.

Byteoder depends on your machine

"6" or "UTF-32BE"

First driver to support: Data::Sofu::Binary::Bin0200

No BOM, always BigEndian

"7" or "UTF-32LE"

First driver to support: Data::Sofu::Binary::Bin0200

No BOM, always LittleEndian

"8","9"

Reserved for future use

"10" or "ascii"

First driver to support: Data::Sofu::Binary::Bin0200

Normal ASCII encoding

Might not support all characters and will warn about that.

"11" or "cp1252"

First driver to support: Data::Sofu::Binary::Bin0200

Windows Codepage 1252

Might not support all characters and will warn about that.

"12" or "latin1"

First driver to support: Data::Sofu::Binary::Bin0200

ISO Latin 1

Might not support all characters and will warn about that.

"13" or "latin9"

First driver to support: Data::Sofu::Binary::Bin0200

ISO Latin 9

Might not support all characters and will warn about that.

"14" or "latin10"

First driver to support: Data::Sofu::Binary::Bin0200

ISO Latin 10

Might not support all characters and will warn about that.

BYTEORDER

First driver to support: Data::Sofu::Binary::Bin0200

Defines how the integers of the binary file are encoded.

undef

First driver to support: Data::Sofu::Binary::Bin0200

Maschine order

This is Default.

BOM is placed to detect the order used.

"LE"

First driver to support: Data::Sofu::Binary::Bin0200

Little Endian

BOM is placed to detect the order used.

Use this to give it to machines which are using Little Endian and have to read the file alot

"BE"

First driver to support: Data::Sofu::Binary::Bin0200

Big Endian

BOM is placed to detect the order used.

Use this to give it to machines which are using Big Endian and have to read the file alot

"7Bit"

First driver to support: Data::Sofu::Binary::Bin0200

Use this byteorder if you can't trust your transport stream to be 8-Bit save.

Encoding is forced to be UTF-7. No byte in the file will be > 127.

BOM is set to 00 00.

"NOFORCE7Bit"

First driver to support: Data::Sofu::Binary::Bin0200

Use this byteorder if you can't trust your transport stream to be 8-Bit save but you want another enconding than UTF-7

Encoding is NOT forced to be UTF-7.

BOM is set to 00 00.

SOFUMARK

First driver to support: Data::Sofu::Binary::Bin0200

Defines how often the string "Sofu" is placed in the file (to tell any user with a text-editor what type of file this one is).

undef

First driver to support: Data::Sofu::Binary::Bin0200

Only place one "Sofu" at the beginning of the file.

This is default.

"0" or ""

First driver to support: Data::Sofu::Binary::Bin0200

Place no string anywhere.

"1" or >1

First driver to support: Data::Sofu::Binary::Bin0200

Place a string on every place it is possible

Warning, the file might get big.

"0.000001" - "0.99999"

First driver to support: Data::Sofu::Binary::Bin0200

Place strings randomly.

NOTE:

Encoding, Byteorder and encoding driver (and Sofumark of course) are saved in the binary file. So you don't need to specify them for reading files, in fact just give them the Data::Sofu's readSofu() and all will be fine.

BUGS

Top

Data::Sofu::Object->writeBinary() will only use the Bin0200 driver, no other. 

	$map = new Data::Sofu::Map;
	.....
	$map->writeBinary($file); #Bin0200 driver always.
	use Data::Sofu;
	writeSofuBinary($file,$map); #Will use the latest driver.

SEE ALSO

Top

perl(1),http://sofu.sf.net

Data::Sofu::Object, Data::Sofu, Data::Sofu::Binary::Bin0200

sofu documentation Contained in the sofu distribution. 
###############################################################################
#Binary.pm
#Last Change: 2008-02-12
#Copyright (c) 2008 Marc-Seabstian "Maluku" Lucksch
#Version 0.29
####################
#This file is part of the sofu.pm project, a parser library for an all-purpose
#ASCII file format. More information can be found on the project web site
#at http://sofu.sourceforge.net/ .
#
#sofu.pm is published under the terms of the MIT license, which basically means
#"Do with it whatever you want". For more information, see the license.txt
#file that should be enclosed with libsofu distributions. A copy of the license
#is (at the time of this writing) also available at
#http://www.opensource.org/licenses/mit-license.php .
###############################################################################



package Data::Sofu::Binary;
use strict;
use warnings;

our $VERSION="0.29";
#We are really going to need these modules:
use Encode;
use Carp qw/confess/;
require Data::Sofu;


my %versions = (
	"000_002_000_000"=>"Data::Sofu::Binary::Bin0200"
);


sub new {
	my $class=shift;
	my $version = shift;
	$version = "000_002_000_000" unless $version;
	$version = $versions{$version};
	$version = "0200.pm" unless $version;
	eval "require $version";
	confess $@ if $@;
	return $version->new();
}



sub warn {
	my $self=shift;
	#croak "Sofu Warning, Binary decoder: @_";
	confess "Sofu Warning, Binary mode: @_ at offset $self->{OFFSET}";
}



sub die {
	my $self=shift;
	confess "Sofu Error, Binary mode: @_ at offset $self->{OFFSET}";
}


sub open { #Opens the data;
	local $_;
	my $self=shift;
	my $data=shift;
	$self->{OFFSET}=0;
	if (ref $data eq "GLOB") {
		binmode $data;
		$self->{IN} = $data;
	}
	elsif (ref $data eq "SCALAR") {
		CORE::open my $in, '<:utf8', $data;
		binmode $in;
		$self->{IN}=$in;	
	}
	elsif (ref $data) {
		$self->warn("Unsupported Data Input Method:",ref $data);
	}
	else {
		CORE::open (my $in,'<:raw',$data) or $self->die("Can't open input file $data: $!");
		binmode $in;
		$self->{IN}=$in;
	}
}


sub openout { #Opens the data;
	local $_;
	my $self=shift;
	my $data=shift;
	$self->{OFFSET}=0;
	if (ref $data eq "GLOB") {
		binmode $data;
		$self->{OUT} = $data;
	}
	elsif (ref $data eq "SCALAR") {
		CORE::open my $out, '>:utf8', $data;
		binmode $out;
		$self->{OUT}=$out;	
	}
	elsif (ref $data) {
		$self->warn("Unsupported Data Input Method:",ref $data);
	}
	else {
		CORE::open (my $out,'>:raw',$data) or $self->die("Can't open output file $data: $!");
		binmode $out;
		$self->{OUT}=$out;
	}
}


sub get { #Reads some bytes..
	local $_;
	my $self=shift;
	my $in =$self->{IN};
	my $amount = shift;
	my $data;
	my $read = CORE::read($in,$data,$amount);
	$self->die("Error while reading: $!") unless defined $read;
	return undef unless $read;
	$self->{OFFSET}+=$read;
	$self->die("Can't read any more bytes, file corrupt?") if $read < $amount; 
	return $data;
}


sub unpackHeader {
	my $self=shift;
	my $end = $self->get(2);
	if ($end eq "So") {
		my $t = $self->get(2);
		$self->die("Incomplete Mark: $t") if $t ne "fu";
		$end = $self->get(2)
	}
	my $bom = unpack("S",$end);
	my $version = $self->get(4);
	$self->die("Can't read version, incomplete Header!") unless defined $version;
	my @v = unpack ("CCCC",$version);
	return ($bom,join("_",map {sprintf("%03d",$_)} @v));

}



sub read { #Perl Structure Parser
	local $_;	
	my $self=shift;
	$self->{COMMENTS}=[];
	$self->open(shift);
	my ($bom, $ver) = $self->unpackHeader();
	return $self->unpack($bom) if ($self->{SUPPORTED}->{$ver});
	my $module=$versions{$ver};
	$self->die("Unknown Version: $ver") unless $module;
	eval "require $module";
	confess $@ if $@;
	my $m = "$module"->new();
	return $m->unpack($bom);
	

}




sub load { #Object parser
	local $_;
	require Data::Sofu::Object;
	my $self=shift;
	$self->open(shift);
	my ($bom, $ver) = $self->unpackHeader();
	return $self->unpackObject($bom) if ($self->{SUPPORTED}->{$ver});
	my $module=$versions{$ver};
	$self->die("Unknown Version: $ver") unless $module;
	eval "require $module";
	confess $@ if $@;
	my $m = "$module"->new();
	return $m->unpackObject($bom);
}


sub write {
	local $_;
	my $self=shift;
	$self->openout(shift);
	my $fh=$self->{OUT};
	print $fh $self->pack(@_);

}


1;