NAME

Text::Shoebox::Entry - class for Shoebox SF lexicon entries

SYNOPSIS

  use Text::Shoebox::Lexicon;
  my $lex = Text::Shoebox::Lexicon->read_file( "haida.sf" );

  foreach my $entry ($lex->entries) {
    #
    # Each $entry is a Text::Shoebox::Entry object
    #
    my %e = $entry->as_list;
    print "Looky, stuff! [", %e, "]!\n";
  }

DESCRIPTION

An object of this class represents an entry in an SF lexicon (Text::Shoebox::Lexicon).

An entry consists of a number of fields. Each field has two scalars, a key, and a value. The first field in an entry is considered the headword field, and its key must occur there and only there in that entry. There is no requirement on uniqueness of keys in the rest of the entry.

METHODS

$entry = Text::Shoebox::Entry->new();

$entry = Text::Shoebox::Entry->new( 'foo' => 'bar', 'baz' => 'quux' );

The new method creates a new Text::Shoebox::Entry method. If you provide parameters, as in the second example, those are used as the contents of the new object.

Normally you don't need to expressly create objects of this class, as Text::Shoebox::Lexicon will create them as needed when you call a Text::Shoebox::Lexicon read_file or read_handle method.

$entry2 = $entry->copy

This returns a copy of the object in $entry.

@keys = $entry->keys;

This returns the names of all the keys (a/k/a fieldnames) in this entry. For example, if $entry is ('hw' => 'foo', 'ex' => 'Things', 'ex' => "Stuff"), then $entry->keys will return the list ('hw', 'ex', 'ex').

@values = $entry->values;

This returns the values of all fields in this entry. For example, if $entry is ('hw' => 'foo', 'ex' => 'Things', 'ex' => "Stuff"), then $entry->values will return the list ('foo', 'Things', 'Stuff').

$headword = $entry->headword;

This returns the headword value of this entry. This is basically a shortcut for ($entry->values)[0]

$headword_field = $entry->headword_field;

This returns the fieldname of this entry's headword field. This is basically a shortcut for ($entry->keys)[0]

$value = $entry->_(keyname)

Yes, this method really is called _ !

This gets all the values of the pairs that have the key keyname. How it returns those values (of which there may be none, one, or many) depends on context:

In list context, this simply returns the list of found values. E.g., if $entry is ('hw' => 'foo', 'ex' => 'Things', 'ex' => "Stuff"), then $entry->_('hw') returns the one-item list ('foo'), then $entry->_('zorp') returns the zero-item list (), and $entry->_('ex') returns the two-item list ('Things', 'Stuff').

In scalar context, this returns undef if no values were found. Otherwise it returns a magical arrayref containing the list of (one or more) found values. What's special about these arrayrefs is that if you treat one as a plain string, you get the useful value join "; ", @$array_ref), instead of nonsense like "ARRAY(0x1555294)".

(Internally, this is implemented just like Array::Autojoin, which see.)

my $num_pairs = $entry->pair_count;

This returns an integer expressing the number of pairs in this entry. It's basically the same as scalar($entry->keys).

($key, $val) = $entry->pair($n)

This returns the key and value of pair number $n for this entry. E.g., if $entry is ('hw' => 'foo', 'ex' => 'Things', 'ex' => "Stuff"), then $entry->pair(1) is the list ('ex', 'Things').

($key, $val, $k2, $v2) = $entry->pairs($n, $m)

This returns the key and value of pair number $n and the key and value of pair number $m for this entry. E.g., if $entry is ('hw' => 'foo', 'ex' => 'Things', 'ex' => "Stuff"), then $entry->pair(0,2) is the list ('hw' = 'foo', 'ex', "Stuff")>.

(Actually, $entry->pair(...) is just an alias to $entry->pairs(...).)

$true_or_false = $entry->are_keys_unique;

This returns true iff every keyname in this entry appears only once.

$entry->assert_keys_unique;

This dies unless $entry->are_keys_unique is true.

$true_or_false = $entry->is_null

This returns true iff this entry is empty. This is basically the same as 0 == $entry->pair_count.

$true_or_false = $entry->is_sane

This returns true iff this entry is non-null, contains no references, and if no keyname is undef or zero-length.

$entry->scrunch;

For all values in this entry, this compacts all whitespace, deletes leading and trailing whitespace, and deletes any pairs where the value is blank. (Where "blank" means undef, zero-length, or is all-whitespace.)

$entry->dump;

This prints (not returns!) a representation of this object's contents.

@it = $entry->as_list

This returns a list expressing the contents of $entry. For example, if $entry is ('hw' => 'foo', 'ex' => 'Things', 'ex' => "Stuff"), then this returns just that, ('hw' => 'foo', 'ex' => 'Things', 'ex' => "Stuff").

