.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Data::Miscellany 3pm" .TH Data::Miscellany 3pm "2022-12-04" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Data::Miscellany \- Collection of miscellaneous subroutines .SH "VERSION" .IX Header "VERSION" version 1.100850 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& 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(\*(Aqfoo\*(Aq, [ qw/foo bar baz/ ]); # true \& flex_grep(\*(Aqfoo\*(Aq, [ qw/bar baz flurble/ ]); # false \& flex_grep(\*(Aqfoo\*(Aq, 1..4, \*(Aqflurble\*(Aq, [ qw/foo bar baz/ ]); # true \& flex_grep(\*(Aqfoo\*(Aq, 1..4, [ [ \*(Aqfoo\*(Aq ] ], [ qw/bar baz/ ]); # false .Ve .SH "DESCRIPTION" .IX Header "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. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "set_push(\s-1ARRAY, LIST\s0)" .IX Subsection "set_push(ARRAY, LIST)" Like \f(CW\*(C`push()\*(C'\fR, 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. .PP Example: .PP .Vb 3 \& @foo = (1, 2, 3, 4); \& set_push @foo, 3, 1, 5, 1, 6; \& # @foo is now (1, 2, 3, 4, 5, 6) .Ve .SS "\fBflatten()\fP" .IX Subsection "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. .SS "flex_grep(\s-1SCALAR, LIST\s0)" .IX Subsection "flex_grep(SCALAR, LIST)" Like \f(CW\*(C`grep()\*(C'\fR, but compares the first argument to each flattened (see \&\f(CW\*(C`flatten()\*(C'\fR) version of each element of the list. .PP Examples: .PP .Vb 4 \& flex_grep(\*(Aqfoo\*(Aq, [ qw/foo bar baz/ ]) # true \& flex_grep(\*(Aqfoo\*(Aq, [ qw/bar baz flurble/ ]) # false \& flex_grep(\*(Aqfoo\*(Aq, 1..4, \*(Aqflurble\*(Aq, [ qw/foo bar baz/ ]) # true \& flex_grep(\*(Aqfoo\*(Aq, 1..4, [ [ \*(Aqfoo\*(Aq ] ], [ qw/bar baz/ ]) # false .Ve .SS "\fBis_deeply()\fP" .IX Subsection "is_deeply()" Like Test::More's \f(CW\*(C`is_deeply()\*(C'\fR 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 \&\f(CW\*(C`is_deeply()\*(C'\fR. This subroutine only does the comparison; there are no test diagnostics or results recorded or printed anywhere. .SS "\fBeq_array()\fP" .IX Subsection "eq_array()" Like Test::More's \f(CW\*(C`eq_array()\*(C'\fR 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 \&\f(CW\*(C`eq_array()\*(C'\fR. This subroutine only does the comparison; there are no test diagnostics or results recorded or printed anywhere. .SS "\fBeq_hash()\fP" .IX Subsection "eq_hash()" Like Test::More's \f(CW\*(C`eq_hash()\*(C'\fR 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 \&\f(CW\*(C`eq_hash()\*(C'\fR. This subroutine only does the comparison; there are no test diagnostics or results recorded or printed anywhere. .SS "is_defined(\s-1SCALAR\s0)" .IX Subsection "is_defined(SCALAR)" A kind of \f(CW\*(C`defined()\*(C'\fR 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 \*(L"definedness\*(R", and \f(CW\*(C`defined()\*(C'\fR 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 \&\f(CW\*(C`is_defined()\*(C'\fR method. .PP This subroutine checks whether its argument is a value object and if so, calls the value object's \f(CW\*(C`is_defined()\*(C'\fR method. Otherwise, the normal \f(CW\*(C`defined()\*(C'\fR is used. .SS "value_of(\s-1SCALAR\s0)" .IX Subsection "value_of(SCALAR)" Stringifies its argument, but returns undefined values (per \f(CW\*(C`is_defined()\*(C'\fR) as \f(CW\*(C`undef\*(C'\fR. .SS "str_value_of(\s-1SCALAR\s0)" .IX Subsection "str_value_of(SCALAR)" Stringifies its argument, but returns undefined values (per \f(CW\*(C`is_defined()\*(C'\fR) as the empty string. .SS "class_map(\s-1SCALAR, HASH\s0)" .IX Subsection "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. .PP 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. .PP If no key is found, a special key, \f(CW\*(C`UNIVERSAL\*(C'\fR is used. .PP 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 \f(CW\*(C`RC_OK\*(C'\fR (meaning it's informational only), \f(CW\*(C`RC_ERROR\*(C'\fR (meaning some sort of action should be taken) and \&\f(CW\*(C`RC_INTERNAL_ERROR\*(C'\fR (meaning something has gone badly wrong and we might halt processing). In the following table assume that if you have names like \&\f(CW\*(C`Foo::Bar\*(C'\fR and \f(CW\*(C`Foo::Bar::Baz\*(C'\fR, then the latter subclasses the former. .PP .Vb 6 \& %map = ( \& \*(AqUNIVERSAL\*(Aq => RC_INTERNAL_ERROR, \& \*(AqMy::Exception::Business\*(Aq => RC_ERROR, \& \*(AqMy::Exception::Internal\*(Aq => RC_INTERNAL_ERROR, \& \*(AqMy::Exception::Business::ValueNormalized\*(Aq => RC_OK, \& ); .Ve .PP Assuming that \f(CW\*(C`My::Exception::Business::IllegalValue\*(C'\fR exists and that it subclasses \f(CW\*(C`My::Exception::Business\*(C'\fR, here are some outcomes: .PP .Vb 2 \& class_map(\*(AqMy::Exception::Business::IllegalValue\*(Aq, \e%map) # RC_ERROR \& class_map(\*(AqMy::Exception::Business::ValueNormalzed\*(Aq, \e%map) # RC_OK .Ve .SS "trim(\s-1STRING\s0)" .IX Subsection "trim(STRING)" Trims off whitespace at the beginning and end of the string and returns the trimmed string. .SH "INSTALLATION" .IX Header "INSTALLATION" See perlmodinstall for information and options on installing Perl modules. .SH "BUGS AND LIMITATIONS" .IX Header "BUGS AND LIMITATIONS" No bugs have been reported. .PP Please report any bugs or feature requests through the web interface at . .SH "AVAILABILITY" .IX Header "AVAILABILITY" The latest version of this module is available from the Comprehensive Perl Archive Network (\s-1CPAN\s0). Visit to find a \s-1CPAN\s0 site near you, or see . .PP The development version lives at . Instead of sending patches, please fork this project using the standard git and github infrastructure. .SH "AUTHOR" .IX Header "AUTHOR" .Vb 1 \& Marcel Gruenauer .Ve .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2004 by Marcel Gruenauer. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.