NAME
   Data::Miscellany - Collection of miscellaneous subroutines

VERSION
   version 1.100850

SYNOPSIS
     use Data::Miscellany qw/set_push flex_grep/;

     my @foo = (1, 2, 3, 4);
     set_push @foo, 3, 1, 5, 1, 6;
     # @foo is now (1, 2, 3, 4, 5, 6);

     flex_grep('foo', [ qw/foo bar baz/ ]);                   # true
     flex_grep('foo', [ qw/bar baz flurble/ ]);               # false
     flex_grep('foo', 1..4, 'flurble', [ qw/foo bar baz/ ]);  # true
     flex_grep('foo', 1..4, [ [ 'foo' ] ], [ qw/bar baz/ ]);  # false

DESCRIPTION
   This is a collection of miscellaneous subroutines useful in wide but
   varying scenarios; a catch-all module for things that don't obviously
   belong anywhere else. Obviously what's useful differs from person to
   person, but this particular collection should be useful in
   object-oriented frameworks, such as Class::Scaffold and Data::Conveyor.

FUNCTIONS
 set_push(ARRAY, LIST)
   Like "push()", but only pushes the item(s) onto the list indicated by
   the list or list ref (the first argument) if the list doesn't already
   contain it.

   Example:

       @foo = (1, 2, 3, 4);
       set_push @foo, 3, 1, 5, 1, 6;
       # @foo is now (1, 2, 3, 4, 5, 6)

 flatten()
   If the first argument is an array reference, it returns the dereferenced
   array. If the first argument is undefined (or there are no arguments),
   it returns the empty list. Otherwise the argument list is returned as
   is.

 flex_grep(SCALAR, LIST)
   Like "grep()", but compares the first argument to each flattened (see
   "flatten()") version of each element of the list.

   Examples:

       flex_grep('foo', [ qw/foo bar baz/ ])                     # true
       flex_grep('foo', [ qw/bar baz flurble/ ])                 # false
       flex_grep('foo', 1..4, 'flurble', [ qw/foo bar baz/ ])    # true
       flex_grep('foo', 1..4, [ [ 'foo' ] ], [ qw/bar baz/ ])    # false

 is_deeply()
   Like Test::More's "is_deeply()" except that this version respects
   stringification overloads. If a package overloads stringification, it
   means that it specifies how it wants to be compared. Recent versions of
   Test::More break this behaviour, so here is a working version of
   "is_deeply()". This subroutine only does the comparison; there are no
   test diagnostics or results recorded or printed anywhere.

 eq_array()
   Like Test::More's "eq_array()" except that this version respects
   stringification overloads. If a package overloads stringification, it
   means that it specifies how it wants to be compared. Recent versions of
   Test::More break this behaviour, so here is a working version of
   "eq_array()". This subroutine only does the comparison; there are no
   test diagnostics or results recorded or printed anywhere.

 eq_hash()
   Like Test::More's "eq_hash()" except that this version respects
   stringification overloads. If a package overloads stringification, it
   means that it specifies how it wants to be compared. Recent versions of
   Test::More break this behaviour, so here is a working version of
   "eq_hash()". This subroutine only does the comparison; there are no test
   diagnostics or results recorded or printed anywhere.

 is_defined(SCALAR)
   A kind of "defined()" that is aware of Class::Value, which has its own
   views of what is a defined value and what isn't. The issue arose since
   Class::Value objects are supposed to be used transparently, mixed with
   normal scalar values. However, it is not possible to overload
   "definedness", and "defined()" used on a value object always returns
   true since the object reference certainly exists. However, what we want
   to know is whether the value encapsulated by the value object is
   defined. Additionally, each value class can have its own ideas of when
   its encapsulated value is defined. Therefore, Class::Value has an
   "is_defined()" method.

   This subroutine checks whether its argument is a value object and if so,
   calls the value object's "is_defined()" method. Otherwise, the normal
   "defined()" is used.

 value_of(SCALAR)
   Stringifies its argument, but returns undefined values (per
   "is_defined()") as "undef".

 str_value_of(SCALAR)
   Stringifies its argument, but returns undefined values (per
   "is_defined()") as the empty string.

 class_map(SCALAR, HASH)
   Takes an object or class name as the first argument (if it's an object,
   the class name used will be the package name the object is blessed
   into). Takes a hash whose keys are class names as the second argument.
   The hash values are completely arbitrary.

   Looks up the given class name in the hash and returns the corresponding
   value. If no such hash key is found, the class hierarchy for the given
   class name is traversed depth-first and checked against the hash keys in
   turn. The first value found is returned.

   If no key is found, a special key, "UNIVERSAL" is used.

   As an example of how this might be used, consider a hierarchy of
   exception classes. When evaluating each exception, we want to know how
   severe this exception is, so we define constants for "RC_OK" (meaning
   it's informational only), "RC_ERROR" (meaning some sort of action should
   be taken) and "RC_INTERNAL_ERROR" (meaning something has gone badly
   wrong and we might halt processing). In the following table assume that
   if you have names like "Foo::Bar" and "Foo::Bar::Baz", then the latter
   subclasses the former.

       %map = (
           'UNIVERSAL'                                => RC_INTERNAL_ERROR,
           'My::Exception::Business'                  => RC_ERROR,
           'My::Exception::Internal'                  => RC_INTERNAL_ERROR,
           'My::Exception::Business::ValueNormalized' => RC_OK,
       );

   Assuming that "My::Exception::Business::IllegalValue" exists and that it
   subclasses "My::Exception::Business", here are some outcomes:

       class_map('My::Exception::Business::IllegalValue', \%map)     # RC_ERROR
       class_map('My::Exception::Business::ValueNormalzed', \%map)   # RC_OK

 trim(STRING)
   Trims off whitespace at the beginning and end of the string and returns
   the trimmed string.

INSTALLATION
   See perlmodinstall for information and options on installing Perl
   modules.

BUGS AND LIMITATIONS
   No bugs have been reported.

   Please report any bugs or feature requests through the web interface at
   <http://rt.cpan.org/Public/Dist/Display.html?Name=Data-Miscellany>.

AVAILABILITY
   The latest version of this module is available from the Comprehensive
   Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find a
   CPAN site near you, or see
   <http://search.cpan.org/dist/Data-Miscellany/>.

   The development version lives at
   <http://github.com/hanekomu/Data-Miscellany/>. Instead of sending
   patches, please fork this project using the standard git and github
   infrastructure.

AUTHOR
     Marcel Gruenauer <[email protected]>

COPYRIGHT AND LICENSE
   This software is copyright (c) 2004 by Marcel Gruenauer.

   This is free software; you can redistribute it and/or modify it under
   the same terms as the Perl 5 programming language system itself.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.