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

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

    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
    }

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.

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 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 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)

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.

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.

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.

    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.

    $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)

    $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

$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

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.

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.

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];

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

Remove all the data from the hash.

Does this key exist?

Get the first key of this hash.

Get the next key of this hash.

For developer reference only.

Set debugging on.

For debugging: say who called this

Check if the string matches the expression.

    Test::More
    Carp

perl(1). Tie::FieldVals

Please report any bugs or feature requests to the author.

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

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.