/ 
File-Find-Repository-0.03.3
River stage zero No dependents
/ File::Find::Repository

NAME

File::Find::Repository - Find files in your repositories.

SYNOPSIS

use File::Find::Repository ;

my $locator = new File::Find::Repository
		(
		NAME => 'name you want to see when messages are displayed',
		
		REPOSITORIES =>
			[
			'path',
			\&sub,
			...
			],
		) ;
			
# single scalar argument
my $located_file = $locator->Find($file_to_locate) ;

# multiple arguments
my $located_files = $locator->Find
			(
			FILES        => [...],
			REPOSITORIES => ['path', \&sub, ...],
			VERBOSE      => 1,
			) ;

DESCRIPTION

This module will find files in a set of repositories.

DOCUMENTATION

This module will try to locate a file in the repositories you define. The repositories are either a string representing a local filesystem path or a sub.

When locating a file, multiple file match can occur (each in a different repository). The default behavior is to return the first match.

You can customize the behavior of the search with two callbacks.

FULL_INFO will be called to allow you to add relevant information to the files that have been located.

WHICH will be called to let you decide which found files is returned.

Advanced example

This module was extracted from PBS, a build system, made generic and will be re-integrated in PBS in next version. Here is how it could be used for a more advanced repository search.

Let's imagine we have multiple matches for an object file in our repositories. The goal here is to not rebuild the object file. Selecting the first object file in the list would be too naive so we define a WHICH callback that will select the most appropriate. In this case, it might involve looking in the object file digest and/or check what configuration was used when the object file was build.

my $located_file = $locator->Find
			(
			FILES => [$file_to_locate],
			REPOSITORIES => [$build_directory, @repositories],
			WHICH => FIND_NODE_WITH_DEPENDENCIES($information_needed_to_select_the_found_file)
			
			# bote that FIND_NODE_WITH_DEPENDENCIES returns a sub reference
			) ;

$located_file ||= "$build_directory/$located_file" ;

SUBROUTINES/METHODS

new

Create a File::Find::Repository .

my $locator = new File::Find::Repository
		(
		# all arguments are optional
		
		NAME => 'name you want to see when messages are displayed',
		
		REPOSITORIES =>
			[
			'path',
			\&sub,
			...
			],
			
		INTERACTION =>
			{
			INFO = \&OnMyTerminal,
			WARN = \&WithBlinkingRedLetters,
			DIE  = \&QuickAndPainless,
			}
			
		VERBOSE   => 1,
		FULL_INFO => \&File::Find::Repository::TIME_AND_SIZE,
		WHICH     => \&File::Find::Repository::FIRST_FOUND,
		) ;

Options

  • NAME

    Name you want to see when messages are displayed.

  • REPOSITORIES

    An array reference. The elements are either scalars representing a local filesystem path or a code reference. The code references are passed a single argument, the file to locate, and should either return the located file or undef.

    This allows you to, for example, to locate the files on servers.

  • INTERACTION

    Lets you define subs used to interact with the user.

    INTERACTION      =>
	{
	INFO  => \&sub,
	WARN  => \&sub,
	DIE   => \&sub,
	}
    INFO

    This sub will be used when displaying VERBOSE information.

    WARN

    This sub will be used when a warning is displayed.

    DIE

    Used when an error occurs.

    The functions default to:

    • INFO => print

    • WARN => Carp::carp

    • DIE => Carp::confess

  • VERBOSE

    When set, informative messages will be displayed.

  • FULL_INFO

    This is set to a sub ref which is called for all the found files, this allows you to add information. See File::Find::Repository::TIME_AND_SIZE for an example.

    Passed arguments:

    • the File::Find::Repository object.

      This is useful when you want to display a message; use the subroutines defined in $object->{INTERACTION}.

    • The file name

    • a hash reference.

      The found file.

  • WHICH

    By defaults, File::Find::Repository will set WHICH to File::Find::Repository::FIRST_FOUND which return the first file found in the repositories.

    Define this callback if you wish to return something else, e.g. the newest file or the largest file.

    WHICH subroutine will be called with these arguments:

    • the File::Find::Repository object.

      This is useful when you want to display a message; use the subroutines defined in $object->{INTERACTION}.

    • a hash reference.

      Containing all the found files, after processing with FULL_INFO. The hash is ordered.

    The subroutine should return one of the array elements or undef. Note that you could also return an element not present in the hash. In this case, a proper documentation of your algorithm will help maintenance.

Setup

Helper sub called by new. This is a private sub.

Find

# single scalar argument
my $located_file = $locator->Find($file_to_locate) ;

# multiple arguments
my $located_files = $locator->Find
			(
			FILES        => [...],
			
			# optional
			REPOSITORIES => ['path', \&sub, ...],
			VERBOSE      => 1,
			INTERACTION  => { INFO = \&OnMyTerminal,},
			FULL_INFO    => \&File::Find::Repository::TIME_AND_SIZE,
			WHICH        => \&File::Find::Repository::FIRST_FOUND,
			) ;

SCALAR calling context

Only SCALAR calling context is allowed.

Arguments

If a single string argument is passed to Find, a string or undef is returned.

If multiple arguments are passed, they will override the object's values for the call duration.

Valid arguments:

  • FILES

    An array ref with scalar elements. Each element represents a file to locate. The returned value will be an ordered hash reference.

  • AT_FILE and AT_LINE

    These will be used in the information message and the history information if set. If not set, the values returned by caller will be used. These options allow you to write wrapper functions that report the callers location properly.

    All arguments passed to New, except NAME are also valid arguments to Find.

FindFiles

This is a private sub. Do not use directly.

Finds all the files in the repositories.

CheckOptions

Verifies the options passed to the members of this class. Calls {INTERACTION}{DIE} in case of error. This shall not be used directly.

FIRST_FOUND

Returns the first matching file.

TIME_AND_SIZE

Adds time and size information to the matched file.

BUGS AND LIMITATIONS

None so far.

AUTHOR

Khemir Nadim ibn Hamouda
CPAN ID: NKH
mailto:nadim@khemir.net

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc File::Find::Repository

You can also look for information at:

SEE ALSO

File::Find::Rules