DataStore::CAS::FS::DirEnt - Light-weight Immutable Directory Entry Object
version 0.0101
DataStore::CAS::FS::DirEnt is a super-light-weight class. More of an interface, really. DirEnt objects should be considered immutable constants, and all attributes are read-only. It is of course *possible* to modify them, but this will break caching features of DataStore::CAS::FS, so don't do that.
See the clone(%params) method for a convenient way to create modified copies of a DirEnt.
Each attribute is optional, except 'name' and 'type'. Accessors for non-existent attributes will return undef. To find out which attributes actually exist, use the as_hash method and inspect the keys.
as_hash
The name of this entry within its directory.
At the end of a long debate with myself, I decided that filenames should be defined as unicode strings, because we want the world to move in that direction, and because I didn't want to get into the "Native Charset" mess when enabling interoperability between Windows and Unix. However, not all UNIX filenames will be unicode, which creates a dilemma: how do you represent these without mangling people's backups?
First, if a file from Unix has a non-UTF-8 name, there is no way to correctly extract it on a Windows platform without mangling the name. (unless you know the unix system to be encoded with a specific charset) The argument of "filenames should just be bytes" doesn't work because then you just push the problem up the software stack, causing problems for network filesystems, removable media, and GUI tools.
Next, (disclaimer: I am not a wide-character user) if you have wide characters in your filename in the first place, you probably know what charset they should be in. So, in using a backup utility, you should be able to specify the charset so that it can translate the names while reading the filesystem.
And finally, it would be a bigger pain to have to decode filenames as you read them from the DataStore::CAS::FS and re-encode them for the current filesystem than it would be to always translate Unicode to the current charset.
But still, people might want to make a backup of *mostly* Unicode but still preserve a few files that had mangled names. While you might want to fix those filenames, it would be inconvenient if your scheduled backups broke because of a bad filename.
So, I came up with the DataStore::CAS::FS::InvalidUTF8 object, which you can use to wrap invalid UTF-8 sequences and deal with the problem later.
So, this 'name' field should return a string of unicode codepoints *or* an instance of DataStore::CAS::FS::InvalidUTF8 (which can stringify to the original octets)
One of "file", "dir", "symlink", "blockdev", "chardev", "pipe", "socket".
Note that 'symlink' refers only to UNIX style symlinks. As support for other systems' symbolic links is added, new type strings will be added to this list, and the type will determine how to interpret the ref value.
ref
type must always be defined when stored, though instances of DirEnt with an undefined type might exist temporarily while building a new directory.
type
For file or dir: the store's checksum of the referenced data.
For symlink: the path as a string of path parts separated by '/'.
For blockdev and chardev: the device node as a string of "$major,$minor".
Ref is allowed to be undefined (regardless of type) if the data is not known.
The size of the referenced file. In the case of directories, this is the size of the serialized directory, if one is referenced. No other types should have a size.
The timestamp of the creation of the file, expressed in Unix Epoch seconds.
The timestamp the file was last modified, expressed in Unix Epoch seconds.
The number reported by lstat for uid.
The number reported by lstat for gid
The user name corresponding to the unix_uid
The group name corresponding to the unix_gid
The unix permissions for the entry, as reported by lstat.
The unix atime, as reported by lstat.
The unix ctime, as reported by lstat.
An alias for modify_ts.
The device file number, as reported by lstat.
The inode number, as reported by lstat.
The the hardlink count reported by lstat.
The block size reported by lstat.
The block count reported by lstat.
$dirEnt= DataStore::CAS::FS::DirEnt->new( %fields | \%fields )
The default constructor *uses* the hashref you pass to it. (it does not clone) This should be ok, because the DirEnt objects should never be modified. We don't yet enforce that though, so be careful what you pass to it.
$dirEnt2= $dirEnt->clone( %overrides )
Create a new directory entry, with some fields overridden.
Most implementations will simply call new( %{$self->as_hash}, %overrides ), but in some implementations it might not be possible or practical to apply the requested overrides, so you might get back a different class than the original.
new( %{$self->as_hash}, %overrides )
$immutable_hash= $dirEnt->as_hash();
Returns the fields of the directory entry as a hashref. The hashref will contain only the public fields. The hashref might be cached, and SHOULD NEVER BE MODIFIED. (Future versions might use perl's constants feature to enforce this)
Michael Conrad <mconrad@intellitree.com>
This software is copyright (c) 2013 by Michael Conrad, and IntelliTree Solutions llc.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install DataStore::CAS::FS, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DataStore::CAS::FS
CPAN shell
perl -MCPAN -e shell install DataStore::CAS::FS
For more information on module installation, please visit the detailed CPAN module installation guide.