Bio/DescribableI.pm

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