Archive Ensembl HomeArchive Ensembl Home
Serializer.pm
Go to the documentation of this file.
00001 =pod
00002 
00003 =head1 LICENSE
00004 
00005   Copyright (c) 1999-2012 The European Bioinformatics Institute and
00006   Genome Research Limited.  All rights reserved.
00007 
00008   This software is distributed under a modified Apache license.
00009   For license details, please see
00010 
00011   http://www.ensembl.org/info/about/code_licence.html
00012 
00013 =head1 NAME
00014 
00015 Serializer - An abstract serializer for turning EnsEMBL data into other formats
00016 
00017 =head1 AUTHOR
00018 
00019 Kieron Taylor, 2011 - ktaylor@ebi.ac.uk
00020 
00021 =head1 SYNOPSIS
00022 
00023 my $serializer = new Serializer( $filehandle );
00024 $serializer->print_feature_list( \@list_of_features );
00025 
00026 =head1 DESCRIPTION
00027 
00028 Subclass this class to create a format-specific serializer.
00029 Be sure to implement print_feature at the bare minimum
00030 
00031 =cut
00032 
00033 package Bio::EnsEMBL::Utils::IO::Serializer;
00034 use strict;
00035 use warnings;
00036 use Bio::EnsEMBL::Utils::Exception;
00037 use Bio::EnsEMBL::Utils::SeqDumper;
00038 
00039 
00040 =head2 new
00041 
00042     Constructor
00043     Arg [1]    : Optional File handle
00044     Returntype : Bio::EnsEMBL::Utils::IO::Serializer
00045 
00046 =cut
00047 
00048 sub new {
00049     my $class = shift;
00050     my $self = {
00051         'filehandle' => shift,
00052         'achieved_something' => 0,
00053     };
00054     bless $self, $class;
00055     if (!defined ($self->{'filehandle'})) {
00056         # no file handle, let the handle point to a copy of STDOUT instead
00057         open $self->{'filehandle'}, ">&STDOUT";
00058         $self->{'stdout'} = 1;
00059     }
00060     return $self;
00061 }
00062 
00063 =head2 DESTROY
00064 
00065     Destructor
00066     Description: Restores default state of the STDOUT filehandle as it is a copy
00067                  and may not flush correctly.
00068 =cut
00069 
00070 sub DESTROY {
00071     my $self = shift;
00072     if ($self->{'stdout'}) {
00073         close $self->{'filehandle'};
00074     }
00075 }
00076 
00077 =head2 print_metadata 
00078     
00079     Arg [1]    : String
00080     Description: Pipes a custom string into the filehandle that the serializer is using
00081 
00082 =cut
00083 
00084 sub print_metadata {
00085     my $self = shift;
00086     my $text = shift;
00087     my $fh = $self->{'filehandle'};
00088     print $fh "\n".$text."\n";
00089 }
00090 
00091 =head2 print_main_header
00092 
00093     Arg [1]    : Data for header, depends on serializer
00094     Description: Printing the header text or metadata required for this file format,
00095                  Re-implement in the serializer.
00096     Returntype : None
00097 =cut
00098 
00099 sub print_main_header {
00100     my $self = shift;
00101     warning("No writer for headers in this format. Nothing done" );
00102 }
00103 
00104 =head2 print_sequence 
00105     Arg [1]    : Bio::EnsEMBL::Slice
00106     Description: By default, prints a block of FASTA format sequence from the given slice
00107     DEPRECATED - This feature is becoming FASTASerializer
00108 =cut
00109 #TODO : Remove in release 66
00110 sub print_sequence {
00111     my $self = shift;
00112     my $slice = shift;
00113     my $fh = $self->{'filehandle'};
00114     Bio::EnsEMBL::Utils::SeqDumper->dump_fasta( $slice, $fh);
00115     $self->{'achieved_something'} = 1;
00116 }
00117 
00118 =head2 printed_something
00119     Description: Check if serializer has printed any useful data. Not accurate with FASTA
00120                  due to non-reporting dumper.
00121     Returntype : Boolean
00122 =cut
00123 
00124 sub printed_something {
00125     my $self = shift;
00126     if ($self->{'achieved_something'}) { return 1;}
00127     else {return 0;}
00128 }
00129 
00130 =head2 formatted_write
00131 
00132    Arg [1]    : Line format, see Perldoc of formline()
00133    Arg [2]    : Array of arguments to suit the line format in Arg [1]
00134    Description: Writes data to the filehandle and rigidly formats it.
00135                 Refer to Perldoc on formline() to specify valid formats.
00136                 Useful for fixed-width file formats.
00137                 Suicides in the event of file system issues.
00138    Example    : my $FORMAT = '^<<<<<<<<<<<<<<<<<<<|<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<\n';
00139                 $serializer->formatted_write($FORMAT,@text_fields);
00140    Returntype : None
00141 =cut
00142 
00143 sub formatted_write {
00144   my ($self, $FORMAT, @values) = @_;
00145   my $fh = $self->{'filehandle'};
00146   
00147   #while the last value still contains something
00148   while(defined($values[-1]) and $values[-1] ne '') {
00149     formline($FORMAT, @values);
00150     print $fh $^A or die "Failed write to filehandle";
00151     $^A = '';
00152   }
00153 }
00154 
00155 1;