PTools::SDF::INI - Implements a Simple Data File in "Windows INI" format

INHERITANCE
SEE ALSO
AUTHOR
COPYRIGHT

NAME

PTools::SDF::INI - Implements a Simple Data File in ``Windows INI'' format

VERSION

This document describes version 0.08, released Feb 15, 2003.

SYNOPSIS

     use PTools::SDF::INI;

     $iniObj = new PTools::SDF::INI( $fileName );

 or  $iniObj = new PTools::SDF::INI( $fileName, $iniSection, @fields );

     $fieldNames    = $iniObj->param($sectName);    # "name1:name2:name3"
     (@fieldNames)  = $iniObj->param($sectName);    # array of field names

     $fieldValue    = $iniObj->param($sectName, $fieldName);

     $iniObj->param($sectName, $fieldName, $newValue);

     $sectionCount  = $iniObj->param;               # number of "sections"
    (@sectionNames) = $iniObj->param;               # name of each section

The following is roughly equivalent to the dump method used to display the contents of objects of this class.

    foreach my $secName ( $iniObj->param ) {

         print "$secName\n";

         foreach my $fieldName ( $iniObj->param( $secName ) ) {

             my($fieldValue) = $iniObj->param($secName, $fieldName);

             print "  $fieldName = $fieldValue\n";
         }
     }

DESCRIPTION

The PTools::SDF::INI class reads and writes files in the MS Windows '.INI' format.

   [personalData]
     first = field value
     last = other field value
     telnet = another field value

Warning: I never found any documentation regarding this file format. If you can point me to official MicroSoft documentation on this format, I would appreciate it. Thanks in advance.

Constructor

new ( [ FileName ] [, Match ] [, FieldNames ] )

Creates a new PTools::SDF::INI object and, if a FileName parameter is specified and the file currently exists, loads file data into the object.

FileName

The FileName parameter is optional. When specified and the data file exists, the file is loaded into the new object. If the specified file does not exist when the object is created, the filename will be used by the save method to create a new file, if possible.

This class is often used simply to store data in memory during the execution of a script. It is often convenient to use familiar data structures, such as this file format, without any actual disk file.

Match

To load only a subset of the data file, pass a Match value. This value will be used to load only those section names that match the pattern.

Note that when a ``subset'' of a data file is loaded, the save method is disabled. Use the Force parameter of the save method to override, or use the ctrl method to specify a different FileName prior to calling save.

FieldNames

When it is not appropriate to embed a comment header within a data file to define the field names for each record, pass a FieldNames parameter to the new method. This can be either a colon separated list of fields, or an array.

Examples

 $iniObj = new PTools::SDF::INI;

 $iniObj = new PTools::SDF::INI( "/application_dir/data/testfile.ini" );

Methods

param ( [ SectionName, FieldName ] [, Value ] )

Fetch or set field values within a record. When called without any parameters, returns a zero-based count of entries in the object. Use the count method to obtain a one-based count of entries.

SectionName: Specify the SectionName as defined in the PTools::SDF::INI object.
FieldName: Specify the FieldName to access within a particular SectionName.
Value: The Value is an optional parameter that is used to set the value of the specified FieldName. Without a this parameter, the current value of the field is returned.

Examples:

 $fieldValue = $iniObj->param( 'SectionOne', 'FieldOne' );

 $iniObj->param( 'SectionOne', 'FieldOne', "New Value" );

ctrl ( CtrlField [, CtrlValue ] )

Fetch or set control field parameters within an object. This can also be used to cache temporary data in the current PTools::SDF::INI object. Just be sure to use a unique attribute name and remember that this data will not be saved with the file data. See the dump method for an example of displaying control fields and values.

CtrlField: Specify the field name to access within the indexed record.
CtrlValue: The CtrlValue is an optional parameter that is used to set the value of the specified CtrlField. Without a this parameter, the current value of the field is returned.

