Public Member Functions
public Boolean	check_ref_pp ()

public Boolean	assert_ref_pp ()

public Boolean	assert_array_contents ()

public Boolean	check_array_contents ()

public Boolean	assert_hash_contents ()

public Boolean	check_hash_contents ()

public Array	wrap_array ()

public CodeRef	check_ref_can ()

public Boolean	assert_ref_can ()

public Boolean	assert_numeric_pp ()

public Boolean	assert_integer_pp ()

public Boolean	assert_boolean ()

public Boolean	assert_strand ()

public Boolean	assert_file_handle ()

public ArrayRef	split_array ()

public Bio::EnsEMBL::Utils::Scalar::ScopeGuard	scope_guard ()

Detailed Description

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

Definition at line 66 of file Scalar.pm.

Member Function Documentation

◆ assert_array_contents()

public Boolean Bio::EnsEMBL::Utils::Scalar::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
               -Unknown-.
 Description : A subroutine which checks to see if the given objects/refs are
               what you expect. This behaves in an identical manner as
               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

Code:

click to view

◆ assert_boolean()

public Boolean Bio::EnsEMBL::Utils::Scalar::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
                -Unknown-.
  Description : A subroutine which checks to see if the given scalar is
                a boolean i.e. value is set to 1 or 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 assert_integer and we raise exceptions if the value
                was not equal to the 2 valid states
  Status      : Stable

Code:

click to view

◆ assert_file_handle()

public Boolean Bio::EnsEMBL::Utils::Scalar::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
                -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 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

Code:

click to view

◆ assert_hash_contents()

public Boolean Bio::EnsEMBL::Utils::Scalar::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
               -Unknown-.
 Description : A subroutine which checks to see if the given objects/refs are
               what you expect. This behaves in an identical manner as
               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

Code:

click to view

◆ assert_integer_pp()

public Boolean Bio::EnsEMBL::Utils::Scalar::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
                -Unknown-.
  Description : A subroutine which checks to see if the given scalar is
                a whole integer; we delegate to 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 assert_numeric and we raise exceptions if the value
                was not a whole integer
  Status      : Stable

Code:

click to view

◆ assert_numeric_pp()

public Boolean Bio::EnsEMBL::Utils::Scalar::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
                -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

Code:

click to view

◆ assert_ref_can()

public Boolean Bio::EnsEMBL::Utils::Scalar::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
                -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

Code:

click to view

◆ assert_ref_pp()

public Boolean Bio::EnsEMBL::Utils::Scalar::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
                -Unknown-.
  Description : A subroutine which checks to see if the given object/ref is
                what you expect. This behaves in an identical manner as
                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

Code:

click to view

◆ assert_strand()

public Boolean Bio::EnsEMBL::Utils::Scalar::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
                -Unknown-.
  Description : A subroutine which checks to see if the given scalar is
                a whole integer and if the value is set to 1, 0 or -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 assert_integer and we raise exceptions if the value
                was not equal to the 3 valid states
  Status      : Stable

Code:

click to view

◆ check_array_contents()

public Boolean Bio::EnsEMBL::Utils::Scalar::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
               -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

Code:

click to view

◆ check_hash_contents()

public Boolean Bio::EnsEMBL::Utils::Scalar::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
               -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

Code:

click to view

◆ check_ref_can()

public CodeRef Bio::EnsEMBL::Utils::Scalar::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 UNIVERSAL::can() but works
                by executing 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

Code:

click to view

◆ check_ref_pp()

public Boolean Bio::EnsEMBL::Utils::Scalar::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

Code:

click to view

◆ scope_guard()

public Bio::EnsEMBL::Utils::Scalar::ScopeGuard Bio::EnsEMBL::Utils::Scalar::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 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;
                }
@section autotoc_md35 $guard is out of scope; sub is triggered and $v is reset
                warn $v;

  Exceptions  : Raised if argument was not a CodeRef   
  Status      : Stable

Code:

click to view

◆ split_array()

public ArrayRef Bio::EnsEMBL::Utils::Scalar::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

Code:

click to view

◆ wrap_array()

public Array Bio::EnsEMBL::Utils::Scalar::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

Code:

click to view

The documentation for this class was generated from the following file:

ensembl/modules/Bio/EnsEMBL/Utils/Scalar.pm

Public Member Functions

Detailed Description

Synopsis

Description

Member Function Documentation

◆ assert_array_contents()

◆ assert_boolean()

◆ assert_file_handle()

◆ assert_hash_contents()

◆ assert_integer_pp()

◆ assert_numeric_pp()

◆ assert_ref_can()

◆ assert_ref_pp()

◆ assert_strand()

◆ check_array_contents()

◆ check_hash_contents()

◆ check_ref_can()

◆ check_ref_pp()

◆ scope_guard()

◆ split_array()

◆ wrap_array()