## Babble/Document.pm
## Copyright (C) 2004 Gergely Nagy <algernon@bonehunter.rulez.org>
##
## This file is part of Babble.
##
## Babble is free software; you can redistribute it and/or modify it
## under the terms of the GNU General Public License as published by
## the Free Software Foundation; version 2 dated June, 1991.
##
## Babble is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
## for more details.
##
## You should have received a copy of the GNU General Public License
## along with this program; if not, write to the Free Software
## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
package Babble::Document;
use strict;
use Date::Manip;
=pod
=head1 NAME
Babble::Document - Babble document container class
=head1 DESCRIPTION
A Babble::Document object represents one entry in the whole collection
a Babble is working with.
=head1 PROPERTIES
A Babble::Document object has the following basic properties:
=over 4
=item author
The author of the document.
=item title
Title of the document.
=item subject
Subject of the document.
=item date
Submission date of the document.
=item id
A unique ID of the document, usually a hyperlink.
=item content
The actual content of the document.
=back
Other properties might be present, but they are not standardised by
this class. However, preprocessors and DataSources are free to add
others.
=head1 METHODS
=over 4
=item new()
Creates a new Babble::Document object. Recognises the default
properties mentioned above as arguments.
=cut
sub new {
my $type = shift;
my %params = @_;
my $self = bless {
author => $params{author},
content => $params{content},
subject => $params{subject},
title => $params{title},
id => $params{id},
date => $params{date},
}, $type;
return $self;
}
=pod
=item date()
Get or set the submission date of the document, depending on having an
argument or not.
=cut
sub date (;$) {
my ($self, $nv) = @_;
$self->{date} = ParseDate ($nv) if (defined $nv);
return $self->{date};
}
=pod
=item date_iso()
Returns the submission date of the document in the
"YYYY-MM-DD HH:MM:SS" format.
=cut
sub date_iso () {
my $self = shift;
return UnixDate ($self->{date}, "%Y-%m-%d %H:%M:%S");
}
=pod
=item date_rss()
Returns the submission date of the document in a format suitable for
putting into an RSS item's dc:date field.
=cut
sub date_rss () {
my $self = shift;
return UnixDate ($self->{date}, "%Y-%m-%dT%H:%M:%S+00:00");
}
=pod
=item date_text()
Returns the submission date of the document in human readable format.
=cut
sub date_text () {
my $self = shift;
return UnixDate ($self->{date}, "%d %B, %Y %H:%M");
}
=pod
=item date_date()
Returns only the date part of the documents submission date.
=cut
sub date_date () {
my $self = shift;
return UnixDate ($self->{date}, "%Y-%m-%d");
}
=pod
=item search($filters)
Given a list of filters (see later) in an arrayref, checks if the
document matches all the criteria specified in them. If yes, returns
an array consisting of the Babble::Document object. Otherwise returns
an empty array.
The filters are simple hashrefs, with two mandatory keys: I<field> and
I<pattern>. The first one determines which field the search is
performed on (this can be any one of the available Babble::Document
properties), and I<pattern> is the pattern it should match.
Optional keys include I<inverse>, which reverses the check, and
I<cmp>, which will be used as a comparsion function if set, instead of
the default regexp matcher.
=cut
sub search {
my ($self, $filters) = @_;
my $match = 1;
foreach my $filter (@$filters) {
unless ($self->{$filter->{field}}) {
next if ($filter->{inverse});
$match = 0;
last;
}
my $cmp = $filter->{cmp} ||
sub {
my ($a, $b) = @_;
return $a =~ /$b/;
};
my $res = &$cmp ($self->{$filter->{field}},
$filter->{pattern});
if ((!$res && !$filter->{inverse}) ||
($res && $filter->{inverse})) {
$match = 0;
last;
}
}
return ($self) if $match;
return ();
}
=pod
=item all()
Return ourselves. This is mostly here so that
Babble::Document::Collection->all() can call $doc->all(), which in
turn makes it possible to have Babble::Document::Collections nested,
and still work.
=cut
sub all () {
return ($_[0]);
}
=pod
=back
=head1 AUTHOR
Gergely Nagy, algernon@bonehunter.rulez.org
Bugs should be reported at L<http://bugs.bonehunter.rulez.org/babble>.
=head1 SEE ALSO
Babble, Babble::Document::Collection
=cut
1;
# arch-tag: ac55e89f-a93d-4b5f-87c7-b72f903352d7