Updated 5/22/2002, 1:27:11 AM The code: Futils.pm (a file handling utilities code library) @Futils::ISA qw( Handy::DANDY ) and implements expt_handler.pm as well Get each module in the packaged archive format of your preference at Each distribution (zip, tar.gz, tar.bz2) will contain the following files: Futils-docs.txt <-- this file Futils_tests.pl <-- run this script to test Futils on your system Futils.pm expt_handler.pm Handy/Dandy.pm ================================================== HOW TO INVOKE THE FILE UTILITIES LIBRARY -------------------------------------------------- use Futils; my($futils) = Futils->new(); ================================================== HOW TO READ FILES -------------------------------------------------- =============================================== GET FILE CONTENTS AS A STRING ----------------------------------------------- my($filecontents) = $futils->load_file('../path/to/your.file'); =============================================== GET FILE CONTENTS LINE BY LINE ----------------------------------------------- my(@filelines) = $futils->load_file('../path/to/your.file','--as-list'); =============================================== CHANGE DEFAULT MAXIMUM LIMIT (in bytes) FOR FILE READS ----------------------------------------------- $Futils::readlimit = 15000000; # reads files only 15 megs or smaller. # the default is 10 megs =============================================== LOAD THE CONTENTS OF EACH FILE IN A DIRECTORY INTO A HASHREF ----------------------------------------------- ...where the keys are the names of each file and the values of the keys are the contents of each file as strings. The readlimit argument (see above) will apply to every file individually when loaded. Adjust the readlimit as necessary. my($files) = $futils->load_dir('directory/to/load/up/'); ...that creates a hashref that looks like this, supposing that the files in the loaded directory were named 'a.txt', 'b.html', 'c.dat', and 'd.conf'... $files = { 'a.txt' => "everything found in the file a.txt", 'b.html' => "everything found in the file b.html", 'c.dat' => "everything found in the file c.dat", 'd.conf' => "everything found in the file d.conf", }; =============================================== LOAD THE CONTENTS OF EACH FILE IN A DIRECTORY INTO AN ARRAY ----------------------------------------------- my(@files) = $futils->load_dir('directory/to/load/','--as-list'); ...where the contents of each file are members of the list, located at the indicie pertaining to the order of the files sorted alphabetically by name, as returned by sort() =============================================== LOAD THE CONTENTS OF EACH FILE IN A DIRECTORY INTO A LISTREF ----------------------------------------------- my($files) = $futils->load_dir('directory/to/load/','--as-listref'); ...where the contents of each file are members of the list, located at the indicie pertaining to the order of the files sorted alphabetically by name, as returned by sort() =============================================== GET NUMBER OF LINES IN A FILE ----------------------------------------------- my($lines) = $futils->lines_in_file('./directory/or/filename'); ================================================== HOW TO WRITE TO FILES: -------------------------------------------------- =============================================== CREATE AND WRITE TO A NEW FILE: ----------------------------------------------- $futils->write_file ( 'filename' => '../path/to/new.file', 'content' => $new_content, 'mode' => 'write', ); =============================================== OVERWRITE AN EXISTING FILE (the same as above) ----------------------------------------------- $futils->write_file ( 'filename' => 'path/to/existing.file', 'content' => $new_content, 'mode' => 'write', ); =============================================== APPEND TO A FILE: ----------------------------------------------- $futils->write_file ( 'filename' => '/path/to/existing.file', 'content' => $new_content, 'mode' => 'append', ); =============================================== CLEAR THE CONTENTS OF A FILE ----------------------------------------------- $futils->ftruncate('./delete/everything/inthis.file'); =============================================== ALLOW EMPTY WRITES ----------------------------------------------- (Futils won't let you open a file for writing unless you provide the content. You can allow empty writes by doing this) $Futils::empty_writes = 0; ================================================== HOW TO GET AN OPEN FILEHANDLE: -------------------------------------------------- NOTE: 'mode' arguments passed to write_file() and open_to_FH() can be either 'write' or 'append'. without a mode argument a mode of 'write' is assumed =============================================== OPEN FILEHANDLE FOR WRITING ON A FILE ----------------------------------------------- $futils->open_to_FH ( 'filename' => './make_new/or/use_existant.file', 'mode' => 'write,' ); =============================================== OPEN FILEHANDLE FOR APPENDING TO A FILE ----------------------------------------------- $futils->open_to_FH ( 'filename' => './make_new/or/use_existant.file', 'mode' => 'append' ); ================================================== HOW TO COPY A FILE: -------------------------------------------------- $futils->write_file ( 'filename' => 'path/to/copyof.file', 'content' => $futils->load_file('/file/to.copy'), 'mode' => 'write', ); %=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=% % NOTE ON FILE LOCKING WITH flock() % - - - - - - - - - - - - - - - - - - - - % flock() is automatically implemented in all read/write operations % performed by Futils based on whether or not your system supports it. % You can bypass the locking on read/write operations by passing the % option '--no-flock' when you call load_file(), write_file(), % open_to_FH(), and load_dir(). flock is not used when calling % lines_in_file() % % the use of flock() can be globally disabled in all Futils I/O by % passing the option '--no-flock' in when you invoke Futils.pm % my($futils) = Futils->new('--no-flock'); % % if your system does not support flock() it will not cause fatal % errors or warnings to occur when you use Futils.pm The use of % flock() is silently bypassed in such circumstances. You can % test for yourself to see if flock() is supported by your system % by calling the 'can_flock' method. % my($system_supports_flock) = $futils->can_flock(); % % OPTIONS ON I/O RACE CONDITION POLICY % set @Futils::onflockfail to any of the following strings: % % --fatal fails with stack trace % --fail same as above % --warn warns() about the error with a stack trace % --ignore ignores the failure to get an exclusive lock % --undef returns undef % --0 returns 0 % --wait* waits to try getting an exclusive lock % --block* same as above % % ex.- @Futils::onflockfail = qw( wait fail ); % % * used in tandem with another option. You must specify another option to % fall back on if blocking should fail. Otherwise Futils will throw a fatal % error and dump a stack trace before exiting the process with a 0 status. %=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=% ================================================== HOW TO TELL IF FILE LOCKING IS SUPPORTED BY YOUR SYSTEM -------------------------------------------------- my($can_use_flock) = $futils->can_flock(); ================================================== HOW TO USE THE RIGHT DIRECTORY PATH SEPERATOR -------------------------------------------------- this is different on windows, mac, EBCDIC, linux/unix, vms, etc my($correct_SL) = $futils->SL(); ================================================== HOW TO USE THE RIGHT NEWLINE CHARACTER -------------------------------------------------- this varies from system to system as well my($newline) = $futils->n(); ================================================== HOW TO LIST DIRECTORIES -------------------------------------------------- my(@files_in_dir) = $futils->list_dir('/directory/name'); NOTE: All Futils functions/methods which pertain to the listing of directories may be combined as desired. Options are: --files-only --dirs-only --with-paths --sl-after-dirs --follow or --recurse --no-fsdots --as-ref --dirs-as-ref --files-as-ref --no-fancy * --raw * * pertains only to print_dir() =============================================== HOW TO LIST A DIRECTORY WITH THE PATHNAMES OF ITS FILES ----------------------------------------------- my(@files_w_paths) = $futils->list_dir('/directory/name'); =============================================== HOW TO LIST A DIRECTORY WITH IT'S FILES ONLY ----------------------------------------------- my(@files) = $futils->list_dir('/directory/name', '--files-only'); =============================================== HOW TO LIST A DIRECTORY WITH IT'S SUBDIRECTORIES ONLY ----------------------------------------------- my(@dirs) = $futils->list_dir('/directory/name', '--dirs-only'); =============================================== HOW TO LIST A DIRECTORY WITH NO '..' or '.' ENTRIES ----------------------------------------------- my(@files) = $futils->list_dir('/directory/name', '--no-fsdots'); =============================================== HOW TO PRETTY-PRINT A DIRECTORY ----------------------------------------------- print($futils->print_dir('/directory/name')); This renders a directory listing that looks something like this: +-----------------------------+ | Directory listing for /home +-----------------------------+ | . | .. | .cpan/ | .ssh/ | mail/ | apache-conf/ | oneliners/ | .bash_history | .perltidyrc +-----------------------------+ =============================================== HOW TO MAKE A DIRECTORY (ONE OR MANY RECURSIVELY) ----------------------------------------------- $futils-> makedir('./new/directory/and/maybe/some/others/inside/it',[bitmask]); NOTE: bitmask is the permission's mode. eg- 0755, 0664, etc. this is merged with the effective UID of the current process ================================================== HOW TO GET FILE ATTRIBUTES -------------------------------------------------- =============================================== GET A FILE'S LAST MODIFIED DATE/TIME ----------------------------------------------- my($lastmod) = $futils->last_mod('./directory/or/filename',[format]); NOTE: If you want the time in human-readable format, the optional [format] argument is one of these strings, where each is listed with the format of the timestamp it renders --short 5/15/02, 4:22 pm --formal Saturday, June 15, 2002, 4:22 pm --long same as '--formal' --succinct Sat 5/15/02 16:22:43 --ISO Sat, 15 Jun 2002 16.22.43 GMT --filename -June-15-2002-16.22.43 --file same as '--filename' --mdy 5/15/02 --hm 4:22 pm --hms 4:22:43 pm --24hms 16:22:43 --dayofmonth 15 --dayofyear 134 (1 - 365) --dayofweek Saturday --dayofweek, --num 7 --month June --month, --num 6 --year 2002 --shortyear 02 --minute 22 --hour 16 (0 - 24) --second 43 Without the [format] argument this will return the last modified time of the file in seconds as an offset of localtime(time). This pertains to all other functions/methods that have to do with the time-sensitive attributes of a file. =============================================== GET A FILE'S CREATION TIME ----------------------------------------------- my($created) = $futils->created('./directory/or/filename',[fmt]); =============================================== GET A FILE'S LAST ACCESSED TIME ----------------------------------------------- my($lastaccss) = $futils->last_access('./directory/or/filename',[fmt]); =============================================== GET FILE TYPE ----------------------------------------------- my($ftype) = $futils->file_type('./directory/or/filename',[fmt]); =============================================== GET FILE SIZE ----------------------------------------------- my($size) = $futils->fsize('./directory/or/filename',[fmt]); ================================================== MISCELLANEOUS -------------------------------------------------- =============================================== ESCAPE FILENAME TO A SINGLE STRING (for saving file uploads mainly) ----------------------------------------------- my($upload_name) = $futils->escape_filename('./directory/or/filename'); =============================================== STRIP THE PATH FROM A FILE NAME ----------------------------------------------- my($file) = $futils->strip_filename('strip/path/leave/last/filename');