NAME

lib::restrict - Perl extension for restricting what goes into @INC

SYNOPSIS

    use lib::restrict qw(foo bar baz), $restiction;
 
    use lib::restrict qw(foo bar baz);
    
    no lib::restrict qw(foo bar baz);

DESCRIPTION

lib::restrict useage and functionality is the same as 'use lib' and 'no lib' (because it ISA lib::) with an additional feature described below.

RESTRICTING WHAT GOES INTO @INC

If the last item passed to use lib::restrict is all digits or an array ref of items that are all digits then only paths passed that are owned by those uids are used.

    # add /foo and /bar only if owned by root
    use lib::restrict '/foo', '/bar', 0;

or

    # add /foo and /bar only if owned by root, effective uid, or real uid
    use lib::restrict '/foo', '/bar', [0, $>, $<];

This means if you are adding a directory that is all digits it has to go somewhere besides the end.

    # add the path 123 if owned by root *not* add the paths 123 and 0
    use lib::restrict '123', '0';

This is not true if its the only argument:

    use lib::restrict '123'; # treats 123 as a path not a uid

Any items that are non numeric are simply ignored:

    use lib::restrict '/foo', '/bar', '/baz'; # adds those 3 paths

    use lib::restrict '/foo', '/bar', [qw( /baz 0 123 /wop)]; # adds /foo and /bar if its owned by root or uid 123

In addition the last item can be a code reference that accepts tha filename as its only argument and returns true if its ok to add and false to not add it.

CONTROLLING BEHAVIOR VIA %ENV

If true, $ENV{'lib::restrict-quiet'}, stiffles the carp when a path is denied.

Set $ENV{'lib::restrict-!-d_ok_in'} to an array ref of absolute paths (will be made absolute if relative). Any paths passed to lib::restrict that do not exist but whose parent is in that list will be allowed and the uid/code ref check ignored.

In other words if you

    local $ENV{'lib::restrict-!-d_ok_in'} = ['/foo'];
    # assuming neither exists yet
    use lib::restrict qw(/foo/bar /foo/baz/wop, $restriction);

/foo/bar made it because /foo, its parent is in the list.

/foo/baz/wop did not because it parent, /foo/baz, is not in the list

SEE ALSO

lib

AUTHOR

Daniel Muey, http://drmuey.com/cpan_contact.pl

COPYRIGHT AND LICENSE

Copyright (C) 2006 by Daniel Muey

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.

cpanm lib::restrict

perl -MCPAN -e shell
install lib::restrict