Bio/DescribableI.pm

   1 # $Id$
   2
   3 #
   4 # This module is licensed under the same terms as Perl itself. You use,
   5 # modify, and redistribute it under the terms of the Perl Artistic License.
   6 #
   7
   8 =head1 NAME
   9
  10 Bio::DescribableI - interface for objects with human readable names and descriptions
  11
  12 =head1 SYNOPSIS
  13
  14
  15     # to test this is a describable object
  16
  17     $obj->isa("Bio::DescribableI") ||
  18       $obj->throw("$obj does not implement the Bio::DescribableI interface");
  19
  20     # accessors
  21
  22     $name = $obj->display_name();
  23     $desc = $obj->description();
  24
  25
  26
  27 =head1 DESCRIPTION
  28
  29 This interface describes methods expected on describable objects, ie
  30 ones which have human displayable names and descriptions
  31
  32 =head1 FEEDBACK
  33
  34 =head2 Mailing Lists
  35
  36 User feedback is an integral part of the evolution of this and other
  37 Bioperl modules. Send your comments and suggestions preferably to one
  38 of the Bioperl mailing lists.  Your participation is much appreciated.
  39
  40   bioperl-l@bioperl.org                  - General discussion
  41   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  42
  43 =head2 Reporting Bugs
  44
  45 Report bugs to the Bioperl bug tracking system to help us keep track
  46 the bugs and their resolution.  Bug reports can be submitted via the web:
  47
  48   http://bugzilla.open-bio.org/
  49
  50 =head1 AUTHOR - Ewan Birney
  51
  52 Email birney@sanger.ac.uk
  53
  54 =cut
  55
  56 package Bio::DescribableI;
  57 use strict;
  58
  59
  60 use base qw(Bio::Root::RootI);
  61
  62 =head1 Implementation Specific Functions
  63
  64 These functions are the ones that a specific implementation must
  65 define.
  66
  67 =head2 display_name
  68
  69  Title   : display_name
  70  Usage   : $string    = $obj->display_name()
  71  Function: A string which is what should be displayed to the user
  72            the string should have no spaces (ideally, though a cautious
  73            user of this interface would not assumme this) and should be
  74            less than thirty characters (though again, double checking
  75            this is a good idea)
  76  Returns : A scalar
  77  Status  : Virtual
  78
  79 =cut
  80
  81 sub display_name {
  82    my ($self) = @_;
  83    $self->throw_not_implemented();
  84 }
  85
  86
  87 =head2 description
  88
  89  Title   : description
  90  Usage   : $string    = $obj->description()
  91  Function: A text string suitable for displaying to the user a
  92            description. This string is likely to have spaces, but
  93            should not have any newlines or formatting - just plain
  94            text. The string should not be greater than 255 characters
  95            and clients can feel justified at truncating strings at 255
  96            characters for the purposes of display
  97  Returns : A scalar
  98  Status  : Virtual
  99
 100 =cut
 101
 102 sub description {
 103    my ($self) = @_;
 104    $self->throw_not_implemented();
 105 }
 106
 107 1;