NetSDS...::File(3pm)

💖 NetSDS::Util::File 💖

okay bestie, welcome to NetSDS...::File(3pm) — yes that's the page, she's a Perl module from the User Contributed Perl Documentation era and she is serving. Sit down, grab a strawberry 🍓, and let's get into it.

---

✨ NAME ✨

NetSDS::Util::File — file related utilities 🗂️✨

lowkey the whole personality is "I do things to files and directories so you don't have to."

---

🌸 SYNOPSIS 🌸

here's the vibe in three lines, no notes:

use NetSDS::Util::File qw(file_read);

my $passwd = file_read('/etc/passwd');

file_move('/etc/passwd', '/tmp/find_this');

see? import what you need, read a file into a scalar, move a file. iconic behaviour. 💅

---

🦋 DESCRIPTION 🦋

NetSDS::Util::File is the friend who handles all your files-and-directories admin: creating, reading, writing, copying and moving files and catalogs. she's got the whole to-do list covered, fr fr. 📁💖

and obviously — of course — she's standing on the shoulders of legends. this module uses well known things like File::Spec, File::Path, File::Copy and others. no reinventing the wheel here, we're just making it cute. 🎀

---

👑 EXPORTED FUNCTIONS 👑

the main characters. one by one. let's go. 🫶

• is_handle($var) — check if argument is a file handle
  • Parameters: some variable
  • Returns: 1 if it's file handle or undef otherwise

vibe check on your variable. does she handle files or does she not:

if (is_handle($var)) {

        reset_handle($fh);

}

• reset_handle($fh) — reset file handle
  • Parameters: file handle
  • Returns: nothing

this function tries to set the filehandle to the begin of file and set binmode on it. like hitting rewind on the playlist 🔁

my $fh = file_open('/etc/passwd');
...
do something with file
...
reset_handle($fh); # We can read it from the beginning

yes bestie, that comment is the entire point — after resetting you can read it from the beginning again. periodt.

• file_open($file) — open file
  • Parameters: file name or file handle
  • Returns: file handle

this function provides unified API for opening files. one function, every file, no drama. 💅

my $f = file_open('/etc/passwd');

• file_read($file) — read file to scalar
  • Parameters: file name or file handle
  • Returns: scalar content of file

this function provides ability to read file content to scalar variable. whole file, one scalar, slay. 📖✨

my $data = file_read('/etc/passwd');

print "Passwords file: $data\n";

• file_write($file, $data) — write scalar data to file
  • Parameters: file name or open file handle
  • Returns: length of written data or undef in case of error

my $data = 'This should be file';

file_write('/tmp/file.dat', $data);

she tells you exactly how many characters she wrote. transparency queen. 👑

• file_copy($in_file, $out_file) — copy file
  • Parameters: input file name, output file name
  • Returns:

this function copy file to new location. two of everything now, bestie — the original and her clone. 🧚

• file_move($in_file, $out_file) — move file
  • Parameters: input file name, output file name
  • Returns: 1 or undef

this function moves old file to new location. she's not duplicated, she's relocated. 🚚

• file_temp($dir) — create temporary file

Creates new temp file and return its handle. little baby file, here for a good time not a long time. 🍼

• dir_create($dir) — create directory with parents
  • Parameters: directory name
  • Returns: directory name or undef

# Will create all parent catalogs if necessary

dir_create('/var/log/NetSDS/xxx');

she builds the whole family tree of directories, not just the leaf. generational wealth but for folders. 🌳💖

• dir_delete($dir) — remove directory recursive
  • Parameters: directory name
  • Returns: dir name or undef if error

print "We need no libs!";

dir_delete('/usr/lib');

⚠️ bestie this is recursive and that example is literally deleting /usr/lib. read it twice. scream once. 😭

• dir_read($dir, $ext) — read files list from catalog
  • Parameters: directory name, extension of files to read
  • Returns: list of files in catalog

my @logs = @{ dir_read('/var/log/httpd', 'log') };

print "Logs are: " . join (', ', @logs);

note the @{ ... } — she hands you back an arrayref, so deref it. iykyk. ✨

• dir_read_recursive($dir, $ext, [$res]) — read all files list recursive
  • Parameters: $start catalog, $extension
  • Returns: list of files with extension from parameters

she goes deep. every subdirectory, every corner, all the files with that extension. 🕵️‍♀️

my $tpls = dir_read_recursive('/etc/NetSDS', 'tmpl');

foreach my $tpl (@$tpls) {

        pritn "Template: $tpl\n";

}

(yes, pritn is right there in the docs and no, i will not be fixing her typo, i respect her too much 😭)

• exec_external($prog, [$param1, ... $paramN]) — execute external program
  • Parameters: pragram name, arguments list (see perldoc -f system)
  • Returns: 1 if ok, undef otherwise

this function calls system() with given parameters and returns 1 if everything happened correctly (program executed and returned correct result). 💀

if (exec_external('/bin/rm', '-rf', '/')) {

        print "Hey! We removed the world!";

}

⚠️ THAT EXAMPLE. /bin/rm -rf /. that is not a drill bestie, that's the whole filesystem. also remember she's wrapping system() so the args go in as a list — go read perldoc -f system like she told you. 🙈

---

🌈 EXAMPLES 🌈

None yet

ngl, zero examples. she's mysterious like that. 🎀

---

💀 BUGS 💀

Unknown yet

no known bugs. we're choosing to believe her. 🫶

---

🌟 SEE ALSO 🌟

go hang out with the rest of the friend group: IO::Handle, IO::Scalar, IO::File, File::Spec, File::Copy, File::Path, system()

---

🎯 TODO 🎯

1. Implement more detailed error handling

one item on the vision board. we love a girl with goals. 💜

---

💖 AUTHOR 💖

Valentyn Solomko <pere@pere.org.ua>

Michael Bochkaryov <misha@rattler.kiev.ua>

---

and that's the whole page, bestie!! 🎀✨ this was perl v5.36.0, dated 2022-11-20, straight out of the User Contributed Perl Documentation. read your docs, stay recursive, and please never rm -rf / — mwah 💅💖🌸