<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Data::Sofu::Binary::Bin0200 - Driver for Sofu Binary version 0.2.0.0</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:" />
<link rel="stylesheet" type="text/css" href="/Data/sofupod.css" />
</head>
<body>
<!-- INDEX BEGIN -->
<div name="index">
<p><a name="__index__"></a></p>
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<li><a href="#synopsis">Synopsis</a></li>
<li><a href="#syntax">SYNTAX</a></li>
<li><a href="#methods">METHODS</a></li>
<ul>
<li><a href="#new__"><code>new()</code></a></li>
<li><a href="#encoding_id_">encoding(ID)</a></li>
<li><a href="#byteorder_bom_">byteorder(BOM)</a></li>
<li><a href="#bom_bom_">bom(BOM)</a></li>
<li><a href="#packshort_int_">packShort(INT)</a></li>
<li><a href="#packlong_int_">packLong(INT)</a></li>
<li><a href="#packendian__"><code>packendian()</code></a></li>
<li><a href="#packversion__"><code>packversion()</code></a></li>
<li><a href="#packencoding__"><code>packencoding()</code></a></li>
<li><a href="#gettype__"><code>getType()</code></a></li>
<li><a href="#objectprocess__"><code>objectprocess()</code></a></li>
<li><a href="#postprocess__"><code>postprocess()</code></a></li>
<li><a href="#getlong__"><code>getLong()</code></a></li>
<li><a href="#gettext__"><code>getText()</code></a></li>
<li><a href="#getcomment_tree_">getComment(TREE)</a></li>
<li><a href="#unpackundef_tree_">unpackUndef(TREE)</a></li>
<li><a href="#unpackscalar_tree_">unpackScalar(TREE)</a></li>
<li><a href="#unpackref_tree_">unpackRef(TREE)</a></li>
<li><a href="#unpackhash_tree_">unpackHash(TREE)</a></li>
<li><a href="#unpackhash_tree_">unpackHash(TREE)</a></li>
<li><a href="#unpacktype_type_tree_"><code>unpackType(TYPE,TREE)</code></a></li>
<li><a href="#unpack_bom_">unpack(BOM)</a></li>
<li><a href="#unpackundefined_tree_">unpackUndefined(TREE)</a></li>
<li><a href="#unpackvalue_tree_">unpackValue(TREE)</a></li>
<li><a href="#unpackreference_tree_">unpackReference(TREE)</a></li>
<li><a href="#unpackmap_tree_">unpackMap(TREE)</a></li>
<li><a href="#unpackmap2_tree_">unpackMap2(TREE)</a></li>
<li><a href="#unpacklist_tree_">unpackList(TREE)</a></li>
<li><a href="#unpacklist2_tree_">unpackList2(TREE)</a></li>
<li><a href="#unpackobjecttype_type_tree_"><code>unpackObjectType(TYPE,TREE)</code></a></li>
<li><a href="#unpack_bom_">unpack(BOM)</a></li>
<li><a href="#packtype_type_">packType(TYPE)</a></li>
<li><a href="#packtext_string_">packText(STRING)</a></li>
<li><a href="#packdata_data_tree_"><code>packData(DATA,TREE)</code></a></li>
<li><a href="#packarray_data_tree_"><code>packArray(DATA,TREE)</code></a></li>
<li><a href="#packarray_data_tree_"><code>packArray(DATA,TREE)</code></a></li>
<li><a href="#pack_tree__comments__encoding__byteorder__sofumark_____"><code>pack(TREE,[COMMENTS,[ENCODING,[BYTEORDER,[SOFUMARK]]]])</code></a></li>
<li><a href="#packobject_tree__comments__encoding__byteorder__sofumark_____"><code>packObject(TREE,[COMMENTS,[ENCODING,[BYTEORDER,[SOFUMARK]]]])</code></a></li>
<li><a href="#packdata_data_tree_"><code>packData(DATA,TREE)</code></a></li>
<li><a href="#packlist_data_tree_"><code>packList(DATA,TREE)</code></a></li>
<li><a href="#packmap_data_tree_"><code>packMap(DATA,TREE)</code></a></li>
<li><a href="#packcomment_tree_add_"><code>packComment(TREE,ADD)</code></a></li>
<li><a href="#packheader__encoding__byteorder__sofumark____"><code>packHeader([ENCODING,[BYTEORDER,[SOFUMARK]]])</code></a></li>
</ul>
<li><a href="#bugs">BUGS</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
</ul>
<hr name="index" />
</div>
<!-- INDEX END -->
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>Data::Sofu::Binary::Bin0200 - Driver for Sofu Binary version 0.2.0.0</p>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>Driver for <code>Data::Sofu::Binary</code> and <code>Data::Sofu</code></p>
<p>
</p>
<hr />
<h1><a name="synopsis">Synopsis</a></h1>
<p>See <code>Data::Sofu::Binary</code></p>
<p>
</p>
<hr />
<h1><a name="syntax">SYNTAX</a></h1>
<p>This Module is pure OO, exports nothing</p>
<p>
</p>
<hr />
<h1><a name="methods">METHODS</a></h1>
<p>See also <code>Data::Sofu::Binary</code> for public methods.</p>
<p>All these methods are INTERNAL, not for use outside of this module...</p>
<p>Except <code>pack()</code>.</p>
<p>
</p>
<h2><a name="new__"><code>new()</code></a></h2>
<p>Creates a new Binary Driver using DRIVER or the latest one available.</p>
<pre>
<span class="keyword">require</span> <span class="variable">Data::Sofu::Binary</span><span class="operator">;</span>
<span class="variable">$bsofu</span> <span class="operator">=</span> <span class="variable">Data::Sofu::Binary</span><span class="operator">-></span><span class="variable">new</span><span class="operator">(</span><span class="string">"000_002_000_000"</span><span class="operator">);</span> <span class="variable">Taking</span> <span class="variable">this</span> <span class="variable">driver</span><span class="operator">;</span>
<span class="comment">#You can call it directly:</span>
<span class="keyword">require</span> <span class="variable">Data::Sofu::Binary::Bin0200</span><span class="operator">;</span>
<span class="variable">$bsofu</span> <span class="operator">=</span> <span class="variable">Data::Sofu::Binary::Bin0200</span><span class="operator">-></span><span class="variable">new</span><span class="operator">();</span> <span class="comment">#The same</span>
</pre>
<p>
</p>
<h2><a name="encoding_id_">encoding(ID)</a></h2>
<p>Switches and/or detetect the encoding.</p>
<p>See <code>pack()</code> for more on encodings.</p>
<p>
</p>
<h2><a name="byteorder_bom_">byteorder(BOM)</a></h2>
<p>Internal method.</p>
<p>Switches the byteorder.</p>
<p>See <code>pack()</code> for more on byteorders.</p>
<p>
</p>
<h2><a name="bom_bom_">bom(BOM)</a></h2>
<p>Internal method.</p>
<p>Detects the byteorder.</p>
<p>See <code>pack()</code> for more on byteorders.</p>
<p>
</p>
<h2><a name="packshort_int_">packShort(INT)</a></h2>
<p>Packs one int-16 to binary using the set byteorder</p>
<p>
</p>
<h2><a name="packlong_int_">packLong(INT)</a></h2>
<p>Packs one int-32 to binary using the set byteorder</p>
<p>
</p>
<h2><a name="packendian__"><code>packendian()</code></a></h2>
<p>Returns the byte order mark for this file.</p>
<p>
</p>
<h2><a name="packversion__"><code>packversion()</code></a></h2>
<p>Returns the version of this driver to put in the file.</p>
<p>
</p>
<h2><a name="packencoding__"><code>packencoding()</code></a></h2>
<p>Returns the current encoding to put in the output file.</p>
<p>
</p>
<h2><a name="gettype__"><code>getType()</code></a></h2>
<p>Tries to find out what SofuObject to deserialise next</p>
<p>Returns:</p>
<p>0 for Undefined / undef</p>
<p>1 for Value / Scalar</p>
<p>2 for List / Array</p>
<p>3 for Map / Hash</p>
<p>4 for Reference / Ref</p>
<p>
</p>
<h2><a name="objectprocess__"><code>objectprocess()</code></a></h2>
<p>Postprocess the SofuObjects, sets References to their targets.</p>
<p>
</p>
<h2><a name="postprocess__"><code>postprocess()</code></a></h2>
<p>Postprocess perl datastructures , sets References to their targets.</p>
<p>
</p>
<h2><a name="getlong__"><code>getLong()</code></a></h2>
<p>Decodes one Int-32 from the input stream according to the byteorder and returns it.</p>
<p>
</p>
<h2><a name="gettext__"><code>getText()</code></a></h2>
<p>Decodes one String according to encoding from the inputstream and returns it</p>
<p>
</p>
<h2><a name="getcomment_tree_">getComment(TREE)</a></h2>
<p>decodes one comment and sets it to TREE</p>
<p>TREE can be a string describing the tree or a Data::Sofu::Object.</p>
<p>
</p>
<h2><a name="unpackundef_tree_">unpackUndef(TREE)</a></h2>
<p>Returns undef and packs it comment</p>
<p>
</p>
<h2><a name="unpackscalar_tree_">unpackScalar(TREE)</a></h2>
<p>Decodes one scalar and its comment.</p>
<p>
</p>
<h2><a name="unpackref_tree_">unpackRef(TREE)</a></h2>
<p>Decodes one ref and its comment.</p>
<p>
</p>
<h2><a name="unpackhash_tree_">unpackHash(TREE)</a></h2>
<p>Decodes a hash, its comment and its content</p>
<p>
</p>
<h2><a name="unpackhash_tree_">unpackHash(TREE)</a></h2>
<p>Decodes an array, its comment and its content</p>
<p>
</p>
<h2><a name="unpacktype_type_tree_"><code>unpackType(TYPE,TREE)</code></a></h2>
<p>Decodes a datastructure of TYPE.</p>
<p>
</p>
<h2><a name="unpack_bom_">unpack(BOM)</a></h2>
<p>Starts unpacking using BOM, gets encoding and the contents</p>
<p>
</p>
<h2><a name="unpackundefined_tree_">unpackUndefined(TREE)</a></h2>
<p>Unpacks a Data::Sofu::Undefined and its comment.</p>
<p>
</p>
<h2><a name="unpackvalue_tree_">unpackValue(TREE)</a></h2>
<p>Unpacks a Data::Sofu::Value, its content and its comment.</p>
<p>
</p>
<h2><a name="unpackreference_tree_">unpackReference(TREE)</a></h2>
<p>Unpacks a Data::Sofu::Reference, its content and its comment.</p>
<p>
</p>
<h2><a name="unpackmap_tree_">unpackMap(TREE)</a></h2>
<p>Unpacks a Data::Sofu::Map, its content and its comment.</p>
<p>
</p>
<h2><a name="unpackmap2_tree_">unpackMap2(TREE)</a></h2>
<p>Unpacks a Data::Sofu::Map, its content and its comment.</p>
<p>(Speed optimized, but uses dirty tricks)</p>
<p>
</p>
<h2><a name="unpacklist_tree_">unpackList(TREE)</a></h2>
<p>Unpacks a Data::Sofu::List, its content and its comment.</p>
<p>
</p>
<h2><a name="unpacklist2_tree_">unpackList2(TREE)</a></h2>
<p>Unpacks a Data::Sofu::List, its content and its comment.</p>
<p>(Speed optimized, but uses dirty tricks)</p>
<p>
</p>
<h2><a name="unpackobjecttype_type_tree_"><code>unpackObjectType(TYPE,TREE)</code></a></h2>
<p>Unpacks a datastructure defined by TYPE</p>
<p>
</p>
<h2><a name="unpack_bom_">unpack(BOM)</a></h2>
<p>Starts unpacking into a Data::Sofu::Object structure using BOM, gets encoding and the contents</p>
<p>
</p>
<h2><a name="packtype_type_">packType(TYPE)</a></h2>
<p>Encodes Type information and returns it.</p>
<p>
</p>
<h2><a name="packtext_string_">packText(STRING)</a></h2>
<p>Encodes a STRING using Encoding and returns it.</p>
<p>
</p>
<h2><a name="packdata_data_tree_"><code>packData(DATA,TREE)</code></a></h2>
<p>Encodes one perl datastructure and its contents and returns it.</p>
<p>
</p>
<h2><a name="packarray_data_tree_"><code>packArray(DATA,TREE)</code></a></h2>
<p>Encodes one perl array and its contents and returns it.</p>
<p>
</p>
<h2><a name="packarray_data_tree_"><code>packArray(DATA,TREE)</code></a></h2>
<p>Encodes one perl hash and its contents and returns it.</p>
<p>
</p>
<h2><a name="pack_tree__comments__encoding__byteorder__sofumark_____"><code>pack(TREE,[COMMENTS,[ENCODING,[BYTEORDER,[SOFUMARK]]]])</code></a></h2>
<p>Packs a structure (TREE) into a string using the Sofu binary file format.</p>
<p>Returns a string representing TREE.</p>
<dl>
<dt><strong><a name="tree" class="item">TREE</a></strong>
<dd>
<p>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};</p>
</dd>
<dd>
<p>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).</p>
</dd>
</li>
<dt><strong><a name="comments" class="item">COMMENTS</a></strong>
<dd>
<p>Comment hash (as returned by Data::Sofu::getSofucomments() or Data::Sofu->new()-><code>comments()</code> after any file was read).</p>
</dd>
<dd>
<p>Can be undef or {}.</p>
</dd>
</li>
<dt><strong><a name="encoding" class="item">ENCODING</a></strong>
<dd>
<p>Specifies the encoding of the strings in the binary sofu file, which can be:</p>
</dd>
<dl>
<dt><strong><a name="0_or_utf_8" class="item"><code>"0"</code> or <code>"UTF-8"</code></a></strong>
<dd>
<p>This is default.</p>
</dd>
<dd>
<p>Normal UTF-8 encoding (supports almost all chars)</p>
</dd>
</li>
<dt><strong><a name="1_or_utf_7" class="item"><code>"1"</code> or <code>"UTF-7"</code></a></strong>
<dd>
<p>This is default for byteorder = 7Bit (See below)</p>
</dd>
<dd>
<p>7Bit encoding (if your transport stream isn't 8-Bit safe</p>
</dd>
</li>
<dt><strong><a name="2_or_utf_16" class="item"><code>"2"</code> or <code>"UTF-16"</code></a></strong>
<dd>
<p>UTF 16 with byte order mark in EVERY string.</p>
</dd>
<dd>
<p>Byteoder depends on your machine</p>
</dd>
</li>
<dt><strong><a name="3_or_utf_16be" class="item"><code>"3"</code> or <code>"UTF-16BE"</code></a></strong>
<dd>
<p>No BOM, always BigEndian</p>
</dd>
</li>
<dt><strong><a name="4_or_utf_16le" class="item"><code>"4"</code> or <code>"UTF-16LE"</code></a></strong>
<dd>
<p>No BOM, always LittleEndian</p>
</dd>
</li>
<dt><strong><a name="5_or_utf_32" class="item"><code>"5"</code> or <code>"UTF-32"</code></a></strong>
<dd>
<p>UTF-32 with byte order mark in EVERY string.</p>
</dd>
<dd>
<p>Byteoder depends on your machine</p>
</dd>
</li>
<dt><strong><a name="6_or_utf_32be" class="item"><code>"6"</code> or <code>"UTF-32BE"</code></a></strong>
<dd>
<p>No BOM, always BigEndian</p>
</dd>
</li>
<dt><strong><a name="7_or_utf_32le" class="item"><code>"7"</code> or <code>"UTF-32LE"</code></a></strong>
<dd>
<p>No BOM, always LittleEndian</p>
</dd>
</li>
<dt><strong><a name="8_9" class="item"><code>"8","9"</code></a></strong>
<dd>
<p>Reserved for future use</p>
</dd>
</li>
<dt><strong><a name="10_or_ascii" class="item"><code>"10"</code> or <code>"ascii"</code></a></strong>
<dd>
<p>Normal ASCII encoding</p>
</dd>
<dd>
<p>Might not support all characters and will warn about that.</p>
</dd>
</li>
<dt><strong><a name="11_or_cp1252" class="item"><code>"11"</code> or <code>"cp1252"</code></a></strong>
<dd>
<p>Windows Codepage 1252</p>
</dd>
<dd>
<p>Might not support all characters and will warn about that.</p>
</dd>
</li>
<dt><strong><a name="12_or_latin1" class="item"><code>"12"</code> or <code>"latin1"</code></a></strong>
<dd>
<p>ISO Latin 1</p>
</dd>
<dd>
<p>Might not support all characters and will warn about that.</p>
</dd>
</li>
<dt><strong><a name="13_or_latin9" class="item"><code>"13"</code> or <code>"latin9"</code></a></strong>
<dd>
<p>ISO Latin 9</p>
</dd>
<dd>
<p>Might not support all characters and will warn about that.</p>
</dd>
</li>
<dt><strong><a name="14_or_latin10" class="item"><code>"14"</code> or <code>"latin10"</code></a></strong>
<dd>
<p>ISO Latin 10</p>
</dd>
<dd>
<p>Might not support all characters and will warn about that.</p>
</dd>
</li>
</dl>
<dt><strong><a name="byteorder" class="item">BYTEORDER</a></strong>
<dd>
<p>Defines how the integers of the binary file are encoded.</p>
</dd>
<dl>
<dt><strong><a name="undef" class="item"><code>undef</code></a></strong>
<dd>
<p>Maschine order</p>
</dd>
<dd>
<p>This is Default.</p>
</dd>
<dd>
<p>BOM is placed to detect the order used.</p>
</dd>
</li>
<dt><strong><a name="le" class="item"><code>"LE"</code></a></strong>
<dd>
<p>Little Endian</p>
</dd>
<dd>
<p>BOM is placed to detect the order used.</p>
</dd>
<dd>
<p>Use this to give it to machines which are using Little Endian and have to read the file alot</p>
</dd>
</li>
<dt><strong><a name="be" class="item"><code>"BE"</code></a></strong>
<dd>
<p>Big Endian</p>
</dd>
<dd>
<p>BOM is placed to detect the order used.</p>
</dd>
<dd>
<p>Use this to give it to machines which are using Big Endian and have to read the file alot</p>
</dd>
</li>
<dt><strong><a name="7bit" class="item"><code>"7Bit"</code></a></strong>
<dd>
<p>Use this byteorder if you can't trust your transport stream to be 8-Bit save.</p>
</dd>
<dd>
<p>Encoding is forced to be UTF-7. No byte in the file will be > 127.</p>
</dd>
<dd>
<p>BOM is set to 00 00.</p>
</dd>
</li>
<dt><strong><a name="noforce7bit" class="item"><code>"NOFORCE7Bit"</code></a></strong>
<dd>
<p>Use this byteorder if you can't trust your transport stream to be 8-Bit save but you want another enconding than UTF-7</p>
</dd>
<dd>
<p>Encoding is NOT forced to be UTF-7.</p>
</dd>
<dd>
<p>BOM is set to 00 00.</p>
</dd>
</li>
</dl>
<dt><strong><a name="sofumark" class="item">SOFUMARK</a></strong>
<dd>
<p>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).</p>
</dd>
<dl>
<dt><strong><code>undef</code></strong>
<dd>
<p>Only place one "Sofu" at the beginning of the file.</p>
</dd>
<dd>
<p>This is default.</p>
</dd>
</li>
<dt><strong><a name="0_or" class="item"><code>"0" or ""</code></a></strong>
<dd>
<p>Place no string anywhere.</p>
</dd>
</li>
<dt><strong><a name="1_or_1" class="item"><code>"1" or >1</code></a></strong>
<dd>
<p>Place a string on every place it is possible</p>
</dd>
<dd>
<p>Warning, the file might get big.</p>
</dd>
</li>
<dt><strong><a name="0_000001_0_99999" class="item"><code>"0.000001" - "0.99999"</code></a></strong>
<dd>
<p>Place strings randomly.</p>
</dd>
</li>
</dl>
</dl>
<p><strong>NOTE:</strong></p>
<p>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 <code>readSofu()</code> and all will be fine.</p>
<p>
</p>
<h2><a name="packobject_tree__comments__encoding__byteorder__sofumark_____"><code>packObject(TREE,[COMMENTS,[ENCODING,[BYTEORDER,[SOFUMARK]]]])</code></a></h2>
<p>Same as <code>pack()</code> but for <code>Data::Sofu::Object</code>'s only</p>
<p>Will be called by <code>pack()</code>.</p>
<p>Comments are taken from COMMENTS and from the Objects itself.</p>
<p>
</p>
<h2><a name="packdata_data_tree_"><code>packData(DATA,TREE)</code></a></h2>
<p>Encodes one Data::Sofu::Object and its contents and returns it.</p>
<p>
</p>
<h2><a name="packlist_data_tree_"><code>packList(DATA,TREE)</code></a></h2>
<p>Encodes one Data::Sofu::List and its contents and returns it.</p>
<p>
</p>
<h2><a name="packmap_data_tree_"><code>packMap(DATA,TREE)</code></a></h2>
<p>Encodes one Data::Sofu::Map and its contents and returns it.</p>
<p>
</p>
<h2><a name="packcomment_tree_add_"><code>packComment(TREE,ADD)</code></a></h2>
<p>Packs the comment for (TREE) + ADD and returns it.</p>
<p>
</p>
<h2><a name="packheader__encoding__byteorder__sofumark____"><code>packHeader([ENCODING,[BYTEORDER,[SOFUMARK]]])</code></a></h2>
<p>Packs the header of the file and sets encoding and byteorder</p>
<p>
</p>
<hr />
<h1><a name="bugs">BUGS</a></h1>
<p>n/c</p>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p><code>perl(1)</code>,<a href="http://sofu.sf.net">http://sofu.sf.net</a></p>
<p>Data::Sofu::Object, Data::Sofu, Data::Sofu::Binary::*</p>
</body>
</html>