LICENSE

Copyright [1999-2015] Wellcome Trust Sanger Institute and the EMBL-European Bioinformatics Institute Copyright [2016-2024] EMBL-European Bioinformatics Institute

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

CONTACT

Please email comments or questions to the public Ensembl
developers list at <http://lists.ensembl.org/mailman/listinfo/dev>.

Questions may also be sent to the Ensembl help desk at
<http://www.ensembl.org/Help/Contact>.

NAME

Bio::EnsEMBL::Utils::Scalar

SYNOPSIS

	use Bio::EnsEMBL::Utils::Scalar qw(check_ref assert_ref wrap_array check_ref_can assert_ref_can assert_numeric assert_integer scope_guard);

	check_ref([], 'ARRAY'); # Will return true
	check_ref({}, 'ARRAY'); # Will return false
	check_ref($dba, 'Bio::EnsEMBL::DBSQL::DBAdaptor'); #Returns true if $dba is a DBAdaptor

  # Returns true if all array contents are of the given type
  check_array_contents([$dba], 'Bio::EnsEMBL::DBSQL::DBAdaptor'); 

	assert_ref([], 'ARRAY'); #Returns true
	assert_ref({}, 'ARRAY'); #throws an exception
	assert_ref($dba, 'Bio::EnsEMBL::Gene'); #throws an exception if $dba is not a Gene

  # Throws an exception if all array contents are not of the given type
  assert_array_contents([$dba], 'Bio::EnsEMBL::Gene'); #throws an exception if $dba is not a Gene

	wrap_array([]); #Returns the same reference
	wrap_array($a); #Returns [$a] if $a was not an array
	wrap_array(undef); #Returns [] since incoming was undefined
	wrap_array(); #Returns [] since incoming was empty (therefore undefined)

	check_ref_can([], 'dbID'); #returns false as ArrayRef is not blessed
	check_ref_can($gene, 'dbID'); #returns true as Gene should implement dbID()
	check_ref_can(undef); #Throws an exception as we gave no method to test

	assert_ref_can([], 'dbID'); #throws an exception since ArrayRef is not blessed
	assert_ref_can($gene, 'dbID'); #returns true if gene implements dbID()
	assert_ref_can(undef); #Throws an exception as we gave no method to test

	asssert_integer(1, 'dbID'); #Passes
	asssert_integer(1.1, 'dbID'); #Fails
	asssert_numeric(1E-11, 'dbID'); #Passes
	asssert_numeric({}, 'dbID'); #Fails
	
	#Scope guards
	my $v = 'wibble'; 
  {
    #Build a guard to reset $v to wibble
    my $guard = scope_guard(sub { $v = 'wibble'});
    $v = 'wobble';
    warn $v; # prints wobble
  }
  # $guard is out of scope; sub is triggered and $v is reset
  warn $v; # prints wibble

	#Tags are also available for exporting
	use Bio::EnsEMBL::Utils::Scalar qw(:assert); # brings in all assert methods
	use Bio::EnsEMBL::Utils::Scalar qw(:check); #brings in all check methods
	use Bio::EnsEMBL::Utils::Scalar qw(:array); #brings in wrap_array
	use Bio::EnsEMBL::Utils::Scalar qw(:all); #import all methods

DESCRIPTION

A collection of subroutines aimed to helping Scalar based operations

METHODS

See subroutines.

MAINTAINER

$Author$

VERSION

$Revision$

check_ref_pp()

Arg [1]     : The reference to check
Arg [2]     : The type we expect
Description : A subroutine which checks to see if the given object/ref is
              what you expect. If you give it a blessed reference then it
              will perform an isa() call on the object after the defined
              tests. If it is a plain reference then it will use ref().

              An undefined value will return a false.
Returntype  : Boolean indicating if the reference was the type we
              expect
Example     : my $ok = check_ref([], 'ARRAY');
Exceptions  : If the expected type was not set
Status      : Stable

assert_ref_pp()

Arg [1]     : The reference to check
Arg [2]     : The type we expect
Arg [3]     : The attribute name you are asserting; not required but allows
              for more useful error messages to be generated. Defaults to
              C<-Unknown->.
Description : A subroutine which checks to see if the given object/ref is
              what you expect. This behaves in an identical manner as
              C<check_ref()> does except this will raise exceptions when
              the values do not match rather than returning a boolean
              indicating the situation.

              Undefs cause exception circumstances.
              
              You can turn assertions off by using the global variable
              $Bio::EnsEMBL::Utils::Scalar::ASSERTIONS = 0
