Ewan Birney, Lincoln Stein, Steve Chervitz, Sendu Bala, Jason Stajich
newthrow
Title : throw
Usage : $obj->throw("throwing exception message")
Function: Throws an exception, which, if not caught with an eval brace
will provide a nice stack trace to STDERR with the message
Returns : nothing
Args : A string giving a descriptive error message
warn
Title : warn
Usage : $object->warn("Warning message");
Function: Places a warning. What happens now is down to the
verbosity of the object (value of $obj->verbose)
verbosity 0 or not set => small warning
verbosity -1 => no warning
verbosity 1 => warning with stack trace
verbosity 2 => converts warnings into throw
Returns : n/a
Args : string (the warning message)
deprecated
Title : deprecated
Usage : $obj->deprecated("Method X is deprecated");
$obj->deprecated("Method X is deprecated", 1.007);
$obj->deprecated(-message => "Method X is deprecated");
$obj->deprecated(-message => "Method X is deprecated",
-version => 1.007);
Function: Prints a message about deprecation unless verbose is < 0
(which means be quiet)
Returns : none
Args : Message string to print to STDERR
Version of BioPerl where use of the method results in an exception
Notes : This is deprecated. Use Carp::carp to warn about a
deprecated method. Just remove the method when it comes to
error. If you really want to throw an error insyead of
removing, use Carp::croak.
The irony of deprecating deprecated() is not lost on us.
We hope you also find it more funny that frustrating.
stack_trace_dump
Title : stack_trace_dump
Usage :
Function:
Example :
Returns :
Args :
stack_trace
Title : stack_trace
Usage : @stack_array_ref= $self->stack_trace
Function: gives an array to a reference of arrays with stack trace info
each coming from the caller(stack_number) call
Returns : array containing a reference of arrays
Args : none
_rearrange
Usage : $object->_rearrange( array_ref, list_of_arguments)
Purpose : Rearranges named parameters to requested order.
Example : $self->_rearrange([qw(SEQUENCE ID DESC)],@param);
: Where @param = (-sequence => $s,
: -desc => $d,
: -id => $i);
Returns : @params - an array of parameters in the requested order.
: The above example would return ($s, $i, $d).
: Unspecified parameters will return undef. For example, if
: @param = (-sequence => $s);
: the above _rearrange call would return ($s, undef, undef)
Argument : $order : a reference to an array which describes the desired
: order of the named parameters.
: @param : an array of parameters, either as a list (in
: which case the function simply returns the list),
: or as an associative array with hyphenated tags
: (in which case the function sorts the values
: according to @{$order} and returns that new array.)
: The tags can be upper, lower, or mixed case
: but they must start with a hyphen (at least the
: first one should be hyphenated.)
Source : This function was taken from CGI.pm, written by Dr. Lincoln
: Stein, and adapted for use in Bio::Seq by Richard Resnick and
: then adapted for use in Bio::Root::Object.pm by Steve Chervitz,
: then migrated into Bio::Root::RootI.pm by Ewan Birney.
Comments :
: Uppercase tags are the norm,
: (SAC)
: This method may not be appropriate for method calls that are
: within in an inner loop if efficiency is a concern.
:
: Parameters can be specified using any of these formats:
: @param = (-name=>'me', -color=>'blue');
: @param = (-NAME=>'me', -COLOR=>'blue');
: @param = (-Name=>'me', -Color=>'blue');
: @param = ('me', 'blue');
: A leading hyphenated argument is used by this function to
: indicate that named parameters are being used.
: Therefore, the ('me', 'blue') list will be returned as-is.
:
: Note that Perl will confuse unquoted, hyphenated tags as
: function calls if there is a function of the same name
: in the current namespace:
: -name => 'foo' is interpreted as -&name => 'foo'
:
: For ultimate safety, put single quotes around the tag:
: ('-name'=>'me', '-color' =>'blue');
: This can be a bit cumbersome and I find not as readable
: as using all uppercase, which is also fairly safe:
: (-NAME=>'me', -COLOR =>'blue');
:
: Personal note (SAC): I have found all uppercase tags to
: be more manageable: it involves less single-quoting,
: the key names stand out better, and there are no method naming
: conflicts.
: The drawbacks are that it's not as easy to type as lowercase,
: and lots of uppercase can be hard to read.
:
: Regardless of the style, it greatly helps to line
: the parameters up vertically for long/complex lists.
:
: Note that if @param is a single string that happens to start with
: a dash, it will be treated as a hash key and probably fail to
: match anything in the array_ref, so not be returned as normally
: happens when @param is a simple list and not an associative array.
_set_from_args
Usage : $object->_set_from_args(\%args, -methods => \@methods)
Purpose : Takes a hash of user-supplied args whose keys match method names,
: and calls the method supplying it the corresponding value.
Example : $self->_set_from_args(\%args, -methods => [qw(sequence id desc)]);
: Where %args = (-sequence => $s,
: -description => $d,
: -ID => $i);
:
: the above _set_from_args calls the following methods:
: $self->sequence($s);
: $self->id($i);
: ( $self->description($i) is not called because 'description' wasn't
: one of the given methods )
Argument : \%args | \@args : a hash ref or associative array ref of arguments
: where keys are any-case strings corresponding to
: method names but optionally prefixed with
: hyphens, and values are the values the method
: should be supplied. If keys contain internal
: hyphens (eg. to separate multi-word args) they
: are converted to underscores, since method names
: cannot contain dashes.
: -methods => [] : (optional) only call methods with names in this
: array ref. Can instead supply a hash ref where
: keys are method names (of real existing methods
: unless -create is in effect) and values are array
: refs of synonyms to allow access to the method
: using synonyms. If there is only one synonym it
: can be supplied as a string instead of a single-
: element array ref
: -force => bool : (optional, default 0) call methods that don't
: seem to exist, ie. let AUTOLOAD handle them
: -create => bool : (optional, default 0) when a method doesn't
: exist, create it as a simple getter/setter
: (combined with -methods it would create all the
: supplied methods that didn't exist, even if not
: mentioned in the supplied %args)
: -code => '' | {}: (optional) when creating methods use the supplied
: code (a string which will be evaulated as a sub).
: The default code is a simple get/setter.
: Alternatively you can supply a hash ref where
: the keys are method names and the values are
: code strings. The variable '$method' will be
: available at evaluation time, so can be used in
: your code strings. Beware that the strict pragma
: will be in effect.
: -case_sensitive => bool : require case sensitivity on the part of
: user (ie. a() and A() are two different
: methods and the user must be careful
: which they use).
Comments :
: The \%args argument will usually be the args received during new()
: from the user. The user is allowed to get the case wrong, include
: 0 or more than one hyphens as a prefix, and to include hyphens as
: multi-word arg separators: '--an-arg' => 1, -an_arg => 1 and
: An_Arg => 1 are all equivalent, calling an_arg(1). However, in
: documentation users should only be told to use the standard form
: -an_arg to avoid confusion. A possible exception to this is a
: wrapper module where '--an-arg' is what the user is used to
: supplying to the program being wrapped.
:
: Another issue with wrapper modules is that there may be an
: argument that has meaning both to Bioperl and to the program, eg.
: -verbose. The recommended way of dealing with this is to leave
: -verbose to set the Bioperl verbosity whilst requesting users use
: an invented -program_verbose (or similar) to set the program
: verbosity. This can be resolved back with
: Bio::Tools::Run::WrapperBase's _setparams() method and code along
: the lines of:
: my %methods = map { $_ => $_ } @LIST_OF_ALL_ALLOWED_PROGRAM_ARGS
: delete $methods{'verbose'};
: $methods{'program_verbose'} = 'verbose';
: my $param_string = $self->_setparams(-methods => \%methods);
: system("$exe $param_string");
_rearrange_old_register_for_cleanup
Title : _register_for_cleanup
Usage : -- internal --
Function: Register a method to be called at DESTROY time. This is useful
and sometimes essential in the case of multiple inheritance for
classes coming second in the sequence of inheritance.
Returns :
Args : a code reference
The code reference will be invoked with the object as the first argument, as per a method. You may
register an unlimited number of cleanup methods.
_unregister_for_cleanup
Title : _unregister_for_cleanup
Usage : -- internal --
Function: Remove a method that has previously been registered to be called
at DESTROY time. If called with a method to be called at DESTROY time.
Has no effect if the code reference has not previously been registered.
Returns : nothing
Args : a code reference
_cleanup_methods
Title : _cleanup_methods
Usage : -- internal --
Function: Return current list of registered cleanup methods.
Returns : list of coderefs
Args : none
throw_not_implemented
Purpose : Throws a Bio::Root::NotImplemented exception.
Intended for use in the method definitions of
abstract interface modules where methods are defined
but are intended to be overridden by subclasses.
Usage : $object->throw_not_implemented();
Example : sub method_foo {
$self = shift;
$self->throw_not_implemented();
}
Returns : n/a
Args : n/a
Throws : A Bio::Root::NotImplemented exception.
The message of the exception contains
- the name of the method
- the name of the interface
- the name of the implementing class
If this object has a throw() method, $self->throw will be used.
If the object doesn't have a throw() method,
Carp::confess() will be used.
warn_not_implemented
Purpose : Generates a warning that a method has not been implemented.
Intended for use in the method definitions of
abstract interface modules where methods are defined
but are intended to be overridden by subclasses.
Generally, throw_not_implemented() should be used,
but warn_not_implemented() may be used if the method isn't
considered essential and convenient no-op behavior can be
provided within the interface.
Usage : $object->warn_not_implemented( method-name-string );
Example : $self->warn_not_implemented( "get_foobar" );
Returns : Calls $self->warn on this object, if available.
If the object doesn't have a warn() method,
Carp::carp() will be used.
Args : n/a
_not_implemented_msg
Unify 'not implemented' message. -Juguang
perl v5.32.1 2021-08-15 Bio::Root::RootI(3pm)
Install Now
