Config::Manager::File - Basic File Utilities (for Tools)
use Config::Manager::File qw( UniqueTempFileName ConvertFromHost ConvertToHost CompareFiles CopyFile MoveByCopying MD5Checksum ReadFile WriteFile AppendFile ConvertFileWithCallback SerializeSimple ); use Config::Manager::File qw(:all); $tempfilename = &UniqueTempFileName(); &ConvertFromHost($targetfile,$sourcefile,$linenumbering,$purgeblanks); &ConvertToHost($targetfile,$sourcefile,$linenumbering,$purgeblanks,$checklength); $same = &CompareFiles($file1,$file2); &CopyFile($source,$target); &MoveByCopying($source,$target); $checksum = &MD5Checksum($source); $arrayref = &ReadFile($source); &WriteFile($target,@contents); &AppendFile($target,$source); &ConvertFileWithCallback($target,$source,$callback); $printable = &SerializeSimple("varname",$datastructure);
$tempfilename = &UniqueTempFileName();
Generates a unique temporary file name with an absolute path (in the temporary directory which has been configured in the user's or the global configuration file).
The file itself is NOT created by this function.
The file name is composed of the "scope" (as passed to the "Config::Manager::Conf::init()" method during global initialization) followed by the day of year (000 to 364 or 365), the hour, minutes, seconds, the process ID, a running number and terminates with ".tmp".
.tmp
All temporary files created in this manner are automatically deleted at shutdown time of the Perl interpreter (if they still exist). So you need not worry about deleting any of your temporary files, but you may do so if you wish.
&ConvertFromHost($targetfile,$sourcefile,$linenumbering,$purgeblanks);
Converts the given input file after it has been fetched from a mainframe.
The original input file is NEVER altered in any way. A new file (whose name "$targetfile" is given) is written instead.
$targetfile
"$targetfile" must be a valid filename; beware that it will be overwritten if it already exists!
"$sourcefile" is the input file's name (and path), "$linenumbering" is a flag (0 = "no", 1 = "yes") indicating whether line numbers shall be removed from the beginning of each line, and "$purgeblanks" is a flag (0 = "no", 1 = "yes") indicating whether trailing whitespace is to be purged from each line.
$sourcefile
$linenumbering
$purgeblanks
Any sequences of "Carriage Return" and "Line Feed" characters (ASCII hexadecimal 0x0D and 0x0A) at the end of lines are converted to the end-of-line character sequence of the current operating system.
Returns true on success or "undef" in case of error (error messages are written to the log file and put on hold for possible output to the screen).
Possible warning messages will also be written to the log file and to STDERR.
This happens for instance if a line does not begin with 6 digits when the "$linenumbering" option is enabled, or if there was a problem closing the input file, or if a needed configuration constant was unavailable.
&ConvertToHost($targetfile,$sourcefile,$linenumbering,$purgeblanks,$checklength);
Converts the given input file so that it can be sent to a host mainframe.
"$sourcefile" is the input file's name (and path), "$linenumbering" is a flag (0 = "no", 1 = "yes") indicating whether line numbers shall be prepended to each line, "$purgeblanks" is a flag (0 = "no", 1 = "yes") indicating whether trailing whitespace is to be removed from each line, and "$checklength" is a flag (0 = "no", 1 = "yes") signaling whether lines should be checked for correct length (a warning message will be issued if the maximum COBOL line length (66 columns) is exceeded by any line).
$checklength
This happens for instance if a line is longer than the maximum permitted number of characters per line (66) or if there was a problem closing the input file, or if a needed configuration constant was unavailable.
$same = &CompareFiles($file1,$file2);
Compares the contents of two files.
Returns "true" (1) if the files are the same, "false" (0) if they differ, and "undef" in case of any error.
The corresponding error message will be written to the log file and put on hold (for subsequent display on the screen, if desired) in the latter case.
&CopyFile($source,$target);
Copies file "$source" to "$target". Returns "true" (1) on success and "undef" in case of any error.
$source
$target
&MoveByCopying($source,$target);
Copies file "$source" to "$target", then deletes file "$source" if the copy was successful. Returns "true" (1) on success and "undef" in case of any error.
Note that moving WITHOUT copying is performed with Perl's built-in "rename()" function!
BEWARE that moving without copying is not possible across file system boundaries on most Unix systems!
So whenever you are unsure whether you are actually trying to move across a file system boundary or not, better use "MoveByCopying()"!
Otherwise, this can easily lead to sudden errors when directory locations are changed in the configuration!
YOU HAVE BEEN WARNED!
$checksum = &MD5Checksum($source);
Determines the MD5 checksum for file "$source". Returns the checksum (a 16 digit hexadecimal string) on success and "undef" in case of any error.
MD5 is used in cryptography for "fingerprints"; it is guaranteed to differ strongly for slightly altered input (but the reverse is not necessarily true!).
In combination with the file's length, this can be used to uniquely identify files, for instance in the recursive processing of certain files, in order to avoid infinite recursion.
For example as follows ("$file" contains the name and path of the file in question, and "$checksum" contains its checksum):
$file
$checksum
if (defined $filesig{-s $file}{$checksum}) { # file already known } else { # file not encountered yet } $filesig{-s $file}{$checksum}{$file} = 1; # add file to list
$arrayref = &ReadFile($source);
Returns a reference to a Perl array containing the lines of the given file (the input separator "$/" is set to "\n" (line mode) locally before the file is read).
$/
Returns "undef" in case of any error.
BEWARE that the lines returned still have their terminating newline character ("\n"), which you may need to get rid of (e.g. with "chomp")!
&WriteFile($target,@contents);
Writes the given lines of text (or binary data) to the given file.
It is your responsibility to provide newline characters ("\n") as necessary, the lines of text are simply concatenated (without any intervening characters!) and written to the file.
(Therefore this routine is also suitable for binary data!)
You may at your option provide scalars as parameters (which will be written to the file "as is"), or array references, whose contents will be written to the file (also "as is"), or both (mixed).
Example:
@msg = (); push( @msg, "1st line\n" ); push( @msg, "2nd line\n" ); &WriteFile( $target, "Messages:\n\n", \@msg );
Returns "true" (1) on success and "undef" in case of any error.
&AppendFile($target,$source);
Appends file "$source" to file "$target" using binary mode.
&ConvertFileWithCallback($target,$source,$callback);
This is the most flexible method for reading a file, modifying its contents, and writing them to another file.
The file "$source" is read line by line (the input separator "$/" is set to "\n" (line mode) locally before the file is opened), and for each line, a callback function (provided by you) is called.
Your callback function should expect two parameters: First, the line just read, and second, this line's line number (you may not need the line number, though, and can safely ignore it).
After processing the line, your callback function should return the modified line or "undef".
The returned value is then written to the given "$target" file, provided that the return value is not "undef". If the callback function's return value is "undef", nothing is printed to the output file. (This way, you can delete certain lines from a file!)
BEWARE that the lines passed to the callback function still have their terminating newline character ("\n"), which you may need to get rid of (e.g. with "chomp") first and back on before returning the line!
Example of use:
$cb = sub { my($l) = @_; $l =~ s!\s+$!!; "$l\n"; }; &ReportErrorAndExit unless (defined &ConvertFileWithCallback($target,$source,$cb));
The function returns "true" (1) on success and "undef" in case of any error.
$printable = &SerializeSimple("varname",$datastructure);
This function takes the name of a variable and the variable itself as arguments, the latter of which is usually a reference to some data structure.
The function returns a reference to an array which contains lines that can be printed to the screen or a file. This reference can also be passed to the "WriteFile()" function, which will automatically write the lines in the array to the indicated file.
WriteFile()
Note that the elements of this array already DO have "newline" characters ("\n") at the end of each line.
\n
As the name of this function indicates, it can only handle simple data structures consisting of SCALARs, ARRAYs, HASHes and REFerences thereof, but no objects, regular expressions, closures or external data structures.
(See Data::Dumper(3) for a more complete solution.)
Moreover, it cannot handle self-references and will enter an infinite loop if any self-references are encountered (this will provoke a "deep recursion" warning message printed to the screen).
The printable lines returned are valid Perl code which can be read back in later from a file using "require" or "eval".
require
eval
The name of the variable provided here will then determine which variable the data structure will be assigned to.
Note that you can set this variable name to anything you like (but your program which reads back the data structure will have to know in advance which variable name to expect), and remember that you can always fully qualify this variable name in order to force it into any given package you want.
2003_02_05 Steffen Beyer & Gerhard Albers Version 1.0 2003_02_14 Steffen Beyer Version 1.1 2003_04_26 Steffen Beyer Version 1.2
To install Config::Manager, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Config::Manager
CPAN shell
perl -MCPAN -e shell install Config::Manager
For more information on module installation, please visit the detailed CPAN module installation guide.