NAME
Tie::Form - access a machine readable database file that minics a
hardcopy form
SYNOPSIS
require Tie::Form;
#####
# Using support methods and file handle with
# the file subroutines such as open(), readline()
# print(), close()
#
tie *FORM_FILEHANDLE, 'Tie::Form', @options
$form = tied \*FORM_FILEHANDLE;
#####
# Using support methods only, no file subroutines
#
$form = Tie::Form->new(@options);
\$encoded_fields = $form->decode_record(\$record);
\@fields = $form->decode_field(\$encoded_fields);
\$encoded_fields = $form->encode_field (\@fields);
\$record = $form->encode_record(\$encoded_fields);
$record = $form->get_record();
####
# Subroutine interface
#
\$encoded_fields = decode_record(\$record);
\@fields = decode_field(\$encoded_fields);
\$encoded_fields = encode_field (\@fields);
\$record = encode_record(\$encoded_fields);
If a subroutine or method will process a list of options, "@options",
that subroutine will also process an array reference, "\@options",
"[@options]", or hash reference, "\%options", "{@options}".
DESCRIPTION
The "Tie::Form" module provides a text database file suitable for local
data such as private mailing lists. The "Tie::Form" cannot provide a
data warehouse shared by mulitple users.
File format description
Desireable goals for small local private databases file format are as
follows:
* The database is a text file that can be edited with a simple text
editor. How many times have a basebase been corrupted and the data
cannot be recoveried? For most people many times. One time is one
time too many
* The text format resembles as much as possible the standard forms
that all civilized people must from time to time fill out in order
to survive in a civilized society. Forms are a necessary evil in the
pursue of happiness, freedom and prosperity in a civilized society.
An example of a form is as follows:
manhood length: ________
time spent in big house: _________
what drugs do you use: _________
Notice the applicant is not required to specify the form data using
Perl hash notation such as
manhood_length => 2
By the way, that would be your entry. My entry would be
manhood_length => 22
The political incorrect NH live free or die response would be
manhood length: come up to my place and I'll show you
time spent in big house: none of your business
what drugs do you use: put it where the sun doesn't shine
The feds response to NH: no federal funding.
* The record separator, field separator and any other separator is
unique and not embedded in the data. With unique separators, various
components of the database may be accessed with simple file read and
write functions. There is no need to buffer and process the data to
determine if the separator is really a separtor or part of the data.
* The format has simple, straightforward method of escaping separators
when they are embedded in the data. Escape techiques such as the
back-slash besides causing blurred vision also leave the separator
embedded in the data. Try looking at the output of the metachar()
function and then try to read a eye chart. This is totally
unacceptable not only because it impairs vision but also for poor
computation performance.
The Tie::Form program module solution is to use separators of the
following form:
(not_the_char) . (char) . (not_the_char)
The separators are escaped in embedded text by adding a extra (char) as
follows:
sequence escaped
[^$c]$c[^c] [^$c]$c$c[^c]
[^$c]$c$c[^c] [^$c]$c$c$c[^c]
...
[^$c]$c x n[^c] [^$c]$c($c x n)[^c]
SUBROUTINES
This package inherits most of its Tie methods from the Tie::Layers
package.
The methods specific to this package are to encode and decode fields and
records, and to put and get records as follows:
TIEHANDLE
tie *FORM_FILEHANDLE, 'Tie::Form', @options
tie *FORM_FILEHANDLE, 'Tie::Form', \@options
tie *FORM_FILEHANDLE, 'Tie::Form', \%options
$form = tied \*FORM_FILEHANDLE;
The "TIEHANDLE" method supports the "tie" Perl built-in subroutine. The
"$form" object created by "tie" may be used to access the functions that
are in addition to the those established in Tie Handle Perl
specification. The available options are as follows:
option description
---------------------------
EON End of Name field termination separator
EOD End of Data field termination separator
EOR End of Record termination separator
strict strict processing of EON and EOD
Typically "EON", "EOD", "EOR" should be read-only. The requirements for
these options are very specific.
encode_field
\$encoded_fields = encode_field (\@fields);
The "encode_field" subroutine method takes a "@fields" and returns a
"encoded_fields" string. This subroutine will escape all field
separators.
encode_record
\$record = encode_record(\$encoded_fields);
The "encode_record" subroutine takes a "$encoded_fields" string and
encodes it as "$record". This subroutines escapes the record separator
and embeds the record separator in the "$record" string.
decode_field
\@fields = decode_field(\$encoded_fields);
The "decode_fiel" subroutine takes "$encoded_fields", unescape the field
separators, decodes the fields and places the results in "@fields". The
"@fields" array is ordered name, value pairs of the fields. The even
array elements are the field names and the following odd array element
is the field data.
The below code will convert the decoded "@fields" to a hash:
%fields = @fields
decode_record
\$encoded_fields = decode_record(\$record);
The "decode_record" subroutine takes a "$record" string, removes the
record separator, unescapes the record separator in the fields string
and leaves the fields string in "$encoded_fields".
get_record
$record = $form->get_record();
The get_record method reads a fully encoded "$record" from the
underlying file of the object.
new
$form = Tie::Form->new(@options);
$form = Tie::Form->new(\@options);
$form = Tie::Form->new(\%options);
The "new" method provides an object that may be used to access the
functions that are in addition to the those established in Tie Handle
Perl specification. The "@options" are the same as "TIEHANDLE".
REQUIREMENTS
The general "STD::TestGen" Perl module requirements are as follows:
general [1] - load
shall[1] load without error and
general [2] - pod check
shall[2] passed the Pod::Checker check without error.
File format requirements
For most databases, the file format is hidden. In this case, since the
file may be accessed and edited by any text editor, the file format
requirements must be rigorously established in order that they may be
properly edited.
The "Tie::Form" module file format will be as follows:
$field_name: $field_data ^
...
$field_name: $field_data ^
~-~
...
~-~
$field_name: $field_data ^
...
$field_name: $field_data ^
~-~
The requirements for the file format are as follows:
format [1] - separator strings
The format separator strings shall[1] be as follows:
End of Field Name (EON): [^:]:[^:]
ENd of Field Data (EOD): [^\^]\^[^\^]
End of Record(EOR): ~-~
The separator strings have the following format:
(not_the_char) . (char) . (not_the_char)
The '^' character was and still available in console text editors as
a cursor. Because it appears very rarely in text, it is a good
choice for use in a separator string. If it does not appear a lot,
it will not have to be escaped a lot. The "~-~" separator sequence
is a natural looking text section separator.
format [2] - separator escapes
Separator strings embedded in $field_name and $field_data strings
shall[2] be escaped by adding one additional middle character.
Escaped sequences must also be escaped. An escaped separator
sequence will always have one additional middle character from an
unescaped separator sequence.
format [3] - field names
The characters [\x00-\x1f] shall[3] not be allowed in $field_name
strings. Spaces will be allowed. The character set [\x00-\x1f] are
the ASCII control characters. See ascii.computerdiamonds.com.
Embedded [\x00-\x1f] characters will be converted to the '_'
character.
format [4] - field names
Leading and trailing [ \x00-\x1f] characters in any potential
$field_name string shall[4] not be part of the $field_name and
discarded.
format [5] - EON
A leading [^:] in the EON separator that is not a [ \x00-\x1f]
shall[5] be the be the last character in the $field_name string;
otherwise, it is not part of the the $field_name string and
discarded. For the situation where the last part of a $field_name
string is an escape sequence a [ \x00-\x1f] will be required between
the $field_name string and the EON. The following is a valid
$field_name EON sequence:
escaped unescaped
field_name:: : fieldname:
format [6] - Strict EOD
For the strict format option, the leading [^\^] of the EOD shall[6]
not be part of the $field_data. The [^\^] character may be any
character including the [\x00-\x1f] characters.
Examples of strict format option are as follows:
$field_name: $data ^
$field_name: $data$c^
$field_name:
line1
..
line2
^
The $field_data for the above example is as follows:
Example $field_data
"$data ^" "$data"
"$data$c^" "$data"
"$line1\n$line2\n^" "$line1\n$line2"
format [7] - Lenient EOD
For the lenient format option, the leading [^\^] of the EOD shall[7]
be part of the $field_data. The lenient format has ambiguous case
when the last character in the $field_data is the [\^] character. In
order to be valid, a [^\^] must be used before the [\^], making the
[^\^] part of the $field_data whether that is intended or not. For
example in, "$data^^ ^", the $field_data is "$data^ " whether or not
the space is intended as part of the $field_data. If this cannot be
tolerated for an application the strict format opion should be
specified.
Examples of lenient format option are as follows:
$field_name: $data1 ^
$field_name: $data2^
$field_name:
$line1
$line2
^
The $field_data for the above example is as follows:
Example $field_data
"$data1 ^" "$data1 "
"$data2^" "$data2"
"$line1\n$line2\n^" "$line1\n$line2\n"
Methods requirements
There are two options, that impact the methodsas follows:
strict => 1 option
This option determines whether to encode a field in strict or
lenient format.
binary => 1 option
This option determines whether or not to process carriage returns
and line feeds. Different operating systems handle these characters
differently for text files.
The requirements for the methods are as follows:
methods [1] - encode_field
$field = $tdb->encode_field (\@fields, \$fields)
The @fields array will contain a number of fields. The $field_names
will be the even elements and the $field_data the following odd
elements.
The encode_field subroutine shall[1] encode the $field_name string
and $field_data string into the $field string in accordance with the
File Format requirements. The encoding shall escape the EON and EOD
separators and embed the EON and EOD separators.
The encoding will be conservative in complying with the File Format
requirements.
As established by the File Format requirements, the encoding will be
different depending upon the value of the strict option,
$tdb->{options}->{strict}.
methods [2] - decode_field
$success = $tdb->decode_field(\$fields, \@fields)
The decode_field subroutine shall[2] decode a $record string into
the @fields array in accordance with the File Format requirements.
The $field_names will be the even elements in the @fields array and
the $field_data the following odd elements.
The decoding will be liberal what it considers that complies to the
File Format requirements.
As established by the File Format requirements, the decoding will be
different depending upon the value of the strict option,
$tdb->{options}->{strict}.
methods [3] - encode_record
$success = $tdb->encode_record(\$fields, \$record)
$success = $tdb->encode_record( \$fields)
The encode_record subroutine shall[3] encode the $fields string into
the $record string in accordance with File Format requirements. If
the $record string is absence or the \$record reference and the
\$fields reference are the same, the encoding will modify the
\$fields string. In this case, the encoding will not perserve the
$fields string. The encoding will escape the EOR and embed the EOR.
methods [4] - decode_record
$success = $tdb->decode_record(\$record, \$fields)
$success = $tdb->decode_record(\$record)
The decode_record subroutine shall[4] decode the $record string and
into the $fields string in accordance with the File Format
requirements. If the $fields string is absence or the \$record
reference and the \$fields reference are the same, the encoding will
modify the \$record string. In this case, the encoding will not
perserve the $record string. The decoding will remove the EOR and
unescape the EOR.
methods [5] - put_record
$success = $tdb_out->put_record( \$record )
The put_record subroutine shall[5] write out the $record to the file
specified when the object $tdb_out was created with the following
statement
$tdb_out = Tie::Form( flag => '>', file => $file, @options );
methods [6] - get_record
$success = $tdb_in->get_record( \$record )
The get_record subroutine shall[6] read a $record from the file
specified when the object $tdb_in was created with the following
statement
$tdb_in = Tie::Form( flag => '<', file=>$file, @options );
methods [7] - get_record
Unless $tdb_in was created with the binary option, {binary => 1},
the get_record subroutine shall[7] translate any "\015\012"
combination into the "\n" for the current operating system.
Tie::Layers
The methods inherit from Tie::Layers will comply to the Tie::Layers
requirements
DEMONSTRATION
#########
# perl Form.d
###
~~~~~~ Demonstration overview ~~~~~
The results from executing the Perl Code follow on the next lines as
comments. For example,
2 + 2
# 4
~~~~~~ The demonstration follows ~~~~~
use File::Package;
use File::SmartNL;
use File::Spec;
my $uut = 'Tie::Form'; # Unit Under Test
my $fp = 'File::Package';
my $loaded;
my (@fields); # force context
my $out_file = File::Spec->catfile('_Form_','form1.txt');;
unlink $out_file;
my $lenient_in_file = File::Spec->catfile('_Form_','lenient0.txt');
my $strict_in_file = File::Spec->catfile('_Form_','strict0.txt');
my $version = $Tie::Form::VERSION;
$version = '' unless $version;
##################
# Load UUT
#
my $errors = $fp->load_package($uut)
$errors
# ''
#
##################
# Tie::Form Version loaded
#
$fp->is_package_loaded($uut)
# 1
#
##################
# Read lenient Form
#
tie *FORM, 'Tie::Form';
open FORM,'<',File::Spec->catfile($lenient_in_file);
@fields =