File Coverage

blib/lib/Dezi/Doc.pm

Criterion	Covered	Total	%
statement	15	32	46.8
branch	0	10	0.0
condition			n/a
subroutine	5	8	62.5
pod	3	3	100.0
total	23	53	43.4

package Dezi::Doc;
use Moo;
use Types::Standard qw( Str Int Num HashRef );
use Carp;
use Search::Tools::XML;
use namespace::autoclean;

our $VERSION = '0.003004';

has 'mime_type' => ( is => 'rw', isa => Str );
has 'summary'   => ( is => 'rw', isa => Str );
has 'title'     => ( is => 'rw', isa => Str );
has 'content'   => ( is => 'rw', isa => Str );
has 'uri'       => ( is => 'rw', isa => Str );
has 'mtime'     => ( is => 'rw', isa => Int );
has 'size'      => ( is => 'rw', isa => Int );
has 'score'     => ( is => 'rw', isa => Num );
has '_fields'   => ( is => 'rw', isa => HashRef );

=pod

=head1 NAME

Dezi::Doc - a Dezi client document

=head1 SYNOPSIS

 # add doc to the index
 use Dezi::Doc;
 my $html = "hello world";
 my $doc = Dezi::Doc->new(
     mime_type => 'text/html',
     uri       => 'foo/bar.html',
     mtime     => time(),
     size      => length $html,
     content   => $html,
 );
 $client->index( $doc );

 # construct a document with field/value pairs
 my $doc2 = Dezi::Doc->new(
    uri => 'auto/xml/magic',
 );
 $doc2->set_field('title' => 'ima dezi doc');
 $doc2->set_field('body'  => 'hello world!');
 $client->index( $doc2 );

 # search results are also Dezi::Doc objects
 for my $doc (@{ $response->results }) {
     printf("hit: %s %s\n", $doc->score, $doc->uri);
 }

=head1 DESCRIPTION

Dezi::Doc represents one document in a collection.

=head1 METHODS

=head2 new

Create new object. Takes pairs of key/values where the keys are one of:

=over

=item mime_type

Sometimes known as the content type. A MIME type indicates the kind
of document this is.

=item uri

The unique URI for the document.

=item mtime

Last modified time. Should be expressed in Epoch seconds.

=item size

Length in bytes.

=item content

The document's content.

=back

=cut

=head2 score

When returned from a Dezi::Response->results array,
the score attribute is the search ranking score.

=head2 title

When returned from a Dezi::Response->results array,
the title is the document's parsed title.

B you cannot set the title of a doc object when
sending to the index. See set_field() instead.

=head2 summary

When returned from a Dezi::Response->results array,
the summary is the snipped and highlighted extract
from the document showing query terms in context.

B you cannot set the summary of a doc object when
sending to the index. The summary is a result field only.
It typically represents all or snipped part of the
C field in the index.

=cut

=head2 as_string_ref

Returns a scalar ref pointing at the Dezi::Doc serialized,
either the value of content() or a XML fragment representing
values set with set_field().

=cut

sub as_string_ref {
    my $self = shift;
    if ( exists $self->{_fields} ) {
        my $xml
            = Search::Tools::XML->perl_to_xml( $self->{_fields}, 'doc', 1 );
        return \$xml;
    }
    else {
        my $content = $self->content;
        return \$content;
    }
}

=head2 get_field( I )

Returns the value of I.

=cut

sub get_field {
    my $self = shift;
    my $name = shift or croak "field_name required";
    if ( !exists $self->{_fields}->{$name} ) {
        return undef;
    }
    return $self->{_fields}->{$name};
}

=head2 set_field( I => I )

Set the I for field I.

This method also sets the mime_type() of the document object
to 'application/xml' since that is how as_string_ref() will
render the object.

=cut

sub set_field {
    my $self  = shift;
    my $field = shift or croak "field_name required";
    my $value = shift;
    croak "value required" unless defined $value;
    $self->{_fields}->{$field} = $value;
    $self->mime_type('application/xml');
}

1;

__END__