Bio/Biblio/Ref.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Biblio::Ref
   4 #
   5 # Cared for by Martin Senger <senger@ebi.ac.uk>
   6 # For copyright and disclaimer see below.
   7
   8 # POD documentation - main docs before the code
   9
  10 =head1 NAME
  11
  12 Bio::Biblio::Ref - Representation of a bibliographic reference
  13
  14 =head1 SYNOPSIS
  15
  16     $obj = Bio::Biblio::Ref->new(-type  => 'Letter',
  17                                  -title => 'Onegin to Tatiana');
  18   #--- OR ---
  19
  20     $obj = Bio::Biblio::Ref->new();
  21     $obj->type ('Letter');
  22
  23 =head1 DESCRIPTION
  24
  25 A storage object for a general bibliographic reference (a citation).
  26 See its place in the class hierarchy in
  27 http://www.ebi.ac.uk/~senger/openbqs/images/bibobjects_perl.gif
  28
  29 =head2 Attributes
  30
  31 The following attributes are specific to this class,
  32 and they are inherited by all citation types.
  33
  34   author_list_complete            values: 'Y'  (default) or 'N'
  35   authors                         type:   array ref of Bio::Biblio::Provider's
  36   cross_references                type:   array ref of Bio::Annotation::DBLink's
  37   cross_references_list_complete  values: 'Y' (default) or 'N'
  38   abstract
  39   abstract_language
  40   abstract_type
  41   codes                           type:   hash ref
  42   contributors                    type:   array ref of Bio::Biblio::Provider's
  43   date
  44   date_completed
  45   date_created
  46   date_revised
  47   format
  48   identifier
  49   keywords
  50   language
  51   last_modified_date
  52   publisher                       type:   Bio::Biblio::Provider
  53   repository_subset
  54   rights
  55   spatial_location
  56   subject_headings                type:   hash ref
  57   subject_headings_source
  58   temporal_period
  59   title
  60   toc
  61   toc_type
  62   type
  63
  64 =head1 SEE ALSO
  65
  66 =over 4
  67
  68 =item *
  69
  70 OpenBQS home page: http://www.ebi.ac.uk/~senger/openbqs/
  71
  72 =item *
  73
  74 Comments to the Perl client: http://www.ebi.ac.uk/~senger/openbqs/Client_perl.html
  75
  76 =back
  77
  78 =head1 FEEDBACK
  79
  80 =head2 Mailing Lists
  81
  82 User feedback is an integral part of the evolution of this and other
  83 Bioperl modules. Send your comments and suggestions preferably to
  84 the Bioperl mailing list.  Your participation is much appreciated.
  85
  86   bioperl-l@bioperl.org                  - General discussion
  87   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  88
  89 =head2 Reporting Bugs
  90
  91 Report bugs to the Bioperl bug tracking system to help us keep track
  92 of the bugs and their resolution. Bug reports can be submitted via the
  93 web:
  94
  95   http://bugzilla.open-bio.org/
  96
  97 =head1 AUTHORS
  98
  99 Heikki Lehvaslaiho (heikki-at-bioperl-dot-org),
 100 Martin Senger (senger@ebi.ac.uk)
 101
 102 =head1 COPYRIGHT
 103
 104 Copyright (c) 2002 European Bioinformatics Institute. All Rights Reserved.
 105
 106 This module is free software; you can redistribute it and/or modify
 107 it under the same terms as Perl itself.
 108
 109 =head1 DISCLAIMER
 110
 111 This software is provided "as is" without warranty of any kind.
 112
 113 =head1 APPENDIX
 114
 115 The rest of the documentation details each of the object
 116 methods. Internal methods are preceded with a _
 117
 118 =cut
 119
 120
 121 # Let the code begin...
 122
 123
 124 package Bio::Biblio::Ref;
 125 use strict;
 126 use vars qw($AUTOLOAD);
 127
 128 use Bio::Annotation::DBLink;
 129
 130 use base qw(Bio::Biblio::BiblioBase);
 131
 132 #
 133 # a closure with a list of allowed attribute names (these names
 134 # correspond with the allowed 'get' and 'set' methods); each name also
 135 # keep what type the attribute should be (use 'undef' if it is a
 136 # simple scalar)
 137 #
 138 {
 139     my %_allowed =
 140         (
 141          _author_list_complete => undef,
 142          _authors => 'ARRAY',  # of Bio::Biblio::Provider
 143          _cross_references => 'ARRAY',   # of Bio::Annotation::DBLink
 144          _cross_references_list_complete => undef,
 145          _abstract => undef,
 146          _abstract_language => undef,
 147          _abstract_type => undef,
 148          _codes => 'HASH',
 149          _contributors => 'ARRAY',  # of Bio::Biblio::Provider
 150          _date => undef,
 151          _date_completed => undef,
 152          _date_created => undef,
 153          _date_revised => undef,
 154          _format => undef,
 155          _identifier => undef,
 156          _keywords => 'HASH',
 157          _language => undef,
 158          _last_modified_date => undef,
 159          _publisher => 'Bio::Biblio::Provider',
 160          _repository_subset => undef,
 161          _rights => undef,
 162          _spatial_location => undef,
 163          _subject_headings => 'HASH',
 164          _subject_headings_source => undef,
 165          _temporal_period => undef,
 166          _title => undef,
 167          _toc => undef,
 168          _toc_type => undef,
 169          _type => undef,
 170          );
 171
 172     # return 1 if $attr is allowed to be set/get in this class
 173     sub _accessible {
 174         my ($self, $attr) = @_;
 175         exists $_allowed{$attr};
 176     }
 177
 178     # return an expected type of given $attr
 179     sub _attr_type {
 180         my ($self, $attr) = @_;
 181         $_allowed{$attr};
 182     }
 183 }
 184
 185
 186 =head2 add_cross_reference
 187
 188  Usage   : $self->add_cross_reference
 189                (Bio::Annotation::DBLink->new(-database   => 'EMBL',
 190                                              -primary_id => 'V00808');
 191  Function: adding a link to a database entry
 192  Returns : new value of 'cross_references'
 193  Args    : an object of type Bio::Annotation::DBLink
 194
 195 =cut
 196
 197 sub add_cross_reference {
 198     my ($self, $value) = @_;
 199     $self->throw ($self->_wrong_type_msg (ref $value, 'Bio::Annotation::DBLink'))
 200         unless (UNIVERSAL::isa ($value, 'Bio::Annotation::DBLink'));
 201     (defined $self->cross_references) ?
 202         push (@{ $self->cross_references }, $value) :
 203             return $self->cross_references ( [$value] );
 204     return $self->cross_references;
 205 }
 206
 207
 208 =head2 add_author
 209
 210  Usage   : $self->add_author (Bio::Biblio::Person->new(-lastname => 'Novak');
 211  Function: adding an author to a list of authors
 212  Returns : new value of 'authors' (a full list)
 213  Args    : an object of type Bio::Biblio::Provider
 214
 215 =cut
 216
 217
 218 sub add_author {
 219     my ($self, $value) = @_;
 220     $self->throw ($self->_wrong_type_msg (ref $value, 'Bio::Biblio::Provider'))
 221         unless (UNIVERSAL::isa ($value, 'Bio::Biblio::Provider'));
 222     (defined $self->authors) ?
 223         push (@{ $self->authors }, $value) :
 224             return $self->authors ( [$value] );
 225     return $self->authors;
 226 }
 227
 228 =head2 add_contributor
 229
 230  Usage   : $self->add_contributor (Bio::Biblio::Person->new(-lastname => 'Novak');
 231  Function: adding a contributor to a list of contributors
 232  Returns : new value of 'contributors' (a full list)
 233  Args    : an object of type Bio::Biblio::Provider
 234
 235 =cut
 236
 237 sub add_contributor {
 238     my ($self, $value) = @_;
 239     $self->throw ($self->_wrong_type_msg (ref $value, 'Bio::Biblio::Provider'))
 240         unless (UNIVERSAL::isa ($value, 'Bio::Biblio::Provider'));
 241     (defined $self->contributors) ?
 242         push (@{ $self->contributors }, $value) :
 243             return $self->contributors ( [$value] );
 244     return $self->contributors;
 245 }
 246
 247
 248 1;
 249 __END__