NAME

WARC::Index::Entry - abstract base class for WARC::Index entries

SYNOPSIS

  use WARC;             # or ...
  use WARC::Index;

  # WARC::Index::Entry objects are returned from directly searching an index

  # match search criteria against entry
  $distance = $entry->distance( ... );
  @report = $entry->distance( ... );

  $index = $entry->index;       # get index containing entry
  $volume = $entry->volume;     # get WARC::Volume containing record
  $record = $entry->record;     # get WARC record

DESCRIPTION

Common Methods

Entries from all index systems support these methods:

@report = $entry->distance( ... )

$distance = $entry->distance( ... )

In list context, return a detailed report mapping each search key to a distance value. In scalar context, return an overall summary distance, such that sorting entries by the return values of this method in ascending order will place the closest matches at the top of the list.

A valid distance is non-negative. Negative distance values indicate that the record does not match the criteria at all. An undefined value indicates that the entry is from an index that does not store the information needed to evaluate distance for that search key. Undefined values are ignored when computing the summarized distance, but the summarized distance will be negative if any keys do not match at all and itself undefined if none of the requested keys can be evaluated.

For details on available search keys, see the "Search Keys" section of the WARC::Collection page. If multiple values are given in an arrayref, the best match is reported.

$index = $entry->index

Return the WARC::Index containing this entry.

$volume = $entry->volume

Return the WARC::Volume object representing the file in which this index entry's record is located.

$record = $entry->record( ... )

Return the WARC::Record this index entry represents. Arguments if given are additional key => value pairs for the record object.

$record_offset = $entry->record_offset

Return the file offset at which this index entry's record is located.

$value = $entry->value( $key )

Return the value this index entry holds for a given search key.

$tag = $entry->tag

Return a tag for this index entry. The exact format of the tag is unspecified and platform-dependent. Two index entries that refer to different records are guaranteed (if the underlying system software behaves correctly) to have different tag values, while two entries that refer to the same record in the same volume will normally have the same tag value, except in edge cases.

Optional Methods

Some index entries may additionally support any of these methods:

$next_entry = $entry->next

Indexes with an inherent sequence of entries may provide a method to obtain the next entry in the index. Some index systems have this, while others do not have a meaningful order amongst their entries.

$position = $entry->entry_position

Indexes with an inherent sequence of entries may provide a method to obtain some kind of index-specific entry number or location parameter. This is most useful for metaindexes to record the location of an index entry.

AUTHOR

Jacob Bachmeyer, <jcb@cpan.org>

SEE ALSO

WARC, WARC::Index

COPYRIGHT AND LICENSE

Copyright (C) 2019 by Jacob Bachmeyer

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