/ 
Tie-FieldVals-0.6203
River stage zero No dependents
/ Tie::FieldVals::Row

NAME

Tie::FieldVals::Row - a hash tie for rows (records) of Tie::FieldVals data

VERSION

This describes version 0.6203 of Tie::FieldVals::Row.

SYNOPSIS

    use Tie::FieldVals::Row;

    my %person;
    my @keys = qw(Forename Surname DateOfBirth Gender);
    my $row_obj = tie %person, 'Tie::FieldVals::Row', fields=>\@keys;

    # set the row
    $row_obj->set_from_string($row_str,override_keys=>1);

    # compare the row
    if ($row_obj->match(Forename=>'Mary'))
    {
	# do something
    }

DESCRIPTION

This is a Tie object to map a row (record) of enhanced Field:Value data to a hash. This sets fixed keys so that they match the columns of the data. Values can go over more than one line. Fields can have multiple values.

Field names cannot have spaces in them, indeed, they must consist of plain alphanumeric characters or underscores. They are case-sensitive.

OBJECT METHODS

set_from_hash

Set the hash data from a simple untied hash.

$row_obj->set_from_hash(\%hash);

$row_obj->set_from_hash(\%hash override_keys=>1, append_keys=>0);

Arguments:

append_keys

Append to the list of official fields with the Field: contents of this string. (default: false)

override_keys

If override_keys is true, then the official fields, the legal keys to this hash, are reset from the Field: contents of this string. (default: false)

set_from_string

Set the hash data from an enhanced Field:Value data string.

$row_obj->set_from_string($record_str);

$row_obj->set_from_string($record_str, override_keys=>1, append_keys=>0);

The format of the string is basically a multi-line string in Field:Value format, with the addition that if a line does not start with a known fieldname followed by a colon, that the contents of that line is added to the value of the previous field.

If a particular FieldName is repeated, its value is added to the existing value of that FieldName, and it becomes a multi-value field.

Arguments:

append_keys

Append to the list of official fields with the Field: contents of this string. (default: false)

override_keys

If override_keys is true, then the official fields, the legal keys to this hash, are reset from the Field: contents of this string. (default: false)

set_from_xml_string

Set the hash data from an XML string.

$row_obj->set_from_xml_string($record_str);

$row_obj->set_from_xml_string($record_str, override_keys=>1, clear=>1);

The format of this XML string is as follows:

    <record>
	<Field>Value</Field>
	<AnotherField>AnotherValue</AnotherField>
	...
    </record>

If a particular FieldName is repeated, its value is added to the existing value of that FieldName, and it becomes a multi-value field.

Arguments:

append_keys

Append to the list of official fields with the <Field> contents of this string. (default: false)

override_keys

If override_keys is true, then the official fields, the legal keys to this hash, are reset from the <Field> contents of this string. (default: false)

get_as_string

Returns the hash data as a string in the same format as expected by "set_from_string".

my $str = $row_obj->get_as_string();

my $str = $row_obj->get_as_string(fields=>\@fields);

If fields is defined, then return a string which is made up of only that subset of the fields given by the @fields array.

get_xml_string

Returns the hash data as an XML string in the same format as expected by "set_from_xml_string".

my $str = $row_obj->get_xml_string();

my $str = $row_obj->get_xml_string(fields=>\@fields);

If fields is defined, then return a string which is made up of only that subset of the fields given by the @fields array.

field_names

my @field_names = @{$row_obj->field_names()};

Return the names of the fields in the order they were defined, rather than the random order that "keys" would give. This will either be the array which was used when the hash was tied, or the order that fields were read from a string if set_from_string or set_from_xml_string is called with override_fields true.

field_count

my $cnt = $row_obj->field_count($field_name);

Return the number of different field values for the given field in the given Row. A multi-valued field will give a count greater than 1.

If there is no value defined for the given field, then returns zero.

set_fields_as_vars

    $row_obj->set_fields_as_vars($package_name);

    $row_obj->set_fields_as_vars($package_name,
	field_ind=>$field_ind);

Sets the data of the hash as variables with the same name as the field name; multi-valued fields have arrays of the field name.

These are set in the given package.

Arguments:

field_ind

For multi-valued fields, the @Field variable is set, but also the $Field variable will be set, to the value of the variable with field_ind index. (default: 0)

match

    $row_obj->match(Author=>qr/Li.a/,
	    Universe=>'Buffy',
	    Year=>'> 2001')

Checks if this row matches the hash. The hash is in the form of Field => value pairs, where the value can be a plain value, a comparison (< > = eq ne ...) or a regular expression.

If the plain value or the comparison starts with '!' then the sense of the comparison is reversed.

Returns: 1 if matches all conditions, 0 if fails

match_any

$row_obj->match_any($match_str);

Checks if any field in this row matches the string.

Returns: 1 if any field matches the string, 0 if fails

Tie-Hash METHODS

TIEHASH

Create a new instance of the object as tied to a hash.

tie %person, 'Tie::FieldVals::Row', fields=>\@keys;

The fields argument defines the names of the legal fields. Legal fields can also be set from a string when using the override_keys argument to "set_from_string" or "set_from_xml_string".

FETCH

Get a key=>value from the hash. Some values may be multi-values, and can either be gotten as an array reference or joined together. If a key is not an official key, undefined is returned.

$val = $hash{$key}

Gets the value, or if it is a multi-value, gets the values joined by spaces.

$val = $hash{\$key}

Gets the whole key field as an array ref.

$match = {$key=>'##'};
$val = $hash{$match};

$match = [$key, '##'];
$val = $hash{$match};

Gets the value, or if it is a multi-value, gets the values joined by the given string (in this case, '##').

See also "field_count" to determine whether a field is a multi-valued field.

STORE

Add a key=>value to the hash. Either add a single value, or an array reference to create a multi-value.

If a key is not an official key, nothing is set, and it complains of error.

$hash{$key} = $val;
$hash{$key} = [$v1,$v2,$v3];

DELETE

Remove a key=>value from the hash, only if it exists.

CLEAR

Remove all the data from the hash.

EXISTS

Does this key exist?

FIRSTKEY

Get the first key of this hash.

NEXTKEY

Get the next key of this hash.

PRIVATE METHODS

For developer reference only.

debug

Set debugging on.

whowasi

For debugging: say who called this

is_matched($str,$re)

Check if the string matches the expression.

REQUIRES

Test::More
Carp

SEE ALSO

perl(1). Tie::FieldVals

BUGS

Please report any bugs or feature requests to the author.

AUTHOR

Kathryn Andersen (RUBYKAT)
perlkat AT katspace dot com
http://www.katspace.com

COPYRIGHT AND LICENCE

Copyright (c) 2004 by Kathryn Andersen

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.