perldoc CONFIG::Plain |
- NAME
- SYNOPSIS
- ABSTRACT
- DESCRIPTION
- METHODS
- new - open, read and preparse file
- close - closes a object instance
- getfile - returns a scalar holding the whole file
- getline - returns a scalar holding a line
- getline_reset - reset the cursor for getline
- getline_number - returns the input line number
- getline_file - returns the input filename
- getline_error - returns errors of this line
- get_errors - returns ALL error messages
- setline_error - stores a errormessage
- SEE ALSO
- TODO
- BUGS
- AUTHOR
- COPYRIGHT
NAME
CONFIG::Plain - Base class for cached file reading
SYNOPSIS
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));
}
}
ABSTRACT
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.
DESCRIPTION
The methods of this module are very similar to the IO methods to read a file. The two major differences are:
Caching
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.
Preparsing
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.
METHODS
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
new - open, read and preparse file
(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
close - closes a object instance
This method accually does nothing, but this may changed in future releases, so please use it for compatibily.
getfile - returns a scalar holding the whole file
$file_contents = $file->getfile;
returns the preparsed file.
getline - returns a scalar holding a line
$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.
getline_reset - reset the cursor for getline
$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.
getline_number - returns the input line number
$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).
getline_file - returns the input filename
$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).
getline_error - returns errors of this line
$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").
get_errors - returns ALL error messages
print $file->get_errors;
Returns a scalar holding ALL error messages in a preformated style.
setline_error - stores a errormessage
$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).
SEE ALSO
TODO
Since this module is grown, the design is horrible! I should re-implement the whole module (I'll do this in V2.0).
BUGS
Many, but in most cases it will work correct ;)
Note: the include stuff is very beta
AUTHOR
Markus Winand <
>
COPYRIGHT
Copyright (C) 1999, 2000 by Markus Winand <
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.