Home | lib::tree

PRIVATE SUBROUTINES
AUTHOR
BUGS
SUPPORT
ACKNOWLEDGEMENTS
LICENSE AND COPYRIGHT

NAME

lib::tree - Add directory trees to the @INC array at compile time.

VERSION

Version 0.05

SYNOPSIS

This pragma allows you to specify one or more directories to search for the given library directory name to be added to the @INC array. Also, based on Perl interpreter type and version, this pragma will add the correct sub-directories within the given library directory (but only if said directories are found).

    # Called with a hash:
    use lib::tree ( DIRS =>  [ '/some/directory/',
                               'another/directory/',
                               '/yet/another/directory/with/*/globbing/',
                               'more/{dir,directory}/glob?/fun/',
                             ], # Accepts absolute/relative directories, with or
                                # without globbing.  (Defaults to the directory
                                # of the currently running script; i.e., if the
                                # full path to the script which invoked
                                # lib::tree is '/home/foo/scripts/bar.pl' then
                                # the default will be '/home/foo/scripts/')
                    LIB_DIR => 'libName', # This should be *just* the name of
                                          # the directory (i.e., neither a
                                          # relative nor an absolute path;
                                          # defaults to 'libperl')!
                    DEPTH_FIRST => 0, # If this is false, then lib::tree will do
                                      # a breadth-first search of the
                                      # directories listed by the DIRS
                                      # parameter.  (Defaults to 1; this allows
                                      # the order of directories specified in
                                      # the DIRS parameter to be honored)
                    HALT_ON_FIND => 1, # Do we want to stop searching
                                       # directories for the given LIB_DIR when
                                       # we find our first match?  (Defaults to
                                       # 1; normally you do not want multiple
                                       # LIB_DIRs found.)
                    DELTA => 2, # How many directories up and down the directory
                                # tree from a given location in said tree are we
                                # to search for a LIB_DIR?  (Defaults to 0; that
                                # is, we normally do *not* look outside of the
                                # directories listed by the DIRS parameter)
                  );
    
    
    # Called with a list which begins with an array reference:
    use lib::tree ( [ '/some/directory/',
                      'another/directory/',
                      '/yet/another/directory/with/*/globbing/',
                      'more/{dir,directory}/glob?/fun/',
                    ], # The DIRS parameter.
                    'libName', # The LIB_DIR parameter.
                    0, # The DEPTH_FIRST parameter.
                    1, # The HALT_ON_FIND parameter.
                    2, # The DELTA parameter.
                  );
    # PLEASE NOTE:
    #     Order matters! If you want to leave a value at the default setting but
    #     want to change the value of something later in the list, use the
    #     undefined value as a placeholder for the default values you do no want
    #     to change.
    
    
    # Called with a simple list:
    use lib::tree ( '/some/directory/',
                    'another/directory/',
                    '/yet/another/directory/with/*/globbing/',
                    'more/{dir,directory}/glob?/fun/',
                  );
    # PLEASE NOTE:
    #     If lib::tree is called with a simple list, two defaults change:
    #         * LIB_DIR defaults to '' (i.e., everything that matches what is
    #           listed will be added to the @INC array).
    #         * HALT_ON_FIND defaults to 0 (otherwise, only the first matching
    #           directory would be added to the INC array).

USAGE

Upon finding a directory whose name matches the LIB_DIR parameter in one of the specified directories, the full path to that directory (i.e., /{specified_dir}/{custom_lib}/)is added to the @INC array as well as the following directories (replace {lib_dir} with lib and site/lib) within the newly added directory (but only if said directories exist and are readable):

.../{lib_dir}/
.../{lib_dir}/{previous_version(s)}/
.../{lib_dir}/{archname}/
.../{lib_dir}/{archname64}/
.../{lib_dir}/{short_version}/
.../{lib_dir}/{short_version}/{archname}/
.../{lib_dir}/{short_version}/{archname64}/
.../{lib_dir}/{version}/
.../{lib_dir}/{version}/{archname}/
.../{lib_dir}/{version}/{archname64}/