$them = $entry->as_arrayref

This returns an arrayref (probably blessed) to the contents of $entry. For example, if $entry is ('hw' => 'foo', 'ex' => 'Things', 'ex' => "Stuff"), then this will return an arrayred to just that list.

Note that this (and as_HoLS) is like the other as_thing methods, in that this doesn't return any sort of copy; it returns a reference to the entry's array itself -- if you do $them->[1] = 'x', then $entry's contents change to ('hw' => 'x', 'ex' => 'Things', 'ex' => "Stuff").)

(Internally, this method is implemented by simply returning $entry itself, since in the current implementation, $entry is just a blessed arrayref to the (k,v,k,v,...) list it contains.)

$h = $entry->as_hashref

This returns a hashref expressing the contents of $entry as a {key => value,...} hash, discarding duplicates. For example, if $entry is ('hw' => 'foo', 'ex' => 'Things', 'ex' => "Stuff"), then this returns { 'hw' => 'foo', 'ex' => "Stuff" }.

$hol = $entry->as_HoL

This returns a reference to a hash-of-lists expressing the contents of this entry, i.e., a reference to a hash where every value is an arrayref. Note that this doesn't destroy duplicates.

For example, if $entry is ('hw' => 'foo', 'ex' => 'Things', 'ex' => "Stuff"), then this returns { 'hw' => ['foo'], 'ex' => ['Things', 'Stuff'] }.

And there's a useful bit of magic added -- the arrayrefs aren't just plain arrayrefs, they're special arrayrefs (implemented just like Array::Autojoin) such that if you treat one as a plain string, you get the useful value join "; ", @$array_ref), instead of nonsense like "ARRAY(0x1555294)".

$hol = $entry->as_HoLS

This returns a hashref where every value is a reference to an array of scalar-refs to the value-slots in $entry. This is so you can alter $entry. (This and $entry->as_arrayref are really the only ways to alter an entry objects's content.)

This sounds (and is) very circuitous, but it's like this: If $entry is ('hw' => 'foo', 'ex' => 'Things', 'ex' => "Stuff"), then this returns { 'hw' => [$fooslot], 'ex' => [$thingsslot, $stuffslot] }, where if you do $$thingslot = 'gack', then $entry then becomes ('hw' => 'foo', 'ex' => 'gack', 'ex' => "Stuff").

$hol = $entry->as_doublets

This returns this entry as a list of "doublets" -- i.e., as a list of two-item arrayrefs.

For example, if $entry is ('hw' => 'foo', 'ex' => 'Things', 'ex' => "Stuff"), then this returns the list (['hw','foo'], ['ex','Things'], ['ex','Stuff']).

$xml_source = $entry->as_xml()

$xml_source = $entry->as_xml( TagNameHash )

This returns an XML representation of this entry's contents. In short, For example, if $entry is ('hw' => 'foo', 'ex' => 'Things', 'ex' => "Stuff"), then this returns this string:

    <hw>foo</hw>
    <ex>Things</ex>
    <ex>Stuff</ex>

The only details arise from the problem of how to turn $entry's keynames into XML tag names. For each key, if it's present in the optional TagNameHash hashref parameter, then that value ($tagnamehash->{$keyname}) is used; otherwise, $keyname itself is used, stripped of characters other than a-zA-Z0-9, colon, underscore, period, and dash.

$xml_source = $entry->as_xml_pairs()

$xml_source = $entry->as_xml_pairs( PairTagName, KeyAttrName, ValAttrName)

This returns an XML representation of this entry's contents. In short, For example, if $entry is ('hw' => 'foo', 'ex' => 'Things', 'ex' => "Stuff"), then this returns this string:

    <pair key="hw" value="foo" />
    <pair key="ex" value="Things" />
    <pair key="ex" value="Stuff" />

This avoids the problem of how to turn keynames into XML tagnames. If you don't like the choice of the pair tagname (by default, "pair") or the key attribute name (by default, "key"), or the value attribute name (by default, "value"), then you can specify new values as the parameters. So if you call $entry->as_xml_pairs( 'fee' , 'fie', 'Foe:Fum'), the return value is:

    <fee fie="hw" Foe:Fum="foo" />
    <fee fie="ex" Foe:Fum="Things" />
    <fee fie="ex" Foe:Fum="Stuff" />

COPYRIGHT

Copyright 2004, Sean M. Burke sburke@cpan.org, all rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Sean M. Burke, sburke@cpan.org

I hasten to point out, incidentally, that I am not in any way affiliated with the Summer Institute of Linguistics.