lib/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://github.com/bioperl/bioperl-live/issues
  59
  60 =head1 AUTHOR - Ewan Birney
  61
  62 Email birney@sanger.ac.uk
  63
  64 =cut
  65
  66 package Bio::DescribableI;
  67
  68 use strict;
  69
  70
  71 use base qw(Bio::Root::RootI);
  72
  73 =head1 Implementation Specific Functions
  74
  75 These functions are the ones that a specific implementation must
  76 define.
  77
  78 =head2 display_name
  79
  80  Title   : display_name
  81  Usage   : $string    = $obj->display_name()
  82  Function: A string which is what should be displayed to the user
  83            the string should have no spaces (ideally, though a cautious
  84            user of this interface would not assume this) and should be
  85            less than thirty characters (though again, double checking
  86            this is a good idea)
  87  Returns : A scalar
  88  Status  : Virtual
  89
  90 =cut
  91
  92 sub display_name {
  93    my ($self) = @_;
  94    $self->throw_not_implemented();
  95 }
  96
  97
  98 =head2 description
  99
 100  Title   : description
 101  Usage   : $string    = $obj->description()
 102  Function: A text string suitable for displaying to the user a
 103            description. This string is likely to have spaces, but
 104            should not have any newlines or formatting - just plain
 105            text. The string should not be greater than 255 characters
 106            and clients can feel justified at truncating strings at 255
 107            characters for the purposes of display
 108  Returns : A scalar
 109  Status  : Virtual
 110
 111 =cut
 112
 113 sub description {
 114    my ($self) = @_;
 115    $self->throw_not_implemented();
 116 }
 117
 118 1;