NAME

App::RecordStream::Record

AUTHOR

Benjamin Bernard <perlhacker@benjaminbernard.com> Keith Amling <keith.amling@gmail.com>

DESCRIPTION

An object representing a single record of recs input/output. This is a glorified hash with some helper methods.

SYNOPSIS

    use App::RecordStream::Record;
    my $record = App::RecordStream::Record->new("name" => "John Smith", "age" => 39);

CONSTRUCTOR

App::RecordStream::Record->new(%hash);

Construct a new record with provided keys and values. Can take a single argument which is a hash ref. If this form is used, it will bless that hash and use it, so that hash ref now belongs to this object. This avoids memory copies

METHODS

@keys = $this->keys();

Returns an array of field names.

$boolean = $this->exists($key);

Determine whether or not this field exists in the record.

$value = $this->get($key);

Retrieve a field from the record, returns undef if there is no such field.

$old_value = $this->get_XXX();

Calls $this->get("XXX");

$old_value = $this->set($key, $value);

Set a field in the record, returns the old value, or undef if there was no such field.

$old_value = $this->set_XXX($value);

Calls $this->set("XXX", $value);

@old_values = $this->remove(@keys);

Remove fields from the record, returns the old values (or undef for each missing).

$this->prune_to(@keys);

Removes fields whose names are not among those provided.

$this->rename($old_key, $new_key);

Rename a field. If the field did not exists a new field with value undef is created.

%hash = $this->as_hash();

Marshall a record into hash format.

$hashref = $this->as_hashref();

Marshall a record into hash format, returning a reference. The caller may modify this hash (the changes will not be reflected in the record itself).

$cmp = $this->cmp($that, @keys);

Compare this record to another, using comparators derived from @keys (see get_comparators). Returns -1, 0, or 1 for $this before $that, $this same as $that, and $this after $that, respectively.

$value_ref = $this->guess_key_from_spec($keyspec, $no_vivify = 0, $throw_error = 0)

Get the reference for a key spec. Commonly used like:

${$r->guess_key_from_spec('foo/bar')} eq 'zip' ${$r->guess_key_from_spec('foo/bar')} = 'boo'

(the assign back gets back into the record)

no_vivify and no_error are optional, and control behavior in the absence of the specified key. throw_error will cause a 'NoSuchKey' exception to be thrown.

See 'man recs' for more info on key specs

$boolean = $this->has_key_spec($spec)

Returns a boolean indicating the presence of the key spec in the record. Will not have side effects in the record.

$ARRAY_REF = $this->get_key_list_for_spec($spec)

Returns a list of keys that the spec expanded out to. Arrrays will still be #NUM, hash keys will be fully expanded to the keys present in the record.

$keyspecs_array_ref = $this->get_keys_for_group($key_group, $rerun)

Will create a App::RecordStream::KeyGroups (if necessary) and return the keyspecs that match the given group. See --help-keyspecs or App::RecordStream::KeyGroups for more information.

Setting rerun to true will cause every record this is called on to re-do keygroup calculation

$values_array_ref = $this->get_group_values($key_group, $rerun)

Returns the values in this record for a key group. Will rerun keygroup parsing if $rerun is passed

$comparators_ref = App::RecordStream::Record::get_comparators(@specs)

Calls get_comparator for each element of @specs and returns the results together in an array reference.

$comparator = App::RecordStream::Record::get_comparator($spec)

Produces a comparator function (which takes two records and returns similarly to <=> or cmp) from the provided $spec. $spec should be like "<field>" for lexical sort, or "<field>=<sign><type><star>" where <sign> is "+" or "" for ascending or "-" for descending and type is one of the known types and <star> is "*" for sorting "ALL" to the end or "" for normal behaviour. Type include "", "l", "lex", or "lexical" for lexical sort (using cmp), and "n", "num" or "numeric" for numeric sort (using <=>).

@sorted_records = App::RecordStream::Record::sort($records_ref, @specs)

Sorts an array ref of records using the provided specs, returns an array of records.