Paranoid::Glob(3pm)

📦
version 2.10 · 3 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 Paranoid::Glob 💖

okay bestie so this is Paranoid::Glob from the 3pm manual — the Perl User Contributed Perl Documentation pages, and it's giving very useful, ngl.

✨ VERSION ✨

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

🌸 SYNOPSIS 🌸

$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);

like, that's the whole vibe right there 💅

🦋 DESCRIPTION 🦋

so the main character energy of these objects is that they let you detaint a whole list of files and/or directories super easily while also doing shell expansion of the names. iconic, right? but there's a caveat, and bestie you gotta hear it: if a given file or directory name actually exists on the file system as a literal string (even if it's got shell expansion characters in it), it gets added as such. it only goes through bsd_glob if it doesn't exist on the file system. periodt.

you can also make these objects with instructions to explicitly treat every single name as a literal string. so you have options, you're not trapped.

any undef or zero-length strings that get passed in the files array? silently removed. gone. not invited to the party 🙈

and as a lil convenience, you can get subsets of the expanded files back based on the common stat/lstat tests. but pls note the obvious caveats: asking for a list of directories will fail to list directories if the effective user doesn't have privileges to read the parent directory, etc. it's no different than performing -d, etc., directly. if you care about privilege/permission issues you shouldn't use these methods. fr fr.

there's one extra method (recurse) that honestly falls outside what a globbing construct should even do, but it seemed way too useful to leave out. no regrets.

👑 SUBROUTINES/METHODS 👑

🌟 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. you can construct it with optional literal strings and/or globs to expand. everything gets filtered through a [[:print:]] regex for detainting. any undefined or zero-length strings are silently removed from the arrays — bye 👋

the object reference is a blessed array reference, populated with the expanded (or literal) globs, which makes it so easy to iterate over the final list. chef's kiss.

and heads up: if any entry in the globs array fails to detaint, this method returns undef instead of an object reference. so check that return value, bestie, don't just assume.

🌟 addGlobs

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

adds more globs to the object, 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, 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. tidying up? we love to see it ✨

🌟 exists

@existing       = $obj->exists;

returns a list of all entries that currently exist on the filesystem. and for a symlink that exists but links to a nonexistent file? it returns the symlink too. loyal to the broken ones, honestly.

🌟 readable

@readable       = $obj->readable;

returns a list of all entries currently readable by the effective user. for a symlink it returns the symlink only if the target of the symlink is readable, exactly like a normal stat or -r function would.

🌟 writable

@writable       = $obj->writable;

returns a list of all entries currently writable by the effective user. for a symlink it returns the symlink only if the target of the symlink is writable, exactly like a normal stat or -w function would.

🌟 executable

@executable     = $obj->executable;

returns a list of all entries currently executable by the effective user. for a symlink it returns the symlink only if the target of the symlink is executable, exactly like a normal stat or -x function would.

🌟 owned

@owned          = $obj->owned;

returns a list of all entries currently owned by the effective user. for a symlink it returns the symlink only if the target of the symlink is owned, exactly like a normal stat or -o function would.

🌟 directories

@directories    = $obj->directories;

returns a list of all the directories. for a symlink it returns the symlink if the target of the symlink is a directory, exactly like a normal stat or -d function would.

🌟 files

@files          = $obj->files;

returns a list of all the files. for a symlink it returns the symlink if the target of the symlink is a file, exactly like a normal stat or -f function would.

@symlinks       = $obj->symlinks;

returns a list of all the symlinks. just the symlinks, nothing extra.

🌟 pipes

@pipes          = $obj->pipes;

returns a list of all the pipes. for a symlink it returns the symlink if the target of the symlink is a pipe, exactly like a normal stat or -p function would.

🌟 sockets

@sockets        = $obj->sockets;

returns a list of all the sockets. for a symlink it returns the symlink if the target of the symlink is a socket, exactly like a normal stat or -S function would.

🌟 blockDevs

@blockDevs      = $obj->blockDevs;

returns a list of all the block device nodes. for a symlink it returns the symlink if the target of the symlink is a block device node, exactly like a normal stat or -b function would.

🌟 charDevs

@charDevs       = $obj->charDevs;

returns a list of all the character device nodes. for a symlink it returns the symlink if the target of the symlink is a character device node, exactly like a normal stat or -c function would.

🌟 recurse

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

this method recursively loads all filesystem entries underneath any directories already listed in the object. it returns true upon completion, or false if any errors occurred (like 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 like normal shell expansion would. setting it to true causes it to include (and recurse into) hidden files and directories. so if you want the hidden stuff, you gotta ask for it 💅

🎀 DEPENDENCIES 🎀

  • Carp
  • Errno
  • Fcntl
  • File::Glob
  • Paranoid
  • Paranoid::Debug

💀 BUGS AND LIMITATIONS 💀

bestie. there is literally nothing here. the section exists, it's just… empty. no bugs listed, no limitations listed. we're manifesting ✨

🫶 AUTHOR 🫶

Arthur Corliss (corliss@digitalmages.com)

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

  1. 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
  2. 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)

and that's the whole page, bestie 💖 this came from the Paranoid::Glob(3pm) page, perl v5.38.2, dated 2024-03-07. go detaint something responsibly 🧚✨

📦 where this page comes from