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

	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,
				) ;

This module will find files in a set of repositories.

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.

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" ;

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,
			) ;

* 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.

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

	# 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,
				) ;

Only SCALAR calling context is allowed.

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.

This is a private sub. Do not use directly.

Finds all the files in the repositories.

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

Returns the first matching file.

Adds time and size information to the matched file.

None so far.

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

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

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

    perldoc File::Find::Repository

You can also look for information at:

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/File-Find-Repository

* RT: CPAN's request tracker

Please report any bugs or feature requests to L <bug-file-find-repository@rt.cpan.org>.

We will be notified, and then you'll automatically be notified of progress on your bug as we make changes.

* Search CPAN

http://search.cpan.org/dist/File-Find-Repository

File::Find::Rules