NAME

 FileHash::Base - Abstract superclass for FileHashes.

SYNOPSIS

 use FileHash;
 $obj = FileHash::Base->alloc;

 $obj = $obj->init;
 $obj = $obj->initFromLines  ($formatline,@lines);
 $obj = $obj->initFromFile   ($formatline,$datafilepath);
 $obj = $obj->initFromTree   ($rootdir);
 $obj = $obj->initFromObject ($obj2);
 $obj = $obj->initFromDump   ($path);

 $obj = $obj->addFromLines   ($formatline,@lines);
 $obj = $obj->addFromFile    ($formatline,$datafilepath);
 $obj = $obj->addFromTree    ($rootdir);
 $obj = $obj->addFromObject  ($obj2);
 $obj = $obj->addFromDump    ($path);

 $fhb = $fha->identical;
 $fhb = $fha->unique;

 $fhc = $fha->and            ($fhb);
 $fhc = $fha->andnot         ($fhb);
 $fhc = $fha->xor            ($fhb);

 $obj = $obj->dump           ($dumpfile);

Inheritance

 UNIVERSAL

Description

This is an abstract superclass for containers of lists of file metadata. It is not directly useable and will execute a Fault if you attempt it.

FileHash::Name and FileHash::Content inherit most of their behavior from here with the exception of hash key selection.

Examples

 See subclasses.

Class Variables

 None.

Instance Variables

 filehash       Pointer to a hash of arrays of FileHash::Entry objects
                which contain all the file metadata discovered found
                when the FileHash object was initialized. Entries for files 
                with identical keys hash into the same array, making for
                a very efficient sort.

Class Methods

$obj = FileHash::Base->alloc

Allocate an empty instance of FileHash::Base. This is for inheritance only and should not be used. Subclasses could override but there is probably no reason to do so unless they add ivars. None do at present.

Instance Methods

Unless otherwise specified, instance methods return self on success and undef on failure.

$fhc = $fha->and ($fhb)

Create a file hash containing the groups of files found in both filehash a and b.

a and b must be of the same FileHash subclass and the newly created c will be off that type also.

$fhc = $fha->andnot ($fhb)

Create a file hash containing the groups of files found in filehash a but not in filehash b.

a and b must be of the same FileHash subclass and the newly created c will be off that type also.

If you want not a and b, just reverse the args; not a and not b is obviously nonsensical as we are testing keys of a against keys of b.

$obj = $obj->addFromDump ($dumpfile)

Use a dump file to recreate hash entries and add them to a FileHash object.

The first line of the file must contain the text:

        Version: x.yy

$obj = $obj->addFromFile ($format,$datafilepath)

Use the format line to create a FileHash::FormatString object. The format object is used to parse each of the lines in a file which contains lines of text data. Each line in the file is assumed to contain data about one file which is to be added to the FileHash.

$obj = $obj->addFromLines ($format,@lines)

Use the format line to create a FileHash:FormatString object. The format object is used to parse each of the lines in a list. Each line contains data about one file which is to be added to the FileHash.

$obj = $obj->addFromObject ($obj2)

Add data to a filehash from another FileHash, $obj2. This is useful for merging two objects. The subclasses need not be the same because the Entries are inserted by re-hashing into the target object.

        my $a = FileHash::Name->alloc;
        $a->initFromTree ("/root");
        $a->addFromTree  ("/home/me");

$obj = $obj->addFromTree ($rootdir)

Entries are added to the hash via a recursive descent through a directory tree. Each file is a 'leaf node' and is represented by an array record in the hash. If two files have the same hash key, the are likely identical so the records for them are placed together in an array under that hask key.

$obj = $obj->dump ($dumpfile)

Dump FileHash::Entry objects sequentially, one to a line, to the specified filename.

The first line of the file contains the FileHash::Entry dump file format version number in this format:

        Version: x.yy

$fhb = $fha->identical

Return a FileHash containing the contents of hash keys which have more than one member. If the keys are md5,length this represents all files with the same content; if they keys are name it represents all files with the same name.

$obj = $obj->init

A noop at present. If you need an empty object, use this after alloc to make sure that if init is needed in the future, it will be carried out.

$obj = $obj->initFromDump ($dumpfile)

Use a dump file to recreate hash entries in a freshly alloc'd FileHash object.

The first line of the file must contain the text:

        Version: x.yy

$obj = $obj->initFromFile ($format,$datafilepath)

Initialize a freshly alloc'd FileHash. It uses the format line to init a FileHash::FormatString object. The format object is used to parse each of the lines in a file which contains lines of text data. Each line in the file is assumed to contain data about one file.

$obj = $obj->initFromLines ($format,@lines)

Initialize a freshly formatted FileHash. It uses the format line to create a FileHash:FormatString object. The format object is used to parse each of the lines in a list. Each line contains data about one file.

$obj = $obj->initFromObject ($obj2)

Initialize the newly alloc'd object using data from another FileHash, $obj2. This is useful for changing from hashing by name to hashing by content or vice versa:

        my $a = FileHash::Name->alloc;
        my $b = FileHash::Content->alloc;
        $a->initFromTree ("/root");
        $b->initFromObject ($a);

$obj = $obj->initFromTree ($rootdir)

Initialize a freshly alloc'd FileHash. The hash is filled via a recursive descent through a directory tree. Each file is a 'leaf node' and is represented by an array record in the hash. If two files have the same hash key, the are likely identical so the records for them are placed together in an array under that hask key.

$fhb = $fha->unique

Return a FileHash containing the contents of hash keys which have only one member. These are files for which no other file has the same content if the key is md5,length; or the same name if the key is the name.

$fhc = $fha->xor ($fhb)

Create a filehash c which contains all of the groups of files which are only in fha or fhb but not both.

a and b must be of the same FileHash subclass and the newly created c will be off that type also.

Private Class Method

 None.

Private Instance Methods

$key = $obj->_genKey($entry)

Create an appropriate hash key. Each subclass must override this stub method as it does nothing except print a warning message and crash the program.

Errors and Warnings

 Lots.

KNOWN BUGS

 See TODO.

SEE ALSO

  File::Spec, Cwd, FileHash::Entry, FileHash::FormatString, Fault::Logger.

AUTHOR

Dale Amon <amon@vnl.com>

cpanm FileHash::Base

perl -MCPAN -e shell
install FileHash::Base