NAME
    Data::Miscellany - Collection of miscellaneous subroutines

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.

SUBROUTINES
    "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.

BUGS AND LIMITATIONS
    No bugs have been reported.

    Please report any bugs or feature requests through the web interface at
    <http://rt.cpan.org>.

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

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/>.

AUTHORS
    Marcel Grnauer, "<marcel@cpan.org>"

COPYRIGHT AND LICENSE
    Copyright 2004-2009 by the authors.

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