Additionally, lib::tree looks for a directory named .../{custom_lib}/PerlInterpreterName/{os_name}-{perl_type}/. If such a directory is found, then that directory (as well as any directories underneath it which match the above list) are added to the @INC array. This is done so a single custom library may contain binary Perl modules for different interpreters.

For example, a single custom library loaded via lib::tree could support the following Perl interpreters if the associated directories were present and readable:

ActiveState Perl on Windows supported via .../{custom_lib}/PerlInterpreterName/MSWin32-ActiveStatePerl/
Strawberry Perl on Windows supported via .../{custom_lib}/PerlInterpreterName/MSWin32-StrawberryPerl/
Vanilla Perl on Windows supported via .../{custom_lib}/PerlInterpreterName/MSWin32-VanillaPerl/
/usr/bin/perl on Cygwin supported via .../{custom_lib}/PerlInterpreterName/cygwin-UsrBinPerl/
/usr/local/bin/perl on Linux supported via .../{custom_lib}/PerlInterpreterName/linux-UsrLocalPerl/
/usr/bin/perl on Linux supported via .../{custom_lib}/PerlInterpreterName/linux-UsrBinPerl/

Please note, definitively identifying different Perl interpreters is an ongoing subject of research (if lib::tree is not correctly identifying your platform please suggest a method of doing so to the author/maintainer of this module). Also, the {os_name}- prefix is needed because of ActiveState's broken (bordering on brain-damaged) install which does not put binary Perl modules in the canonical location (that is, in any of the above mentioned .../{archname}/ or .../{archname64}/ directories).

Of note is when this module is called with a simple list (that is, a list where all values are scalars), four configuration commands are honored (all commands begin with the ':' character):

:ORIGINAL: Restores @INC array to its original condition. This is provided as an alternative to saying @INC = @lib::tree::Original_INC; (which some schools of thought consider to be inelegant). May be negated by prepending NO- (i.e., :NO-ORIGINAL).; Synonyms are: :ORIGINAL-INC, :RESTORE-ORIGINAL, :RESTORE-ORIGINAL-INC, :ORIGINAL_INC, :RESTORE_ORIGINAL, :RESTORE_ORIGINAL_INC
:DEPTH: Sets the search type to depth-first. May be negated by prepending NO- (i.e., :NO-DEPTH).; Synonyms are: :DEPTH-FIRST, :DEPTH_FIRST
:HALT: Sets the search style to halt on the first directory which satisfies the search criteria. May be negated by prepending NO- (i.e., :NO-HALT).; Synonyms are: :HALT-ON-FIND, :HALT_ON_FIND
:DEBUG: Turns on debugging. May be negated by prepending NO- (i.e., :NO-DEBUG).

Also, lib::tree uses the File::Spec module methods for all path manipulation. As an added bonus, lib::tree allows you to specify which flavour of File::Spec you want lib::tree to use via the $FS variable (defaults to 'File::Spec').

Should you want lib::tree to use a specific flavour of File::Spec, use something like the following code:

    BEGIN {
        require lib::tree;
        $lib::tree::FS = 'File::Spec::Unix';
    }
    use lib::tree ('/some/directory/', 'another/directory/');
    
    #  ~~~ or ~~~  
    
    BEGIN {
        require lib::tree;
        $lib::tree::FS = 'File::Spec::Unix';
        lib::tree->import('/some/directory/', 'another/directory/');
    }

EXAMPLES

Example 1:

    use lib::tree;

The above incantation will look in /{full_path_to_script_directory}/ (or whatever the $lib::tree::Default{DIRS} array reference is set to) for a directory named libperl (or whatever the $lib::tree::Default{LIB_DIR} scalar value is set to).

