NAME

File::HStore - Perl extension to store files on a filesystem using a very simple hash-based storage.

SYNOPSIS

  use File::HStore;
  my $store = File::HStore ("/tmp/.mystore");
  
  # Add a file in the store
  my $id = $store->add("/foo/bar.txt");

  # Return the filesystem location of an id
  my $location = $store->getpath($id);

  # Remove a file by its id from the store
  $store->remove("ff3b73dd85beeaf6e7b34d678ab2615c71eee9d5")

DESCRIPTION

File-HStore is a very minimalist perl library to store files on a filesystem using a very simple hash-based storage.

File-HStore is nothing more than a simple wrapper interface to a storage containing a specific directory structure where files are hold based on their hashes. The name of the directories is based on the first two bytes of the hexadecimal form of the digest. The file is stored and named with its full hexadecimal form in the corresponding prefixed directory.

The current version is supporting the SHA-1 and SHA-2 (256 bits) algorithm. The FAT (Free Archive Toolkit) format is also supported and it is composed of the date of submission plus the SHA-2 real digest part.

METHODS

The object oriented interface to File::HFile is described in this section.

The following methods are provided:

$store = File::HStore->new($path,$digest,$prefix)

This constructor returns a new File::HFile object encapsulating a specific store. The path specifies where the HStore is located on the filesystem. If the path is not specified, the path ~/.hstore is used. The digest specifies the algorithm to be used (SHA-1 or SHA-2 or the submission date called FAT). If not specified, SHA-1 is used. Various digest can be mixed in the same path but the utility is somewhat limited. The $prefix is only an extension used for the FAT (Free Archive Format) format to specify the archive unique name.

$store->add($filename)

The $filename is the file to be added in the store. The return value is the hash value ($id) of the $filename stored. Return undef on error.

$store->getpath($id)

Return the filesystem location of the file specified by its hash value.

Return undef on error.

$store->remove($hashvalue)

The $hashvalue is the file to be removed from the store.

Return false on success and undef on error.

SEE ALSO

There is a web page for the File::HStore module at the following location : http://www.foo.be/hstore/

If you plan to use a hash-based storage (like File::HStore), don't forget to read the following paper and check the impact for your application :

An Analysis of Compare-by-hash - http://www.usenix.org/events/hotos03/tech/full_papers/henson/henson.pdf

Please also consider the security impact in your application concerning the statement made by the NIST regarding the overall security impact of the SHA-1 vulnereability. In the use of storage and unique identifier only , the impact is somewhat very limited.

http://csrc.nist.gov/news-highlights/NIST-Brief-Comments-on-SHA1-attack.pdf

AUTHOR

Alexandre "adulau" Dulaunoy, <adulau@foo.be>

COPYRIGHT AND LICENSE

Copyright (C) 2004-2008 by Alexandre Dulaunoy <adulau@uucp.foo.be>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have available.