PTools::SDF::TAG - Implements a Simple Data File in "Tagged Data" format

INHERITANCE
SEE ALSO
AUTHOR
COPYRIGHT

NAME

PTools::SDF::TAG - Implements a Simple Data File in ``Tagged Data'' format

VERSION

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

SYNOPSIS

    use PTools::SDF::TAG;

    $tagObj = new PTools::SDF::TAG("$fileName");

Access and set data field values.

    $dataValue = $tagObj->param("fieldName");

    $tagObj->param("fieldName", "new value");

Access and set control field values.

    $ctrlValue = $tagObj->ctrl("fieldName");

    $ctrlValue = $tagObj->ctrl("ctrlField", "new value");

Determine the current field names contained in the $tagObj object.

     $fields = $tagObj->ctrl("dataFields");
   (@fields) = $tagObj->ctrl("dataFields");

    $tagObj->ctrl("fileName",  "data/control.tmp");
    $tagObj->ctrl("dataFields","folder:seqnbr");

    $tagObj->ctrl("fileName", "newFile");
    $tagObj->save;

DESCRIPTION

PTools::SDF::TAG is used to simplify data file access, and to eliminate dependance on field positions within files. This package reads and writes files in the following format.

     [fieldName1]
     some field value
     [fieldName2]
     other field with
     a multiline value
     [fieldName3]
     another field value

Constructor

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

Creates a new PTools::SDF::TAG 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.

Mode

The Mode parameter is not currently implemented in this class.

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

 $tagObj = new PTools::SDF::TAG;

 $tagObj = new PTools::SDF::TAG( "/home/cobb/data/testfile.tag" );

Methods

param( DataFieldName [ DataFieldValue ] )

Fetch or set a data value.

Examples:

  $fieldCount = $ref->param;

  $fieldValue = $ref->param($fieldName);

  $ref->param($fieldName, $newValue);

delete ( FieldName )

Delete the value for a named data field.

Example:

    # Delete the value for the 'proddesc' field

    $tagObj->delete( 'proddesc');

ctrl( CtrlFieldName [ CtrlFieldValue ] )

Fetch or set a control parameter.

Examples:

  $ctrlFields = $tagObj->ctrl;                 # string of field names
 (@ctrlFields) = $tagObj->ctrl;                # array of field names

  $fieldValues = $tagObj->ctrl($fieldName);    # string of values for field
 (@fieldValues) = $tagObj->ctrl($fieldName);   # array of values for field

  $tagObj->ctrl($fieldName, $newValue);
  $tagObj->ctrl($fieldName, @newValues);

Note that the 'version' and 'ctrlFields' values can NOT be changed using the ctrl method.

ctrlDelete ( CtrlField )

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

Example:

 $tagObj->ctrlDelete('fileName');

tag2sdf( [ FieldNameList ] )

This method is is designed for use with a special form of the param method in the PTools::SDF::SDF class. If a hash reference is passed for the FieldName parameter, this hash ref will replace the data record specified by the Index parameter. Note that no checking is done. It is up to the programmer to ensure appropriate key names and values.

 use PTools::SDF::SDF;
 use PTools::SDF::TAG;

 $sdfObj = new PTools::SDF::SDF;
 $tagObj = new PTools::SDF::TAG( "myFile.tag" );

 $tagHashRef = $tagObj->tag2sdf;

 $nextRecord = $sdfObj->count;          # (one-based count)

 $sdfObj->param( $nextRecord, $tagHashRef );

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

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

Note: Only those fields 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.

In addition, the only control parameters that are saved with the file are the field names.

UserID

By default the PTools::SDF::TAG 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)

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

NewFileName

By default the PTools::SDF::TAG 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::TAG 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.

Examples:

 $tagObj->save;

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

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

Another Example:

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

 $tagObj->save;

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

sort

The sort method is not implemented in this class.

isLocked

notLocked

Determine whether a lock is held on the data file associated with the current object.

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) = $tagObj->status;

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

 $err = $tagObj->err;

dump

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

Example:

 print $tagObj->dump;

INHERITANCE

This PTools::SDF::TAG 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::TAG - Implements a Simple Data File in "Tagged Data" format