<?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>lib/DataStore/CAS/FS/DirCodec/Universal.pm</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@localhost" />
</head>
<body style="background-color: white">
<!-- INDEX BEGIN -->
<div name="index">
<p><a name="__index__"></a></p>
<ul>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<ul>
<li><a href="#unicode">Unicode</a></li>
</ul>
<li><a href="#methods">METHODS</a></li>
<ul>
<li><a href="#encode">encode</a></li>
<li><a href="#decode">decode</a></li>
</ul>
</ul>
<hr name="index" />
</div>
<!-- INDEX END -->
<p>
</p>
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
require DataStore::CAS::FS::DirCodec::Universal
my %metadata= ( foo => 1, bar => 42 );
my @entries= ( { name => 'file1', type => 'file', ref => 'SHA1DIGESTVALUE', mtime => '1736354736' } );
my $digest_hash= DataStore::CAS::FS::DirCodec->put( $cas, 'universal', \@entries, \%metadata );
my $dir= DataStore::CAS::FS::DirCodec->load( $cas->get($digest_hash) );
print Dumper( $dir->get_entry('file1') );</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>This <a href="/DataStore/CAS/FS/DirCodec.html">DirCodec</a> can store any arbitrary metadata about a file.
It uses <em>JSON</em> for its encoding, so other languages/platforms should be able to easily interface
with the files this codec writes ... except for Unicode caveats.</p>
<p>
</p>
<h2><a name="unicode">Unicode</a></h2>
<p>JSON requires that all data be proper Unicode, and some filenames might be
a sequence of bytes which is not a valid Unicode string. While the high-ascii
bytes of these filenames could be encoded as unicode code-points, this would
create an ambiguity with the names that actually were Unicode. Instead, I
wrap values which are intended to be a string of octets in an instance of
<a href="/DataStore/CAS/Dir/InvalidUTF8.html">the DataStore::CAS::Dir::InvalidUTF8 manpage</a>, which gets written into JSON as</p>
<pre>
C<{ "*InvalidUTF8*": $bytes_as_codepoints }></pre>
<p>Any attribute which contains bytes >= 0x80 and which does not have Perl's
unicode flag set will be encoded this way, so that it comes back as it went in.</p>
<p>However, since filenames are intended to be human-readable, they are decoded as
unicode strings when appropriate, even if they arrived as octets which just
happened to be valid UTF-8.</p>
<p>
</p>
<hr />
<h1><a name="methods">METHODS</a></h1>
<p>
</p>
<h2><a name="encode">encode</a></h2>
<pre>
my $serialized= $class->encode( \@entries, \%metadata )</pre>
<p>Serialize the given entries into a scalar.</p>
<p><code>@entries</code> is an array of <a href="/DataStore/CAS/FS/DirEnt.html">DirEnt</a> objects or hashrefs mimicing them.</p>
<p><code>%metadata</code> is a hash of arbitrary metadata which you want saved along with the
directory.</p>
<p>This "Universal" DirCodec serializes the data as a short one-line header
followed by a string of JSON. JSON isn't the most efficient format around,
but it has wide cross-platform support, and can store any arbitrary <a href="/DataStore/CAS/FS/DirEnt.html">DirEnt</a>
attributes that you might have, and even structure within them.</p>
<p>The serialization contains newlines in a manner that should make it convenient
to write custom processing code to inspect the contents of the directory
without decoding the whole thing with a JSON library.</p>
<p>If you add anything to the metadata, try to keep the data consistent so that
two encodings of the same directory are identical. Otherwise, (in say, a
backup utility) you will waste disk space storing multiple copies of the same
directory.</p>
<p>
</p>
<h2><a name="decode">decode</a></h2>
<pre>
$dir= $class->decode( %params )</pre>
<p>Reverses <code>encode</code>, to create a Dir object.</p>
<p>See <a href="/ DataStore/CAS/FS/DirCodec.html#load">DirCodec->load </a> for details on <code>%params</code>.</p>
</body>
</html>