Example 2:

    use lib::tree ( DIRS =>  [ '/home/cschwenz/foo/',
                               '/home/cschwenz/bar/' ],
                  );

The above incantation will look in /home/cschwenz/foo/ and /home/cschwenz/bar/ for a directory named libperl (or whatever the $lib::tree::Default{LIB_DIR} scalar value is set to).

Example 3:

    use lib::tree ( DIRS =>  [ '/home/cschwenz/foo/',
                               '/home/cschwenz/bar/' ],
                    LIB_DIR => 'custom_perl_lib',
                  );

The above incantation will look in /home/cschwenz/foo/ and /home/cschwenz/bar/ for a directory named custom_perl_lib.

Example 4:

    use lib::tree ( DIRS =>  [ '/home/cschwenz/foo/',
                               '/home/cschwenz/bar/' ],
                    LIB_DIR => 'custom_perl_lib',
                    DELTA => 3,
                  );

The above incantation will look up/down the directory tree to a max of three directories from the starting locations of /home/cschwenz/foo/ and /home/cschwenz/bar/ for a directory named custom_perl_lib.

That is, the directories /home/cschwenz/foo/, /home/cschwenz/foo/../, /home/cschwenz/foo/*/, /home/cschwenz/foo/../../, /home/cschwenz/foo/*/*/, /home/cschwenz/foo/../../../, /home/cschwenz/foo/*/*/*/, /home/cschwenz/bar/, /home/cschwenz/bar/../, /home/cschwenz/bar/*/, /home/cschwenz/bar/../../, /home/cschwenz/bar/*/*/, /home/cschwenz/bar/../../../, and /home/cschwenz/bar/*/*/*/ will be searched for a directory named custom_perl_lib (in that order). The search will halt upon finding the first instance of a directory named custom_perl_lib.

Example 5:

    use lib::tree ( DIRS =>  [ '/home/cschwenz/foo/',
                               '/home/cschwenz/bar/' ],
                    LIB_DIR => 'custom_perl_lib',
                    DEPTH_FIRST => 0,
                    DELTA => 2,
                  );

The above incantation will look up/down the directory tree to a max of two directories from the starting locations of /home/cschwenz/foo/ and /home/cschwenz/bar/ for a directory named custom_perl_lib. But, because the DEPTH_FIRST parameter is now false, do a breadth-first search instead.

The DEPTH_FIRST parameter change is important because it changes the order directories are searched (thus potentially changing which custom_perl_lib gets loaded due to the HALT_ON_FIND parameter defaulting to true). That is, the directories /home/cschwenz/foo/, /home/cschwenz/bar/, /home/cschwenz/foo/../, /home/cschwenz/bar/../, /home/cschwenz/foo/*/, /home/cschwenz/bar/*/, /home/cschwenz/foo/../../, /home/cschwenz/bar/../../, /home/cschwenz/foo/*/*/, and /home/cschwenz/bar/*/*/ will be searched for a directory named custom_perl_lib (in that order). The search will halt upon finding the first instance of a directory named custom_perl_lib.

Example 6:

    use lib::tree ( DIRS =>  [ '/home/cschwenz/foo/',
                               '/home/cschwenz/bar/' ],
                    LIB_DIR => 'custom_perl_lib',
                    HALT_ON_FIND => 0,
                  );

The above incantation will look in /home/cschwenz/foo/ and /home/cschwenz/bar/ for a directory named custom_perl_lib. But because the HALT_ON_FIND parameter is now false, lib::tree will continue searching regardless of what it finds; if there is a custom_perl_lib directory in both directories, then both /home/cschwenz/foo/custom_perl_lib/ and /home/cschwenz/bar/custom_perl_lib/ will be added to the @INC array.

Example 7:

    use lib::tree ( DIRS =>  [ '/home/cschwenz/foo/',
                               '/home/cschwenz/bar/' ],
                    LIB_DIR => '',
                    HALT_ON_FIND => 0,
                  );

