Bio/DB/QueryI.pm

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