Examples:

 # Specify a new file name for the current PTools::SDF::INI object

 $fieldValue = $iniObj->ctrl( "fileName", '/tmp/newDataFilename' );

 # Fetch a colon-separated list of field names in the file.
 # In list context, an array of field names is returned.

 $fieldList   = $iniObj->ctrl( "dataFields" );
 (@fieldList) = $iniObj->ctrl( "dataFields" );

 # Specify a new list of fieldnames for the current object
 # WARN: this will *not* change any existing field names, and
 # only existing fields that appear in this list will be written
 # to the data file via the "save" method. This is provided as
 # a way to create a subset of a file, to add new fields, and/or
 # to re-arrange the field order when file is saved to disk.

 $iniObj->ctrl( "dataFields", "colon:separated:list:of:names" );
 $iniObj->ctrl( "dataFields", @fieldNameList );

ctrlDelete ( CtrlField )

Delete the value for a named control field in the current object.

Example:

 # Loading a subset of a data file sets an attribute to disable the
 # "save" method. This removes the attribute and re-enables "save":

 $iniObj->ctrlDelete('readOnly');

delete ( SectionName [, FieldName ] )

Delete one variable from the SectionName in the current PTools::SDF::INI object. The deleted value is available as a return parameter. This will be whatever was originally stored in this variable.

Examples:

 $value = $iniObj->delete( "SectionOne", "FieldTwo" );

save ( [ UserID ] [, NewFileName ] [, Heading ] [, Force ] )

Write the data in the current object out to a disk file.

Note: Only those SectionNames that have an entry in the dataFields control parameter will be written to the disk file. See the ctrl method, above, for details on using this attribute.

Note that no control parameters are saved with the file.

UserID

By default the PTools::SDF::INI module adds a header that includes the uname of the person running the current script. Use this parameter to log a different user name.

Example:

 $webUserid = $ENV{'REMOTE_USER'};   # (from Web Server Basic Auth)

 $iniObj->save( $webUserid, $filename );

NewFileName

By default the PTools::SDF::INI module saves the file using the original name specified when creating the current object. This can be changed by passing a new file name here.

Heading

By default the PTools::SDF::INI module adds a header that includes a date stamp (Unix ``epoch'' number) of when the file was saved. To write a different header, pass the text here.

Force

If a ``subset'' of the original data file was loaded using ``match'' criteria, the save parameter is disabled by default. Pass any non-null parameter here to override this default and force a save.

WARN: This will cause any records omitted during the load to be lost.

Examples:

 $iniObj->save;

 ($stat,$err) = $iniObj->save;

 $iniObj->save( undef, "newfilename" );

Another Example:

 $iniObj->ctrl('fileName', "newfilename" );

 $iniObj->save;

 ($stat,$err) = $iniObj->status;

 $stat and die $err

isLocked

notLocked

Determine whether or not the data file associated with the current object has an 'advisory lock' in effect.

 if ( $iniObj->isLocked ) do { . . . }

 if ( $iniObj->notLocked ) do { . . . }

status

stat

err

Determine whether an error occurred during the last call to a method on this object. The stat method returns different values depending on the calling context.

 ($stat,$err) = $iniObj->status;

 $stat = $iniObj->stat;     # scalar context returns status number
 ($err)= $iniObj->stat;     # array context returns error message

 $err = $iniObj->err;

dump

Display contents of the current PTools::SDF::INI object. This is useful during testing and debugging, but does not produce a ``pretty'' format. For large data files the output will be rather lengthy.

Examples:

 print $iniObj->dump;          # can produce a *lot* of output

INHERITANCE

This PTools::SDF::INI class inherits from the PTools::SDF::File abstract base class. Additional methods are available via this parent class.

AUTHOR

Chris Cobb, <nospamplease@ccobb.net>

COPYRIGHT

PTools::SDF::INI - Implements a Simple Data File in "Windows INI" format