Returntype  : Boolean; true if we managed to get to the return
Example     : assert_ref([], 'ARRAY');
Exceptions  : If the expected type was not set and if the given reference
              was not assignable to the expected value
Status      : Stable

assert_array_contents

Arg [1]     : ArrayRef references to check
Arg [2]     : The type we expect
Arg [3]     : The attribute name you are asserting; not required but allows
              for more useful error messages to be generated. Defaults to
              C<-Unknown->.
Description : A subroutine which checks to see if the given objects/refs are
              what you expect. This behaves in an identical manner as
              C<assert_ref> does works on an array ref of references

              You can turn assertions off by using the global variable
              $Bio::EnsEMBL::Utils::Scalar::ASSERTIONS = 0
Returntype  : Boolean; true if we managed to get to the return
Example     : assert_array_contents([[],[],[]], 'ARRAY');
Exceptions  : Throws is references argument is not an ArrayRef, also
              if the expected type was not set and if the given reference
              was not assignable to the expected value.
Status      : Stable

check_array_contents

Arg [1]     : ArrayRef references to check
Arg [2]     : The type we expect
Arg [3]     : The attribute name you are asserting; not required but allows
              for more useful error messages to be generated. Defaults to
              C<-Unknown->.
Description : A subroutine which checks to see if the given objects/refs are
              what you expect. 
Returntype  : Boolean; true if all contents were as expected
Example     : check_array_contents([[],[],[]], 'ARRAY');
Exceptions  : Thrown if no type was given
Status      : Stable

assert_hash_contents

Arg [1]     : HashRef references to check
Arg [2]     : The type we expect
Arg [3]     : The attribute name you are asserting; not required but allows
              for more useful error messages to be generated. Defaults to
              C<-Unknown->.
Description : A subroutine which checks to see if the given objects/refs are
              what you expect. This behaves in an identical manner as
              C<assert_ref> does works on a HashRef of references. Hash keys 
              are always Strings so do not need asserting.

              You can turn assertions off by using the global variable
              $Bio::EnsEMBL::Utils::Scalar::ASSERTIONS = 0
Returntype  : Boolean; true if we managed to get to the return
Example     : assert_hash_contents({a => [], b => []}, 'ARRAY');
Exceptions  : Throws is references argument is not an ArrayRef, also
              if the expected type was not set and if the given reference
              was not assignable to the expected value.
Status      : Stable

check_hash_contents

Arg [1]     : HashRef references to check
Arg [2]     : The type we expect
Arg [3]     : The attribute name you are asserting; not required but allows
              for more useful error messages to be generated. Defaults to
              C<-Unknown->.
Description : A subroutine which checks to see if the given objects/refs are
              what you expect. 
Returntype  : Boolean; true if all contents were as expected
Example     : check_hash_contents({a => [], b => []}, 'ARRAY');
Exceptions  : Thrown if no type was given
Status      : Stable

wrap_array()

Arg         : The reference we want to wrap in an array
Description : Takes in a reference and returns either the reference if it
              was already an array, the reference wrapped in an array or
              an empty array (if the given value was undefined).
Returntype  : Array Reference
Example     : my $a = wrap_array($input);
Exceptions  : None
Status      : Stable

check_ref_can

Arg [1]     : The reference to check
Arg [2]     : The method we expect to run
Description : A subroutine which checks to see if the given object/ref is
              implements the given method. This is very similar to the
              functionality given by C<UNIVERSAL::can()> but works
              by executing C<can()> on the object meaning we consult the
              object's potentially overriden version rather than Perl's
              default mechanism.
Returntype  : CodeRef
Example     : check_ref_can($gene, 'dbID');
Exceptions  : If the expected type was not set.
Status      : Stable

assert_ref_can

Arg [1]     : The reference to check
Arg [2]     : The method we expect to run
Arg [3]     : The attribute name you are asserting; not required but allows
              for more useful error messages to be generated. Defaults to
              C<-Unknown->.
Description : A subroutine which checks to see if the given object/ref is
              implements the given method. Will throw exceptions.
              
              You can turn assertions off by using the global variable
              $Bio::EnsEMBL::Utils::Scalar::ASSERTIONS = 0
Returntype  : Boolean; true if we managed to get to the return
Example     : assert_ref_can($gene, 'dbID');
Exceptions  : If the reference is not defined, if the object does not
              implement the given method and if no method was given to check
Status      : Stable

assert_numeric_pp

Arg [1]     : The Scalar to check
Arg [2]     : The attribute name you are asserting; not required but allows
              for more useful error messages to be generated. Defaults to
              C<-Unknown->.