The above incantation will add /home/cschwenz/foo/ and /home/cschwenz/bar/ to the @INC array (but only if said directories exist and are readable).

Example 8:

    use lib::tree ( DIRS =>  [ '/home/cschwenz/foo/',
                               '/home/cschwenz/ba[rz]/',
                               '/home/cschwenz/qu*x/' ],
                    LIB_DIR => '',
                    HALT_ON_FIND => 0,
                  );

The above incantation will add /home/cschwenz/foo/, any directory matching the file glob /home/cschwenz/ba[rz]/ (i.e., /home/cschwenz/bar/ and/or /home/cschwenz/baz/), and any directory matching the file glob /home/cschwenz/qu*x/ to the @INC array (but only if said directories exist and are readable).

Example 9:

    use lib::tree ( DIRS =>  [ '/home/cschwenz/foo/',
                               '/home/cschwenz/ba[rz]/',
                               '/home/cschwenz/qu*x/' ],
                    LIB_DIR => '',
                    HALT_ON_FIND => 0,
                    DEBUG => 1,
                  );

The same as Example 8, but with debugging turned on so you can see what lib::tree is doing internally.

Example 10:

    use lib::tree ( '/home/cschwenz/foo/',
                    '/home/cschwenz/ba[rz]/',
                    '/home/cschwenz/qu*x/',
                    ':DEBUG',
                  );

The same as Example 9, but called in the simple list style.

SUBROUTINES

import

Called when you say use lib::tree ( ... );

May be called with a hash, a complex list (that is, a list which starts with an array reference), or a simple list (where all values are scalars).

To see what import() is doing, set the DEBUG parameter to true.

unimport

Called when you say no lib::tree ( ... );

May be called with a hash, a complex list (that is, a list which starts with an array reference), or a simple list (where all values are scalars).

To see what unimport() is doing, set the DEBUG parameter to true.

PRIVATE SUBROUTINES

These are listed for completeness, as well as to make it easier for future maintainers to understand the code.

TRUE: Used where the code is expecting a boolean value. Returns 1.
FALSE: Used where the code is expecting a boolean value. Returns 0.
_parse_params: Parses the @_ array, placing relevant data in a returned %param hash. Supports three different calling conventions: hash, complex list, and simple list.
_script_dir: This is the function which tries to determine the full path to the directory which holds the currently running program. Assumes the user has not chdired before lib::tree enters the compile phase.
_find_dirs: Given a reference to a list of directories, find the ones which exist, are readable, and (most importantly) truly are directories.
_find_lib_dirs: This subroutine is the heart of lib::tree; it is where we go hunting for the requested custom library directory. Takes the library directory name to search for, how many directories up/down from a given directory to search for said library directory, whether or not this is a depth-first search, if we halt the search on the first matching directory, and a reference to a list of directories to search.
_find_INC_dirs: Takes a reference to a list of directories and returns a (nuanced) list of directories to include on the @INC array.
_get_path_hash: Break a given path into is volume, directories, and file; then further divide the directories segment into individual directory names. Returns a hash with keys 'volume', 'directories', 'file', and 'dirs' (and the 'dirs' key points to an array reference).
_get_dirs: Given a path, generate a list of all possible directories to look for based on this perl interpreter's configuration values (it is the job of the _find_INC_dirs() subroutine to validate the returned list).
_find_perl_type: Return the directory name to look for when searching for this perl's binary modules (i.e., Perl modules which call out to dynamic libraries, modules which play well with only one type of perl interpreter, etc.). This subroutine is the one most likely to need periodic maintenance.
_valid_path: Canonize what constitutes a valid path. Used in the _glob_dir() and _add_to_list() subroutines and anywhere else we need to determine if a given path is valid for our uses.
_glob_dir: Take a scalar (presumably one which contains a directory path), run it through glob() and Cwd::realpath(), then return a list of directories which exist and are readable.
_add_to_list: Given two array references and the optional current first library directory (used to halt upon finding the first directory match), push the contents of the second array reference onto the array referenced by the first value.
_simplify_list: Given a list, use Tie::Indexed::Hash to maintain order while stripping out duplicates from said list; then return the cleaned list.

