# parse primer3 output to get some data
 # this is also called from Bio::Tools::Run::Primer3

 use Bio::Tools::Primer3;

 # read a primer3 output file
 my $p3=Bio::Tools::Primer3->new(-file=>"data/primer3_output.txt");

 # how many results were there?
 my $num=$p3->number_of_results;
 print "There were $num results\n";

 # get all the results
 my $all_results=$p3->all_results;
 print "ALL the results\n";
 foreach my $key (keys %{$all_results}) {print "$key\t${$all_results}{$key}\n"}

 # get specific results
 my $result1=$p3->primer_results(1);
 print "The first primer is\n";
 foreach my $key (keys %{$result1}) {print "$key\t${$result1}{$key}\n"}

 # get the results as a Bio::Seq::PrimedSeq stream
 my $primer=$p3->next_primer;
 print "The left primer in the stream is ", $primer->get_primer('-left_primer')->seq->seq, "\n";

 Bio::Tools::Primer3 creates the input files needed to design primers using
 primer3 and provides mechanisms to access data in the primer3 output files.

 This module provides a bioperl interface to the program primer3. See 
 http://www-genome.wi.mit.edu/genome_software/other/primer3.html
 for details and to download the software.

 This module is based on one written by Chad Matsalla (bioinformatics1@dieselwurks.com)

 I have ripped some of his code, and added a lot of my own. I hope he's not mad at me!

 This is probably best run in one of the two following ways:
  i. To parse the output from Bio::Tools::Run::Primer3. 
     You'll most likely just use next_primer to get the results from Bio::Tools::Run::Primer3.
  ii. To parse the output of primer3 handed to it as a file name.

 @PRIMER3_PARAMS=qw(results seqobject);

 foreach my $attr (@PRIMER3_PARAMS) {$OK_FIELD{$attr}++

 my $self = shift;
 my $attr = $AUTOLOAD;
 $attr =~ s/.*:://;
 $self->throw("Unallowed parameter: $attr !") unless $OK_FIELD{$attr};
 $self->{$attr} = shift if @_;
 return $self->{$attr};

 my($class,%args) = @_;
 my $self = $class->SUPER::new(%args);

 if ($args{'-file'}) {$self->_readfile($args{'-file'})}
 if ($args{'-verbose'}) {$self->{'verbose'}=1}
 return $self;

 my $self=shift;
 return $self->{'maximum_primers_returned'};

 my ($self, @results) = @_;
 my %hash;
  if (@results) {
  # we only want a few things
  foreach my $result (@results) {$hash{$result}=$self->{'results'}->$result}
 }
 else {
  foreach my $result (keys %{$self->{'results'}}) {
   $hash{$result}=$self->{'results'}->{$result};
  }
 }


 return\% hash;

 my ($self, $toget) = @_;
 if ($toget > $self->{'maximum_primers_returned'}) {
  $self->warn("Didn't get any results for $toget");
  return 0;
 }
 else {return\% {$self->{'results_by_number'}->{$toget}}}

 my ($self, $file) = @_;
 $self->_initialize_io(-file=>$file);
 my $line;
 my $id='primer 3 parsed results'; # hopefully we'll get this, but we can set a temp id in case not.
 while (defined($line=$self->_readline()) ) {
  chomp $line;
  next unless ($line);
  my ($return, $value) = split /=/, $line;
  if (uc($return) eq "SEQUENCE") {
   $self->{seqobject}=Bio::Seq->new(-seq=>$value, $id=>$id);
   next;
  }
  if (uc($return) eq "PRIMER_SEQUENCE_ID") {
   if ($self->{seqobject}) {$self->{seqobject}->id($value)} else {$id=$value}
  }

  $self->{'results'}->{$return} = $value;
 }

 # convert the results to individual results
 $self->_separate();

 my $self=shift;
 my $primedseq = $self->next_primer;
 return $primedseq;

 my $self = shift;
 # here we are going to convert the primers to Bio::SeqFeature::Primer objects
 # and the primer/sequence to Bio::Seq::PrimedSeq objects
 # the problem at the moment is that PrimedSeq can only take one sequence/primer pair, and
 # yet for each sequence we can have lots of primer pairs. We need a way to overcome this.
 # at the moment we can do this as a stream, I guess.

 my $next=0;
 if ($self->{'next_to_return'}) {$next=$self->{'next_to_return'}}
 if ($next>$self->{'maximum_primers_returned'}) {return}
 my $results=$self->primer_results($next);
 unless (${$results}{'PRIMER_LEFT_SEQUENCE'}) {$self->throw("No left primer sequence")}
 unless (${$results}{'PRIMER_RIGHT_SEQUENCE'}) {$self->throw("No right primer sequence")}
 unless ($self->{'seqobject'}) {$self->throw("No target sequence")}

 my $left_seq  = Bio::SeqFeature::Primer->new(-primer_sequence_id=>"left_primer", -sequence=>${$results}{'PRIMER_LEFT_SEQUENCE'});
 my $right_seq = Bio::SeqFeature::Primer->new(-primer_sequence_id=>"right_primer", -sequence=>${$results}{'PRIMER_RIGHT_SEQUENCE'});
 my $primed_seq = Bio::Seq::PrimedSeq->new(-target_sequence=>$self->{'seqobject'}, -left_primer=>$left_seq, -right_primer=>$right_seq);
 my %product_hash; my %primer_left_hash; my %primer_right_hash;
 # now we are going to add the remaining primer3 results to the appropriate place (either primer or primed seq)
 foreach my $key (keys %$results) {
  next if ($key eq 'PRIMER_LEFT_SEQUENCE' || $key eq 'PRIMER_RIGHT_SEQUENCE');
  if ($key =~ /PRIMER_LEFT/i) {$primer_left_hash{$key}=$$results{$key}}
  elsif ($key =~ /PRIMER_RIGHT/i) {$primer_right_hash{$key}=$$results{$key}}
  else {$product_hash{$key}=$$results{$key}}
 }
 $left_seq->add_tag_value(%primer_left_hash);
 $right_seq->add_tag_value(%primer_right_hash);
 $primed_seq->add_tag_value(%product_hash);

 $self->{'next_to_return'}=$next+1;
 return $primed_seq;

 my ($self, $name, $value)=@_;
 next unless ($name);
 $self->{$name}=$value;

 my $self=shift;
 my %results; # the results that we find
 my $maxlocation=0; # the maximum number of primers returned
 foreach my $key (keys %{$self->{'results'}}) {
  next if (${$self->{'input_options'}}{$key}); # don't process it if it is an input key

  my $location; # the number of the primer pair
  # names will have values like
  # PRIMER_RIGHT_SEQUENCE, PRIMER_RIGHT_2_SEQUENCE, PRIMER_PRODUCT_SIZE, and PRIMER_PRODUCT_SIZE_3
  # hence we need to find and remove the number
  my $tempkey=$key;
  if ($tempkey =~ s/_(\d+)//) {
   $location=$1;
   if ($location > $maxlocation) {$maxlocation = $location}
   } else {$location = 0}

  # we will hash the results by number, and then by name
  ${$results{$location}}{$tempkey}=${$self->{'results'}}{$key};
 }
 $self->{'results_by_number'}=\%results;
 $self->{'maximum_primers_returned'}=$maxlocation;

  User feedback is an integral part of the evolution of this and other
  Bioperl modules. Send your comments and suggestions preferably to one
  of the Bioperl mailing lists.  Your participation is much appreciated.

    bioperl-l@bioperl.org          - General discussion
    http://www.bioperl.org/MailList.html             - About the mailing lists

  Report bugs to the Bioperl bug tracking system to help us keep track
  the bugs and their resolution.  Bug reports can be submitted via email
  or the web:

    bioperl-bugs@bio.perl.org
    http://bugzilla.bioperl.org/

  Rob Edwards

  redwards@utmem.edu

  Based heavily on work of 

  Chad Matsalla

  bioinformatics1@dieselwurks.com

  The rest of the documentation details each of the object methods. 
  Internal methods are usually preceded with a _