Description : A subroutine which checks to see if the given scalar is
              number or not. If not then we raise exceptions detailing why
              
              You can turn assertions off by using the global variable
              $Bio::EnsEMBL::Utils::Scalar::ASSERTIONS = 0
Returntype  : Boolean; true if we had a numeric otherwise we signal failure
              via exceptions
Example     : assert_numeric(1, 'dbID');
Exceptions  : If the Scalar is not defined, if the Scalar was blessed and
              if the value was not a number
Status      : Stable

assert_integer_pp

Arg [1]     : The Scalar to check
Arg [2]     : The attribute name you are asserting; not required but allows
              for more useful error messages to be generated. Defaults to
              C<-Unknown->.
Description : A subroutine which checks to see if the given scalar is
              a whole integer; we delegate to L<assert_numeric> for number
              checking.
              
              You can turn assertions off by using the global variable
              $Bio::EnsEMBL::Utils::Scalar::ASSERTIONS = 0
Returntype  : Boolean; true if we had a numeric otherwise we signal failure
              via exceptions
Example     : assert_integer(1, 'dbID');
Exceptions  : See L<assert_numeric> and we raise exceptions if the value
              was not a whole integer
Status      : Stable

assert_boolean

Arg [1]     : The Scalar to check
Arg [2]     : The attribute name you are asserting; not required but allows
              for more useful error messages to be generated. Defaults to
              C<-Unknown->.
Description : A subroutine which checks to see if the given scalar is
              a boolean i.e. value is set to C<1> or C<0>
              
              You can turn assertions off by using the global variable
              $Bio::EnsEMBL::Utils::Scalar::ASSERTIONS = 0
Returntype  : Boolean; true if we were given a boolean otherwise we signal
              failure via exceptions
Example     : assert_boolean(1, 'is_circular');
Exceptions  : See L<assert_integer> and we raise exceptions if the value
              was not equal to the 2 valid states
Status      : Stable

assert_strand

Arg [1]     : The Scalar to check
Arg [2]     : The attribute name you are asserting; not required but allows
              for more useful error messages to be generated. Defaults to
              C<-Unknown->.
Description : A subroutine which checks to see if the given scalar is
              a whole integer and if the value is set to C<1>, C<0> or C<-1>
              
              You can turn assertions off by using the global variable
              $Bio::EnsEMBL::Utils::Scalar::ASSERTIONS = 0
Returntype  : Boolean; true if we had a strand integer otherwise we signal
              failure via exceptions
Example     : assert_strand(1, 'strand');
Exceptions  : See L<assert_integer> and we raise exceptions if the value
              was not equal to the 3 valid states
Status      : Stable

assert_file_handle

Arg [1]     : The Scalar to check
Arg [2]     : The attribute name you are asserting; not required but allows
              for more useful error messages to be generated. Defaults to
              C<-Unknown->.
Description : A subroutine which checks to see if the given scalar is
              actually a file handle. This will handle those which are Glob
              references and those which inherit from C<IO::Handle>. It will
              also cope with a blessed Glob reference.
              
              You can turn assertions off by using the global variable
              $Bio::EnsEMBL::Utils::Scalar::ASSERTIONS = 0
Returntype  : Boolean;
Example     : assert_file_handle($fh, '-FILE_HANDLE');
Exceptions  : Raised if not defined, not a reference and was not a
              GLOB or did not inherit from IO::Handle   
Status      : Stable

split_array

Arg [1]     : Integer Maximum size of an array produced
Arg [2]     : ArrayRef The array to split
Description : Takes an array of values and splits the array into multiple 
              arrays where the maximum size of each array is as specified
Example     : my $split_arrays = split_array($large_array, 10);
Returntype  : ArrayRef of ArrayRefs where each element is a split list

scope_guard

Arg [1]     : CodeRef The block of code to exit once it escapes out of scope
Description : Simple subroutine which blesses your given code reference into
              a L<Bio::EnsEMBL::Utils::Scalar::ScopeGuard> object. This has
              a DESTROY implemented which will cause the code reference
              to execute once the object goes out of scope and its reference
              count hits 0.
Returntype  : Bio::EnsEMBL::Utils::Scalar::ScopeGuard
Example     : my $v = 'wibble'; 
              {
                #Build a guard to reset $v to wibble
                my $guard = scope_guard(sub { $v = 'wibble'});
                $v = 'wobble';
                warn $v;
              }
              # $guard is out of scope; sub is triggered and $v is reset
              warn $v;
Exceptions  : Raised if argument was not a CodeRef   
Status      : Stable

cpanm Bio::EnsEMBL

perl -MCPAN -e shell
install Bio::EnsEMBL