AUTHOR

Calvin Schwenzfeier, <calvin dot schwenzfeier at gmail.com>

BUGS

Please report any bugs or feature requests through GitHub's issue tracker web interface at http://github.com/cschwenz/lib-tree/issues.

SUPPORT

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

    perldoc lib::tree

You can also look for information at:

ACKNOWLEDGEMENTS

And again Jesus spoke to them in parables, saying, “The Kingdom of Heaven may be compared to a king who gave a wedding feast for his son, and sent his servants to call those who were invited to the wedding feast, but they refused to come. So he sent other servants, saying, ‘Tell those who are invited: «See, I have prepared my banquet; my bulls and my fattened cattle have been slaughtered, and everything is ready. Come to the wedding feast!»’ But they paid no attention and went off, one to his farm, another to his business; while the rest seized his servants, mistreated them, and killed them. The king was furious and sent his soldiers, who killed those murderers and burned down their city. Then he said to his servants, ‘The wedding feast is ready, but the ones who were invited did not deserve it. So go out to the street‑corners and invite to the banquet as many as you find.’ The servants went out into the streets and gathered all the people they could find, both bad and good; and the wedding hall was filled with guests. But when the king came in to look at the guests, he saw there a man who was not dressed for a wedding; so he asked him, ‘Friend, how did you get in here without wedding clothes?’ The man was speechless. Then the king said to the attendants, ‘Bind him hand and foot, and throw him outside into the dark!’ In that place people will wail and grind their teeth; for many are invited, but few are chosen.”

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of either:

a): the GNU General Public License [http://dev.perl.org/licenses/gpl1.html] as published by the Free Software Foundation [http://www.fsf.org/]; either version 1 [http://dev.perl.org/licenses/gpl1.html], or (at your option) any later version [http://www.fsf.org/licensing/licenses/#GNUGPL], or
b): the ``Artistic License'' [http://dev.perl.org/licenses/artistic.html].

    
    For those of you that choose to use the GNU General Public License, my
    interpretation of the GNU General Public License is that no Perl script
    falls under the terms of the GPL unless you explicitly put said script under
    the terms of the GPL yourself.
    
    Furthermore, any object code linked with perl does not automatically fall
    under the terms of the GPL, provided such object code only adds definitions
    of subroutines and variables, and does not otherwise impair the resulting
    interpreter from executing any standard Perl script. I consider linking in C
    subroutines in this manner to be the moral equivalent of defining
    subroutines in the Perl language itself. You may sell such an object file as
    proprietary provided that you provide or offer to provide the Perl source,
    as specified by the GNU General Public License. (This is merely an alternate
    way of specifying input to the program.) You may also sell a binary produced
    by the dumping of a running Perl script that belongs to you, provided that
    you provide or offer to provide the Perl source as specified by the GPL.
    (The fact that a Perl interpreter and your code are in the same binary file
    is, in this case, a form of mere aggregation.)
    
    This is my interpretation of the GPL. If you still have concerns or
    difficulties understanding my intent, feel free to contact me. Of course,
    the Artistic License spells all this out for your protection, so you may
    prefer to use that.
    
    -- Larry Wall

See http://dev.perl.org/licenses/ for more information.

Voir http://dev.perl.org/licenses/ pour plus d'information.

Ver http://dev.perl.org/licenses/ para más información.

См. http://dev.perl.org/licenses/ За дополнительной информацией.

Se http://dev.perl.org/licenses/ kwa taarifa zaidi.

Féach http://dev.perl.org/licenses/ le haghaidh tuilleadh eolais.

Se http://dev.perl.org/licenses/ för mer information.