Markus Winand > CONFIG-V0.99.11 > CONFIG::Plain

Download:
CONFIG-V0.99.11.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Source  

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 ^

CONFIG::Hash(3pm)

The CONFIG:: Guide at http://www.fatalmind.com/programs/CONFIG

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 <mws@fatalmind.com>

COPYRIGHT ^

    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.
syntax highlighting: