CONFIG::Plain - Base class for cached file reading
use CONFIG::Plain; my $file = CONFIG::Plain->new($filename, \%config); my $file_content = $file->getfile; while (defined $line = $file->getline) { printf("%s:%d> %s\n", $file->getline_file, $file->getline_number, $line); } # example for error reporting while (defined ($line = $file->getline)) { $error = $file->getline_error; if (defined $error) { printf("ERROR in %s:%d\n", $file->getline_file, $file->getline_number); while ($filename = $file->getline_file) { printf(" included from %s:%d\n", $filename, $file->getline_number); } do { printf(" %s\n", $error); } while (defined ($error = $file->getline_error)); } }
This perl module is highly useful in connection with mod_perl cgi scripts. It caches files (re-reads the files if necessary) to speed up the file reading. It is possible to configure the module to remove comments, trailing blanks, empty lines or to do other useful things only once.
The methods of this module are very similar to the IO methods to read a file. The two major differences are:
If you open/read a file twice (or often) the file will be cached after the first access. So the second (and third, and forth, ...) access is much faster. This feature is very useful in connection with mod_perl CGI scripts.
You can configure this class to preparse the input file immediatly after the disk access (NOTE: the preparsed file will be cached). Some default preparse algorithms are available (delete empty lines, remove comments, remove trailing blanks, ...) but it's possible to overload a method to implement special preparse functionality.
Overview:
new - opens, reads and preparses a file close - close the file parse_file - empty method, overload this for specific preparse functionality getfile - returns a scalar holding the preparsed file getline - returns a scalar holding a line of the file getline_reset - resets the cursor for getline getline_number - returns the inputfile number of the last line got via getline (cursor handled for includes) getline_file - returns the inputfilename of the last line got via getline (cursor handled for includes) getline_error - returns error messages in for this line (cursor handled) setline_error - stores a errormessage to the last line got via getline get_errors - returns a human readable string holding ALL error messages
(1) $ref = CONFIG::Plain->new($filename);
(2) $ref = CONFIG::Plain->new($filename, \%CONFIG);
(3) $ref = CONFIG::Plain->new(\%CONFIG);
This method creates a new object from the class.
You can specify the filename as first argument (see syntax (1) or (2)) or include the filename into the options hash (use "FILE" as key).
Configuration Options:
COMMENT - define comment styles Known comment styles are: sh - shell like comments (from '#' to end of line) C - C like comments (from '/*' to '*/', multi line) C++ - C++ like comments (from '//' to end of line) asm - assembler like comments (from ';' to end of line) pascal - pascal like comments (from '{' to '}', multi line) sql - oracle sql style (from '--' to end of line) regexp - define comments by regular expression for start and end. This style accepts two parameters, the syntax is: "regexp:<startre>|<stopre>" where <startre> is the regular expression for the start of the comment, and <stopre> the regexp for the end. EXAMPLE: "regexp:#|\$" comments goes from "#" to new line (same as "sh" style). DEFAULT: "sh C C++" DATA - use given data instaed of read it from a file Use the data given in this argument instaed of read it from disk. DELEMPTYLINE - delete empty lines Boolsch, if true empty lines will be deleted. DEFAULT: 1 ESCAPE - specifies a escape character Use the ESCAPE character in front of magic sequences (or characters) to make them non magic. EXAMPLE: (escape a comment) >this line includes a hash sign \# but no comment< will get into >this line includes a hash sign # but no comment< of >no \/*comment /* comment \*/ still comment */ no comment< will get into >no /*comment no comment< EXAMPLE: (escape a escape character) >a backslash:\\< will get into >a backslash:\< EXAMPLE: (escape a new line) >line one \ line two< will get into >line one line two< DEFAULT: `\\\\` # -> one backslash FILE - specify the filename If you use the syntax (3) the filename is got from this option. INCLUDE - specify a regexp for includes If this regexp matches, the specified file will be included at this point. This regexp must store the filename in the $1 varaible. DEFAULT: "include <(.*?)>" (filename in <> is stored) REMOVETRAILINGBLANKS - remove trailing blanks Boolsch, if true trailing blanks will be removed. EXAMPLE: > ho ho < will get into >ho ho< (no leading or trailing white spaces) DEFAULT: 1
This method accually does nothing, but this may changed in future releases, so please use it for compatibily.
$file_contents = $file->getfile; returns the preparsed file.
$line = $file_getline; returns the file line by line until the end of the file is reached. The method will return an undefined value on end of file. NOTE: the first call to this method need not return the first line of the file (e.g. if the line was empty and DELEMPTYLINE was enabled) Use the method getline_number to get the linenumber of the last got line.
$file->getline_reset; If you call this method, the next call to the getline method will start the filereading from the top of the file.
$line_number = $file->getline_number; Returns the input line number of the last line got via getline. Because of the INCLUDE feature this method may called often to get the include path (see example below).
$filename = $file->getline_file; Returns the filename of the sourcefile of the last line got via getline. Because of the INCLUDE feature this mathod may called often to get the include path (see example below).
$error = $file->getline_error; Returns for every error occurred in this line a human readable error message or an undefined value if no error occures. NOTE: Since one line may contain more then one error, this method may called often to get all error messages. The list will be terminated by an undefined value. NOTE: If you call this method before the first call to getline, you will get the global error messages (such as "file not found").
print $file->get_errors; Returns a scalar holding ALL error messages in a preformated style.
$file->setline_error(sprintf("File %s not found", $filename)); Stores a error message to a line. Every line may contain more then one error(message).
CONFIG::Hash(3pm)
The CONFIG:: Guide at http://www.fatalmind.com/programs/CONFIG
Since this module is grown, the design is horrible! I should re-implement the whole module (I'll do this in V2.0).
Many, but in most cases it will work correct ;)
Note: the include stuff is very beta
Markus Winand <mws@fatalmind.com>
Copyright (C) 1999, 2000 by Markus Winand <mws@fatalmind.com> This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install CONFIG::Hash, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CONFIG::Hash
CPAN shell
perl -MCPAN -e shell install CONFIG::Hash
For more information on module installation, please visit the detailed CPAN module installation guide.