ConfigReader::DirectiveStyle(3) 			User Contributed Perl Documentation			   ConfigReader::DirectiveStyle(3)

NAME

       ConfigReader::DirectiveStyle

       Reads a configuration file of directives and values.

CONFIGURATION FILE SYNOPSIS

	   # comments start with a #, and blank lines are ignored

	   Input     /etc/data_source	   # the value follows the directive name
	   HomePage  http://www.w3.org/

	   # values can be quoted
	   Comment   "here is a value with trailing spaces   "

CODE SYNOPSIS

	   my $c = new ConfigReader::DirectiveStyle;

	   directive $c 'Input', undef, '~/input';  # specify default value,
						    #	but no parsing needed
	   required  $c 'HomePage', 'new URI::URL'; # create URI::URL object
	   ignore    $c 'Comment';		    # Ignore this directive.

	   $c->load('my.config');
	   open(IN, $c->value("Input"));

	   $c->define_accessors();		    # creates Input() and HomePage()
	   retrieve(HomePage());

DESCRIPTION

       This class reads a common style of configuration files, where directive names are followed by a value.  For each directive you can specify
       whether it has a default value or is required, and a function or method to use to parse the value.  Errors and warnings are caught while
       parsing, and the location where the offending value came from (either from the configuration file, or your Perl source for default values)
       is reported.

       DirectiveStyle is a subclass of ConfigReader::Values.  The methods to define the directives in the configuration file are documented there.

       Comments are introduced by the "#" character, and continue until the end of line.  Like in Perl, the backslash character "" may be used in
       the directive values for the various standard sequences:

	    			tab
	    
		newline
	    
		return
	    f		form feed
	    v		vertical tab, whatever that is
	    		backspace
	    a		alarm (bell)
	    e		escape
	    33	octal char
	    x1b	hex char

       The value may also be quoted, which lets you include leading or trailing spaces.  The quotes are stripped off before the value is returned.

       DirectiveStyle itself only reads the configuration file.  Most of the hard work of defining the directives and parsing the values is done
       in its superclass, ConfigReader::Values.  You should be able to easily modify or subclass DirectiveStyle to read a different style of con-
       figuration file.

PUBLIC METHODS

       "new( [$spec] )"

       This static method creates and returns a new DirectiveStyle object.  For information about the optional $spec argument, see Direc-
       tiveStyle::new().

       "load($file, [$untaint])"

       Before calling load(), you'll want to define the directives using the methods described in ConfigReader::Values.

       Reads a configuration from $file.  The default values for any directives not present in the file are assigned.

       Normally configuration values are tainted like any data read from a file.  If the configuration file comes from a trusted source, you can
       untaint all the values by setting the optional $untaint argument to a true value (such as 'UNTAINT').

SUBCLASSABLE METHODS

       You can stop reading here if you just want to use DirectiveStyle.  The following methods could be overridden in a subclass to provide addi-
       tional or alternate functionality.

       "parse_line($line, $whence, $untaint)"

       Parses $line.  $whence is a string describing the source of the line.  Returns a two-element array of the directive and the value string,
       or the empty array () if the line is blank or only contains a comment.

       "parse_value_string($str, $whence)"

       Interprets quotes, backslashes, and comments in the value part.	(Note that after the value string is returned, it will still get passed to
       the directive's parsing function of method if one is defined).

perl v5.8.2							    1996-02-14					   ConfigReader::DirectiveStyle(3)