.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Paranoid::Glob 3pm"
.TH Paranoid::Glob 3pm "2010-05-03" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Paranoid::Glob \- Paranoid Glob objects
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR Glob.pm,v 0.2 2010/04/21 09:07:30 acorliss Exp $
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&    $obj = Paranoid::Glob\->new(
\&           globs       => [ qw(/lib/* /sbin/* /etc/foo.conf) ],
\&           literals    => [ qw(/tmp/{sadssde\-asdfak}) ],
\&           );
\&
\&    print "Expanded globs:\en\et", join("\en\et", @$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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
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 \fBbsd_glob\fR if it does not exist on the file system.
.PP
The objects can also be created with instructions to explicitly treat all
names as literal strings.
.PP
Any undef or zero-length strings passed in the files array are silently
removed.
.PP
As a convenience subsets of the expanded files can be returned based on the
common \fBstat\fR/\fBlstat\fR 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.
.PP
An additional method (\fBrecurse\fR) falls outside of what a globbing construct
should do, but it seemed too useful to leave out.
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
.SS "new"
.IX Subsection "new"
.Vb 4
\&    $obj = Paranoid::Glob\->new(
\&           globs       => [ qw(/lib/* /sbin/* /etc/foo.conf) ],
\&           literals    => [ qw(/tmp/{sadssde\-asdfak}) ],
\&           );
.Ve
.PP
This class method creates a \fBParanoid::Glob\fR 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.
.PP
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.
.PP
If any entry in the globs array fails to detaint this method will return undef
instead of an object reference.
.SS "addGlobs"
.IX Subsection "addGlobs"
.Vb 1
\&    $rv = $obj\->addGlobs(qw(/etc/* /bin/*));
.Ve
.PP
Adds more globs to the object that are detainted and filtered through
\&\fBbsd_glob\fR.  Returns false if any strings fail to detaint.  All undefined or
zero-length strings are silently removed.
.SS "addLiterals"
.IX Subsection "addLiterals"
.Vb 1
\&    $rv = $obj\->addLiterals(qw(/etc/foo.conf));
.Ve
.PP
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.
.SS "consolidate"
.IX Subsection "consolidate"
.Vb 1
\&    $obj\->consolidate;
.Ve
.PP
This method removes redundant entries and lexically sorts the contents of
the glob.
.SS "exists"
.IX Subsection "exists"
.Vb 1
\&    @existing       = $obj\->exists;
.Ve
.PP
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.
.SS "readable"
.IX Subsection "readable"
.Vb 1
\&    @readable       = $obj\->readable;
.Ve
.PP
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 \fBstat\fR or \fB\-r\fR
function would.
.SS "writable"
.IX Subsection "writable"
.Vb 1
\&    @writable       = $obj\->writable;
.Ve
.PP
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 \fBstat\fR or \fB\-w\fR
function would.
.SS "executable"
.IX Subsection "executable"
.Vb 1
\&    @executable     = $obj\->executable;
.Ve
.PP
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 \fBstat\fR or \fB\-x\fR
function would.
.SS "owned"
.IX Subsection "owned"
.Vb 1
\&    @owned          = $obj\->owned;
.Ve
.PP
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 \fBstat\fR or \fB\-o\fR
function would.
.SS "directories"
.IX Subsection "directories"
.Vb 1
\&    @directories    = $obj\->directories;
.Ve
.PP
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 \fBstat\fR or \fB\-d\fR function would.
.SS "files"
.IX Subsection "files"
.Vb 1
\&    @files          = $obj\->files;
.Ve
.PP
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 \fBstat\fR or \fB\-f\fR function would.
.SS "symlinks"
.IX Subsection "symlinks"
.Vb 1
\&    @symlinks       = $obj\->symlinks;
.Ve
.PP
This method returns a list of all the symlinks.
.SS "pipes"
.IX Subsection "pipes"
.Vb 1
\&    @pipes          = $obj\->pipes;
.Ve
.PP
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 \fBstat\fR or \fB\-p\fR function would.
.SS "sockets"
.IX Subsection "sockets"
.Vb 1
\&    @sockets        = $obj\->sockets;
.Ve
.PP
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 \fBstat\fR or \fB\-S\fR function would.
.SS "blockDevs"
.IX Subsection "blockDevs"
.Vb 1
\&    @blockDevs      = $obj\->blockDevs;
.Ve
.PP
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 \fBstat\fR or \fB\-b\fR function would.
.SS "charDevs"
.IX Subsection "charDevs"
.Vb 1
\&    @charDevs       = $obj\->charDevs;
.Ve
.PP
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 \fBstat\fR or \fB\-c\fR function would.
.SS "recurse"
.IX Subsection "recurse"
.Vb 3
\&    $obj\->recurse;
\&    $obj\->recurse(1);
\&    $obj\->recurse(1, 1);
.Ve
.PP
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 occured (such as Permission Denied).
.PP
Two optional boolean arguments can be passed to it:
.PP
.Vb 2
\&  Option1:        Follow Symlinks
\&  Option2:        Include "Hidden" directories
.Ve
.PP
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.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.IP "o" 4
.IX Item "o"
Carp
.IP "o" 4
.IX Item "o"
Errno
.IP "o" 4
.IX Item "o"
Fcntl
.IP "o" 4
.IX Item "o"
File::Glob
.IP "o" 4
.IX Item "o"
Paranoid
.IP "o" 4
.IX Item "o"
Paranoid::Debug
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
.SH "AUTHOR"
.IX Header "AUTHOR"
Arthur Corliss (corliss@digitalmages.com)
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
This software is licensed under the same terms as Perl, itself. 
Please see http://dev.perl.org/licenses/ for more information.
.PP
(c) 2009, Arthur Corliss (corliss@digitalmages.com)