PTools::SDF::TAG - Implements a Simple Data File in "Tagged Data" format
This document describes version 0.09, released Feb 15, 2003.
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;
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
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.
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.
The Mode parameter is not currently implemented in this class.
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" );
Fetch or set a data value.
Examples:
$fieldCount = $ref->param; $fieldValue = $ref->param($fieldName); $ref->param($fieldName, $newValue);
Delete the value for a named data field.
Example:
# Delete the value for the 'proddesc' field
$tagObj->delete( 'proddesc');
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.
Delete the value for a named control field in the current object.
Example:
$tagObj->ctrlDelete('fileName');
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 );
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.
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 );
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.
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;
The sort method is not implemented in this class.
Determine whether a lock is held on the data file associated with the current object.
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;
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;
This PTools::SDF::TAG class inherits from the PTools::SDF::File abstract base class. Additional methods are available via this parent class.
See PTools::SDF::Overview, PTools::SDF::ARRAY, PTools::SDF::CSV, PTools::SDF::DB, PTools::SDF::DIR, PTools::SDF::DSET, PTools::SDF::File, PTools::SDF::IDX, PTools::SDF::INI, PTools::SDF::SDF, PTools::SDF::Lock::Advisory, PTools::SDF::Lock::Selective, PTools::SDF::Sort::Bubble, PTools::SDF::Sort::Quick and PTools::PTools::SDF::Sort::Shell.
Chris Cobb, <nospamplease@ccobb.net>
Copyright (c) 1997-2007 by Chris Cobb. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
