UCS::File - File access utilities
use UCS::File;
## open filehandle for reading or writing
# automagically compresses/decompresses files and dies on error
$fh = UCS::File::Open("> my_file.gz");
# the same without error checks (may return undefined value)
$fh = UCS::File::TryOpen("> my_file.bz2");
## temporary file objects (disk files are automatically removed)
$t1 = new UCS::File::Temp; # picks a unique filename
$t2 = new UCS::File::Temp "mytemp"; # extends prefix to unique name
$t3 = new UCS::File::Temp "mytemp.gz"; # compressed temporary file
$filename = $t1->name; # full pathname of temporary file
$t1->write(...); # works like $fh->print() ;
$t1->finish; # stop writing file
print $t1->status, "\n"; # WRITING/FINISHED/READING/DELETED
# main program can read or overwrite file <$filename> now
$line = $t1->read; # read one line (like $fh->getline())
$t1->rewind; # re-read from beginning of file
$line = $t1->read; # (reads first line again)
$t1->close; # stop reading and remove temporary file
# other files will be removed when objects $t2 and $t3 are destroyed
## execute shell command with error detection
$cmd = "ls -l";
$errlevel = UCS::File::ShellCmd($cmd); # dies with error message if not ok
$UCS::File::Paranoid = 1; # more paranoid checks (-1 for less paranoid)
# $errlevel == 0 (ok), 1 (minor problems), ..., 6 (fatal error)
UCS::File::ShellCmd($cmd, \@lines); # capture standard output in array
UCS::File::ShellCmd($cmd, "file.txt"); # ... or in file (for large amounts of data)
UCS::File::ShellCmd(["ls", "-l", @files], \@lines); # bypass shell expansion
This module provides some useful routines for handling files and external programs. This includes opening files with error checks and automagical compression/decompression, temporary file objects that are automatically created and deleted, and the execution of shell commands with extensive error checks.
>
, the file is opened for writing (an existing file will be overwritten). If $name starts with >>
, the file is opened for appending..Z
, .gz
, and .bz2
are automagically compressed and decompressed, provided that the necessary tools are installed. It is also possible to append to .gz
and .bz2
files."... |"
or "| ..."
, respectively), which is passed directly to the built-in open command. It is thus subject to shell expansion and does not support automagic compression and decompression.open()
call fails.Temporary files (implemented by UCS::File::Temp objects) are assigned a unique name and are automatically deleted when the script exits. The life cycle of a temporary file consists of four stages: create, write, read (possibly re-read), delete. This cycle corresponds to the following method calls:
$tf = new UCS::File::Temp; # create new temporary file in /tmp dir
$tf->write(...); # write cycle (buffered output, like print function)
$tf->finish; # complete write cycle (flushes buffer)
$line = $tf->read; # read cycle (like getline method for FileHandle)
[$tf->rewind; # optional: start re-reading temporary file ]
[$line = $tf->read; ]
$tf->close; # delete temporary file
Once the temporary file has been read from, it cannot be re-written; a new UCS::File::Temp object has to be created for the next cycle. When the write stage is completed (but before reading has started, i.e. after calling the finish method), the temporary file can be accessed and/or overwritten by external programs. Use the name method to obtain its full pathname. If no direct access to the temporary file is required, the finish method is optional. The write cycle will automatically be completed before the first read method call.
/
character, it is interpreted as an absolute or relative path, and the temporary file will not be created in the /tmp directory. To create a temporary file in the current working directory, use ./MyPrefix
..Z
, .gz
, or .bz2
to $prefix in order to create a compressed temporary file. The actual filename (as returned by the name method) will have the same extension in this case. $tf = new UCS::File::Temp;
$tf->finish; # temporary file has size of 0 bytes now
$filename = $tf->name;
system "$my_shell_command > $filename";
The UCS::File::ShellCmd function provides a convenient replacement for the built-in system command. Standard output and error messages produced by the invoked shell command are captured to avoid screen clutter. The collected standard ouput of the command can optionally be returned to the caller (similar to the backtick operator `$shell_cmd`
). UCS::File::ShellCmd also checks for a variety of error conditions and returns an error level ranging from 0 (successful) to 6 (fatal error):
Error Level Description
6 command execution failed (system error)
5 non-zero exit value or error message on STDERR
4 -- reserved for future use --
3 warning message on STDERR
2 any output on STDERR
1 error message on STDOUT
Depending on the value of $UCS::File::Paranoid and the error level, a warning message may be issued or the function may die with an error message.
[$program, @args]
instead: $errlvl = UCS::File::ShellCmd(["ls", "-l", @files], \@lines);
Copyright 2003 Stefan Evert.
This software is provided AS IS and the author makes no warranty as to its use and performance. You may use the software, redistribute and modify it under the same terms as Perl itself.