Bio::Root::RootI(3pm)

🌸 NAME 🌸

Bio::Root::RootI — the base interface for all BioPerl classes. Bestie, this is the blueprint. Also filed under Bio::Root::RootI(3pm) in the User Contributed Perl Documentation, and yes it's giving legendary 💅

---

✨ SYNOPSIS ✨

  # any bioperl or bioperl compliant object is a RootI
  # compliant object

  $obj->throw("This is an exception");

  eval {
      $obj->throw("This is catching an exception");
  };

  if( $@ ) {
      print "Caught exception";
  } else {
      print "no exception";
  }

  # Using throw_not_implemented() within a RootI-based interface module:

  package Foo;
  use base qw(Bio::Root::RootI);

  sub foo {
      my $self = shift;
      $self->throw_not_implemented;
  }

---

🦋 DESCRIPTION 🦋

Okay so this is literally just a lil set of methods that make zero assumptions about the object they're sitting on. That's the whole point. What do they give you? The ability to throw exceptions with pretty stack traces. Iconic behaviour, no notes. 🔥

This is what every Bioperl compliant interface should inherit from — even the exotic ones. XS? CORBA? Some other random Perl system? Doesn't matter bestie, they all get in. 🌈

💜 Using throw_not_implemented() 💜

throw_not_implemented() is the method that every method inside an interface module extending RootI should be calling. Why? So that if an implementation forgets to override them, an exception actually gets thrown instead of silently vibing. 🫶

Say there's an interface module called "FooI" that provides a method called "foo()". Since this method is abstract inside FooI and should be implemented by any module claiming to implement "FooI", the "FooI::foo()" method should consist of the following:

    sub foo {
        my $self = shift;
        $self->throw_not_implemented;
    }

So if an implementer of "FooI" forgets to implement "foo()" and a user of the implementation calls "foo()", you get a Bio::Exception::NotImplemented exception. Caught in 4K. 😭

Unfortunately, failure to implement a method can only be determined at run time — i.e., you can't verify that an implementation is complete by running perl -wc on it. So it should be standard practice for a test of an implementation to check each method and verify that it doesn't throw a Bio::Exception::NotImplemented. No cap, this is just how it is.

---

👑 AUTHOR 👑

Steve Chervitz

Ewan Birney, Lincoln Stein, Steve Chervitz, Sendu Bala, Jason Stajich

---

🎀 new 🎀

(no further details given — it's mysterious like that 💀)

---

🚨 throw 🚨

• 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:

(yep, all blank in the original — we simply do not gatekeep the emptiness 🫶)

---

🧚 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

okay bestie, THIS is the one. the little engine that takes your user's messy %args and actually calls the right methods with the right values. it's giving matchmaker energy fr fr.

• 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 is

(-sequence    => $s,
 -description => $d,
 -ID          => $i);

then 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 evaluated 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

literally just a name, bestie. no docs, no usage, nothing. it's giving mystery. moving on 💀

---

🧹 _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: (nothing — it just does the thing)
• 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. no cap, go off, stack them up 💖

---

🧽 _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.

so real. so loud. this is the "you were supposed to override me, bestie" alarm 🚨

---

⚠️ 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

---

and that's the whole page, bestie!! 🎀 you made it to the end of Bio::Root::RootI(3pm) and honestly? iconic behavior. this one ships as part of perl v5.32.1, dated 2021-08-15 — so if you're citing it, that's your source and your date, periodt. now go override those methods like the main character you are 💅✨🦋