branch-1-6/Bio/DB/QueryI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::DB::QueryI.pm
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Lincoln Stein <lstein@cshl.org>
   8 #
   9 # Copyright Lincoln Stein
  10 #
  11 # You may distribute this module under the same terms as perl itself
  12 #
  13 # POD documentation - main docs before the code
  14 #
  15
  16 =head1 NAME
  17
  18 Bio::DB::QueryI - Object Interface to queryable sequence databases
  19
  20 =head1 SYNOPSIS
  21
  22    # using Bio::DB::Query::GenBank as an example
  23    my $query_string = 'Oryza[Organism] AND EST[Keyword]';
  24    my $query = Bio::DB::Query::GenBank->new(-db=>'nucleotide',
  25                                             -query=>$query_string);
  26    my $count = $query->count;
  27    my @ids   = $query->ids;
  28
  29    # get a genbank database handle
  30    $gb = Bio::DB::GenBank->new();
  31    my $stream = $db->get_Stream_by_query($query);
  32    while (my $seq = $stream->next_seq) {
  33       ...
  34    }
  35
  36    # initialize the list yourself
  37    my $query = Bio::DB::Query::GenBank->new(-ids=>['X1012','CA12345']);
  38
  39 =head1 DESCRIPTION
  40
  41 This interface provides facilities for managing sequence queries such
  42 as those offered by Entrez.  A query object is created by calling
  43 new() with a database-specific argument list. From the query object
  44 you can either obtain the list of IDs returned by the query, or a
  45 count of entries that would be returned.  You can pass the query
  46 object to a Bio::DB::RandomAccessI object to return the entries
  47 themselves as a list or a stream.
  48
  49 =head1 FEEDBACK
  50
  51 =head2 Mailing Lists
  52
  53 User feedback is an integral part of the
  54 evolution of this and other Bioperl modules. Send
  55 your comments and suggestions preferably to one
  56 of the Bioperl mailing lists. Your participation
  57 is much appreciated.
  58
  59   bioperl-l@bioperl.org                  - General discussion
  60   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  61
  62 =head2 Support
  63
  64 Please direct usage questions or support issues to the mailing list:
  65
  66 I<bioperl-l@bioperl.org>
  67
  68 rather than to the module maintainer directly. Many experienced and
  69 reponsive experts will be able look at the problem and quickly
  70 address it. Please include a thorough description of the problem
  71 with code and data examples if at all possible.
  72
  73 =head2 Reporting Bugs
  74
  75 Report bugs to the Bioperl bug tracking system to help us keep track
  76 the bugs and their resolution.  Bug reports can be submitted via the
  77 web:
  78
  79   http://bugzilla.open-bio.org/
  80
  81 =head1 AUTHOR - Lincoln Stein
  82
  83 Email lstein@cshl.org
  84
  85 =head1 APPENDIX
  86
  87 The rest of the documentation details each of the
  88 object methods. Internal methods are usually
  89 preceded with a _
  90
  91 =cut
  92
  93 # Let the code begin...
  94
  95 package Bio::DB::QueryI;
  96 use strict;
  97
  98
  99 use base qw(Bio::Root::RootI);
 100
 101 =head2 new
 102
 103  Title   : new
 104  Usage   : $db = Bio::DB::QueryI->new(@args);
 105  Function: constructor
 106  Returns : QueryI object
 107  Args    : -query       a query string
 108            -ids         a list of ids as an arrayref
 109
 110 Create new QueryI object.  You may initialize with either a query
 111 string or with a list of ids.  If both ids and a query are provided,
 112 the former takes precedence.
 113
 114 Subclasses may recognize additional arguments.
 115
 116 =cut
 117
 118 =head2 count
 119
 120  Title   : count
 121  Usage   : $count = $db->count;
 122  Function: return count of number of entries retrieved by query
 123  Returns : integer
 124  Args    : none
 125
 126 Returns the number of entries that are matched by the query.
 127
 128 =cut
 129
 130 sub count   {
 131   my $self = shift;
 132   my @ids  = $self->ids;
 133   scalar @ids;
 134 }
 135
 136 =head2 ids
 137
 138  Title   : ids
 139  Usage   : @ids = $db->ids([@ids])
 140  Function: get/set matching ids
 141  Returns : array of sequence ids
 142  Args    : (optional) array ref with new set of ids
 143
 144 =cut
 145
 146 sub ids     {
 147   my $self = shift;
 148   $self->throw_not_implemented;
 149 }
 150
 151 =head2 query
 152
 153  Title   : query
 154  Usage   : $query = $db->query([$query])
 155  Function: get/set query string
 156  Returns : string
 157  Args    : (optional) new query string
 158
 159 =cut
 160
 161 sub query   {
 162   my $self = shift;
 163   $self->throw_not_implemented;
 164 }
 165
 166 1;