Paranoid::Glob - Paranoid Glob objects

       Arthur Corliss (corliss@digitalmages.com)

       o   Carp

       o   Errno

       o   Fcntl

       o   File::Glob

       o   Paranoid

       o   Paranoid::Debug

       The primary purpose of these objects is to allow an easy way to detaint a list of files and/or
       directories while performing shell expansion of names.  It does this with a caveat, however.  If a given
       file or directory name exists on the file system as a literal string (regardless of whether it has shell
       expansion characters in it) it will be added as such.  It is only filtered through bsd_glob if it does
       not exist on the file system.

       The objects can also be created with instructions to explicitly treat all names as literal strings.

       Any undef or zero-length strings passed in the files array are silently removed.

       As a convenience subsets of the expanded files can be returned based on the common stat/lstat tests.
       Please note the obvious caveats, however: asking for a list of directories will fail to list directories
       if the effective user does not have privileges to read the parent directory, etc.  This is no different
       than performing '-d', etc., directly.  If you care about privilege/permission issues you shouldn't use
       these methods.

       An additional method (recurse) falls outside of what a globbing construct should do, but it seemed too
       useful to leave out.

       This  software  is  free  software.   Similar to Perl, you can redistribute it and/or modify it under the
       terms of either:

         a)     the GNU General Public License
                <https://www.gnu.org/licenses/gpl-1.0.html> as published by the
                Free Software Foundation <http://www.fsf.org/>; either version 1
                <https://www.gnu.org/licenses/gpl-1.0.html>, or any later version
                <https://www.gnu.org/licenses/license-list.html#GNUGPL>, or
         b)     the Artistic License 2.0
                <https://opensource.org/licenses/Artistic-2.0>,

       subject to the following additional term:  No trademark rights to "Paranoid" have been  or  are  conveyed
       under  any  of  the  above  licenses.  However, "Paranoid" may be used fairly to describe this unmodified
       software, in good faith, but not as a trademark.

       (c)  2005  -  2020,  Arthur  Corliss  (corliss@digitalmages.com)  (tm)  2008  -   2020,   Paranoid   Inc.
       (www.paranoid.com)

perl v5.38.2                                       2024-03-07                                Paranoid::Glob(3pm)

       Paranoid::Glob - Paranoid Glob objects

new
           $obj = Paranoid::Glob->new(
                  globs       => [ qw(/lib/* /sbin/* /etc/foo.conf) ],
                  literals    => [ qw(/tmp/{sadssde-asdfak}) ],
                  );

       This class method creates a Paranoid::Glob object.  It can be constructed with optional literal strings
       and/or globs to expand.  All are filtered through a [[:print:]] regex for detainting.  Any undefined or
       zero-length strings are silently removed from the arrays.

       The object reference is a blessed array reference, which is populated with the expanded (or literal)
       globs, making it easy to iterate over the final list.

       If any entry in the globs array fails to detaint this method will return undef instead of an object
       reference.

   addGlobs
           $rv = $obj->addGlobs(qw(/etc/* /bin/*));

       Adds more globs to the object that are detainted and filtered through bsd_glob.  Returns false if any
       strings fail to detaint.  All undefined or zero-length strings are silently removed.

   addLiterals
           $rv = $obj->addLiterals(qw(/etc/foo.conf));

       Adds more literal strings to the object that are detainted.  Returns false if any strings fail to
       detaint.  All undefined or zero-length strings are silently removed.

   consolidate
           $obj->consolidate;

       This method removes redundant entries and lexically sorts the contents of the glob.

   exists
           @existing       = $obj->exists;

       This object method returns a list of all entries that currently exist on the filesystem.  In the case of
       a symlink that exists but links to a nonexistent file it returns the symlink as well.

   readable
           @readable       = $obj->readable;

       This method returns a list of all entries that are currently readable by the effective user.  In the case
       of a symlink it returns the symlink only if the target of the symlink is readable, just as a normal stat
       or -r function would.

   writable
           @writable       = $obj->writable;

       This method returns a list of all entries that are currently writable by the effective user.  In the case
       of a symlink it returns the symlink only if the target of the symlink is writable, just as a normal stat
       or -w function would.

   executable
           @executable     = $obj->executable;

       This method returns a list of all entries that are currently executable by the effective user.  In the
       case of a symlink it returns the symlink only if the target of the symlink is executable, just as a
       normal stat or -x function would.

   owned
           @owned          = $obj->owned;

       This method returns a list of all entries that are currently owned by the effective user.  In the case of
       a symlink it returns the symlink only if the target of the symlink is owned, just as a normal stat or -o
       function would.

   directories
           @directories    = $obj->directories;

       This method returns a list of all the directories.  In the case of a symlink it returns the symlink if
       the target of the symlink is a directory, just as a normal stat or -d function would.

   files
           @files          = $obj->files;

       This method returns a list of all the files.  In the case of a symlink it returns the symlink if the
       target of the symlink is a file, just as a normal stat or -f function would.

   symlinks
           @symlinks       = $obj->symlinks;

       This method returns a list of all the symlinks.

   pipes
           @pipes          = $obj->pipes;

       This method returns a list of all the pipes.  In the case of a symlink it returns the symlink if the
       target of the symlink is a pipe, just as a normal stat or -p function would.

   sockets
           @sockets        = $obj->sockets;

       This method returns a list of all the sockets.  In the case of a symlink it returns the symlink if the
       target of the symlink is a socket, just as a normal stat or -S function would.

   blockDevs
           @blockDevs      = $obj->blockDevs;

       This method returns a list of all the block device nodes.  In the case of a symlink it returns the
       symlink if the target of the symlink is a block device node, just as a normal stat or -b function would.

   charDevs
           @charDevs       = $obj->charDevs;

       This method returns a list of all the character device nodes.  In the case of a symlink it returns the
       symlink if the target of the symlink is a character device node, just as a normal stat or -c function
       would.

   recurse
           $obj->recurse;
           $obj->recurse(1);
           $obj->recurse(1, 1);

       This method with recursively load all filesystem entries underneath any directories already listed in the
       object.  It returns true upon completion, or false if any errors occurred (such as Permission Denied).

       Two optional boolean arguments can be passed to it:

         Option1:        Follow Symlinks
         Option2:        Include "Hidden" directories

       Both options are false by default.  If Option1 (Follow Symlinks) is true any symlinks pointing to
       directories will be recursed into as well.  Option2 in its default false setting excludes dot files or
       directories just as normal shell expansion would.  Setting it to true causes it to include (and recurse
       into) hidden files and directories.

           $obj = Paranoid::Glob->new(
                  globs       => [ qw(/lib/* /sbin/* /etc/foo.conf) ],
                  literals    => [ qw(/tmp/{sadssde-asdfak}) ],
                  );

           print "Expanded globs:\n\t", join("\n\t", @$obj);

           $rv = $obj->addGlobs(qw(/etc/* /bin/*));
           $rv = $obj->addLiterals(qw(/etc/foo.conf));

           $obj->consolidate;

           @existing       = $obj->exists;
           @readable       = $obj->readable;
           @writable       = $obj->writable;
           @executable     = $obj->executable;
           @owned          = $obj->owned;
           @directories    = $obj->directories;
           @files          = $obj->files;
           @symlinks       = $obj->symlinks;
           @pipes          = $obj->pipes;
           @sockets        = $obj->sockets;
           @blockDevs      = $obj->blockDevs;
           @charDevs       = $obj->charDevs;

           $obj->recurse(1, 1);

       $Id: lib/Paranoid/Glob.pm, 2.10 2022/03/08 00:01:04 acorliss Exp $