نديم ابن ﺤﻣﻮﺪﺓ الخمير - Nadim Khemir > File-Find-Repository-0.03.3 > File::Find::Repository

Download:
File-Find-Repository-0.03.3.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.03   Source  

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

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:

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

syntax highlighting: