PTools::SDF::File - Abstract base class for "Simple Data File" modules

INHERITANCE
SEE ALSO
AUTHOR
COPYRIGHT

NAME

PTools::SDF::File - Abstract base class for ``Simple Data File'' modules

VERSION

This document describes version 0.08, released Nov 12, 2002.

SYNOPSIS

This class is intended for use by module designers when creating a new subclass to handle another type of ``simple data file.''

    package NewFileType;

    use vars qw( $VERSION @ISA );
    $VERSION = '0.01';
    @ISA     = qw( PTools::SDF::File );

    use PTools::SDF::File;

    # After creating this inheritance structure, the designer must
    # implement all of the required abstract methods in the parent 
    # class, including the following.

    sub new        { }
    sub param      { }
    sub ctrl       { }
    sub delete     { }
    sub ctrlDelete { }
    sub save       { }
    sub sort       { }
    sub setError   { }
    sub dump       { }

DESCRIPTION

PTools::SDF::File is used to provide a foundation for various classes that provide interfaces to ``simple'' data file types.

Some of these subclasses violate the Liskov Substitution Principle. The param method will take different parameters depending on the subclass. This is simply due to differences in the format of the data records in various file types. However, all attempts should be made to keep as many of the methods as similar as possible across the subclasses.

Modules currently exist to implement various ``Simple Data Files'' including a ``Self Defining File'' format, Windows ``.INI'' files, ``tagged'' data files, and others. See the PTools::SDF::Overview manpage for details.

Constructor

new ( Options )

This is an abstract method. Implementation is up to the designer of each particular subclass.

This method should include the option to load a data file upon instantiation or simply return an empty object.

Abstract Methods

The following methods are expected to exist in each subclass, and are expected to work in a similar manner to existing subclasses. Refer to the following notes for implementation guidelines.

See documentation on the existing subclass modules for implementation examples including the PTools::SDF::INI manpage, the PTools::SDF::SDF manpage and the PTools::SDF::TAG manpage.

param ( Options )

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

ctrl ( CtrlField [, CtrlValue ] )

Fetch or set ControlField parameters within an object. This can also be used to cache temporary data in the current PTools::SDF:: object. 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.

Example:

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

    $sdfObj->ctrl( "fileName", '/tmp/newDataFilename' );

    # Obtain the file name for the current PTools::SDF::Subclass object

    $fileName = $sdfObj->ctrl( "fileName" );

ctrlDelete

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

Example:

    $sdfObj->ctrlDelete('readOnly');

delete ( Options )

Delete one or more entire records from the current PTools::SDF::Subclass object. The deleted entry/ies should available as a return parameter.

save ( Options )

Save any modifications to the file data.

The implementation is left up to the module designer.

Example:

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

sort ( Options )

This is a required method even though some file implementations may not be in a format where a sort operation would be meaningful. In these cases, simply define a sort method that sets an error condition.

Currently, only the PTools::SDF::SDF subclass support a sort method. The options used for sorting depend entirely on which sort module is loaded at the time of the call. There are several sort modules available. See the PTools::SDF::SDF manpage for further details.

setError ( Status, ErrorText )

This method is used internally in an PTools::SDF::Subclass to set an error condition. Note, however, that any script may call this method.

status: A numeric status code where any non-zero value indicates an error.
errortext: A text string indicating the nature of the error condition.

Examples:

    $sdfObj->setError(0,"");        # restore object to a "no error" state

    $sdfObj->setError(-1, "Edit failed for field '$field' in record '$idx'");

dump ( Options )

Display contents of the current PTools::SDF::Subclass object. This is useful during testing and debugging, but does not need to produce a ``pretty'' format. For data files that can contain many records, providing a way to limit the output will be most useful.

The implementation is left up to the module designer.

Examples:

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

    print $sdfObj->dump( 0, -1 )  # dump only the "control field" values

    print $sdfObj->dump( 10, 5 )  # dump recs 10 through 15.

Concrete Methods

lock ( [Retry [, Sleep ] [, CreateMode ] )

This method locks the physical file associated with the various PTools::SDF::Subclass objects. If the filename passed to the new method did not exist at object instantiation, the file will exist after a successful lock.

The options used for locking depend entirely on which lock module is loaded at the time of the call. Currently there is one lock module available (listed in the SEE ALSO section, below).

Options used by the default the PTools::SDF::Lock::Advisory manpage module includes the following. See description of the extend method, below, on how to select other lock modules.

Retry: If the lock fails, the retry parameter indicates how many times the lock module should rety. Default is 0 retries.
Sleep: If the lock fails, and the retry parameter is non-zero, the sleep parameter indicates how many seconds to sleep between reties. Default is 1 second.
CreateMode: If the file represented by the current PTools::SDF::Subclass object does not exist, the createmode parameter indicates what open mode will be used to create the file. The default value is 0644 (equivalent to ``-rw-r--r--'').

Example:

    ($stat,$err) = $sdfObj->lock;
    $stat and die $err;

Note that the PTools::SDF::Lock::Advisory module is designed to work with any script as a stand-alone lock manager. However, when this module is not used via one of the PTools::SDF::Subclass modules the calling syntax changes. See the PTools::SDF::Lock::Advisory manpage for details.

isLocked, notLocked

These methods exist to test the ``lock state'' of the current PTools::SDF::Subclass object.

Examples:

    $sdfObj->isLocked  or do { ... };

    $sdfObj->notLocked or do { ... };

unlock

Unlock the physical file associated with the current object. The default PTools::SDF:: lock module uses simple advisory locking, so any lock held will be released upon object destruction, when the script ends, etc.

Example:

    $sdfObj->unlock;

extend ( MethodList, ClassName )

The extend method is the mechanism used to select which external class will be used for the lock method in this class. Each new subclass based on this module should support this lock strategy.

Currently a method must be explicitly created as extendible, and currently only the lock / unlock methods in this class and the PTools::SDF::SDF sort method are extendible using this mechanism.

Module designers are free to include extendible methods in their modules as appropriate. Refer to the code for examples of implementation.

MethodList: Either a string naming a single method (e.g., sort), or an array reference naming multilpe methods (e.g., lock / unlock). The methods must be object methods, not class methods.
ClassName: The name of the Perl class that will be used to perform the method(s) indicated in the MethodList parameter.

Examples:

    $sdfObj->extend('sort', "PTools::SDF::Sort::Quick");

    $sdfObj->extend( [ "lock","unlock" ], "PTools::SDF::Lock::Advisory");

Note that, in the last example above, the syntax shown using braces (``[]'') is the actual syntax used to pass an array reference to the extend method, and not an indication of ``optional'' parameters.

Any Perl module can be specified but, at a minimum, it should be able to do the following.

successfully be included via the ``use'' statement
contain a new method that instantiates an object (necessary so the object may be cached in the PTools::SDF::Subclass object).
contain the necessary methods for the desired operation (e.g., ``sort'' for a sort module and ``lock/unlock'' for a lock module).

extended ( MethodName )

Returns a boolean value that indicates whether the MethodName is currently extended. Intended for use by module designers who wish to provide a default method/Class for an extendible method.

Example:

    $sdfObj->extended( "method" )  or  $sdfObj->extend( "method", "Class" );

unextend ( MethodList )

Used to delete the current definition for an extended method. The MethodList parameter here is identical as in the extend method.

expand ( MethodName )

This method is used by module designers to invoke an extended method. Refer to the implementation of the lock method in this class for details.

escapeIFS ( TextString )

Implementations of certain file types specify a record separator or ``internal field separator'' (IFS) character used to delimit data fields. For these file types, it is imperative that no user entered data contain the IFS character. Otherwise that particular record will become corrupt and, in effect, contain an ``extra field.''

To avoid this situation, the escapeIFS method is provided to encode any IFS character(s). Module designers can use this in the save method while writing the data file to disk.

Note that characters like colon (``:''), exclamation point (``!'') and pipe (``|'') work great as field delimiters. Characters such as asterisk (``*'') and percent (``%'') do not.

Performance Note: for large files this operation is an expensive overhead. Modules that use this method should contain a mechanism to disable this functionality when it is not necessary.

unescapeIFS ( TextString )

If there is a possibility that data fields may contain an escaped IFS character, as described above, this method will reverse the encoding of these characters. Module designers can use this in the new method while reading the data file from disk.

escape ( TextString )

This method will encode all characters in the TextString parameter per URL encoding guidelines.

unescape ( TextString )

This method will decode all characters in the TextString parameter per URL encoding guidelines.

writeLogFile ( TextString [, LogFileName ] )

This utility method is provided as many projects include some type of message logging.

TextString: Message text to be written on the log file.
LogFileName: A valid filename to which TextString will be appended.

Example:

    $sdfObj->writeLog( "$date: Error: $err at $line in $PACK", $logFile );

INHERITANCE

This PTools::SDF::File is an abstract base class intended for use by the various ``Simple Data File'' subclasses that implement a particular file format.

AUTHOR

Chris Cobb, <nospamplease@ccobb.net>

COPYRIGHT

PTools::SDF::File - Abstract base class for "Simple Data File" modules