Archive Ensembl HomeArchive Ensembl Home
Argument.pm
Go to the documentation of this file.
00001 =head1 LICENSE
00002 
00003   Copyright (c) 1999-2012 The European Bioinformatics Institute and
00004   Genome Research Limited.  All rights reserved.
00005 
00006   This software is distributed under a modified Apache license.
00007   For license details, please see
00008 
00009     http://www.ensembl.org/info/about/code_licence.html
00010 
00011 =head1 CONTACT
00012 
00013   Please email comments or questions to the public Ensembl
00014   developers list at <dev@ensembl.org>.
00015 
00016   Questions may also be sent to the Ensembl help desk at
00017   <helpdesk@ensembl.org>.
00018 
00019 =cut
00020 
00021 =head1 NAME
00022 
00023 Bio::EnsEMBL::Utils::Argument - Utility functions for argument handling
00024 
00025 =head1 SYNOPSIS
00026 
00027   use Bio::EnsEMBL::Utils::Argument qw(rearrange)
00028 
00029   package Feature;
00030 
00031   sub new {
00032     my $class = shift;
00033     my ( $start, $end, $strand ) =
00034       rearrange( [ 'START', 'END', 'STRAND' ], @_ );
00035 
00036     return
00037       bless( { 'start' => $start, 'end' => $end, 'strand' => $strand },
00038       $class );
00039   }
00040 
00041 =head1 DESCRIPTION
00042 
00043 This is derived from the Bio::Root module in BioPerl.  The _rearrange
00044 object method taken from BioPerl has been renamed rearrange and is now
00045 a static class method.  This method was originally written by Lincoln
00046 Stein, and has since been refactored several times by various people (as
00047 described below).
00048 
00049 It is recommended that this package be used instead of inheriting
00050 unnecessarily from the Bio::EnsEMBL::Root or Bio::Root object.
00051 
00052 =head1 METHODS
00053 
00054 =cut
00055 
00056 package Bio::EnsEMBL::Utils::Argument;
00057 
00058 use strict;
00059 use warnings;
00060 
00061 use Exporter;
00062 
00063 use vars qw(@ISA @EXPORT);
00064 
00065 @ISA = qw(Exporter);
00066 @EXPORT = qw(rearrange);
00067 
00068 
00069 
00070 =head2 rearrange
00071 
00072  Usage     : rearrange( array_ref, list_of_arguments)
00073  Purpose   : Rearranges named parameters to requested order.
00074  Example   : use Bio::EnsEMBL::Utils::Argument qw(rearrange);
00075            : rearrange([qw(SEQUENCE ID DESC)],@param);
00076            : Where @param = (-sequence => $s, 
00077              :                 -id       => $i, 
00078              :                 -desc     => $d);
00079  Returns   : @params - an array of parameters in the requested order.
00080            : The above example would return ($s, $i, $d)
00081  Argument  : $order : a reference to an array which describes the desired
00082            :          order of the named parameters.
00083            : @param : an array of parameters, either as a list (in
00084            :          which case the function simply returns the list),
00085            :          or as an associative array with hyphenated tags
00086            :          (in which case the function sorts the values 
00087            :          according to @{$order} and returns that new array.)
00088        :          The tags can be upper, lower, or mixed case
00089            :          but they must start with a hyphen (at least the
00090            :          first one should be hyphenated.)
00091  Source    : This function was taken from CGI.pm, written by Dr. Lincoln
00092            : Stein, and adapted for use in Bio::Seq by Richard Resnick and
00093            : then adapted for use in Bio::Root::Object.pm by Steve A. Chervitz.
00094            : This has since been adapted as an exported static method in this 
00095              class Bio::EnsEMBL::Utils::Argument 
00096  Comments  : (SAC)
00097            : This method may not be appropriate for method calls that are
00098            : within in an inner loop if efficiency is a concern.
00099            :
00100            : Parameters can be specified using any of these formats:
00101            :  @param = (-name=>'me', -color=>'blue');
00102            :  @param = (-NAME=>'me', -COLOR=>'blue');
00103            :  @param = (-Name=>'me', -Color=>'blue');
00104            : A leading hyphenated argument is used by this function to 
00105            : indicate that named parameters are being used.
00106            : Therefore, a ('me', 'blue') list will be returned as-is.
00107            :
00108            : Note that Perl will confuse unquoted, hyphenated tags as 
00109            : function calls if there is a function of the same name 
00110            : in the current namespace:
00111            :    -name => 'foo' is interpreted as -&name => 'foo'
00112            :
00113            : For ultimate safety, put single quotes around the tag:
00114              :    ('-name'=>'me', '-color' =>'blue');
00115            : This can be a bit cumbersome and I find not as readable
00116            : as using all uppercase, which is also fairly safe:
00117            :    (-NAME=>'me', -COLOR =>'blue');
00118              :
00119            : Personal note (SAC): I have found all uppercase tags to
00120            : be more managable: it involves less single-quoting,
00121            : the code is more readable, and there are no method naming 
00122            : conlicts.
00123            : Regardless of the style, it greatly helps to line
00124              : the parameters up vertically for long/complex lists.
00125 
00126 =cut
00127 
00128 
00129 sub rearrange {
00130   my $order = shift;
00131 
00132   if ( $order eq "Bio::EnsEMBL::Utils::Argument" ) {
00133     # skip object if one provided
00134     $order = shift;
00135   }
00136 
00137   # If we've got parameters, we need to check to see whether
00138   # they are named or simply listed. If they are listed, we
00139   # can just return them.
00140   unless ( @_ && $_[0] && substr( $_[0], 0, 1 ) eq '-' ) {
00141     return @_;
00142   }
00143   
00144   # Push undef onto the end if % 2 != 0 to stop warnings
00145   push @_,undef unless $#_ %2;
00146   my %param;
00147   while( @_ ) {
00148     #deletes all dashes & uppercases at the same time
00149     (my $key = shift) =~ tr/a-z\055/A-Z/d;
00150     $param{$key} = shift;
00151   }
00152   
00153   # What we intend to do is loop through the @{$order} variable,
00154   # and for each value, we use that as a key into our associative
00155   # array, pushing the value at that key onto our return array.
00156   return map { $param{uc($_)} } @$order;
00157 }
00158 
00159 1;
00160 
00161