1NAME
2 Data::Miscellany - Collection of miscellaneous subroutines
3
4VERSION
5 version 1.100850
6
7SYNOPSIS
8 use Data::Miscellany qw/set_push flex_grep/;
9
10 my @foo = (1, 2, 3, 4);
11 set_push @foo, 3, 1, 5, 1, 6;
12 # @foo is now (1, 2, 3, 4, 5, 6);
13
14 flex_grep('foo', [ qw/foo bar baz/ ]); # true
15 flex_grep('foo', [ qw/bar baz flurble/ ]); # false
16 flex_grep('foo', 1..4, 'flurble', [ qw/foo bar baz/ ]); # true
17 flex_grep('foo', 1..4, [ [ 'foo' ] ], [ qw/bar baz/ ]); # false
18
19DESCRIPTION
20 This is a collection of miscellaneous subroutines useful in wide but
21 varying scenarios; a catch-all module for things that don't obviously
22 belong anywhere else. Obviously what's useful differs from person to
23 person, but this particular collection should be useful in
24 object-oriented frameworks, such as Class::Scaffold and Data::Conveyor.
25
26FUNCTIONS
27 set_push(ARRAY, LIST)
28 Like "push()", but only pushes the item(s) onto the list indicated by
29 the list or list ref (the first argument) if the list doesn't already
30 contain it.
31
32 Example:
33
34 @foo = (1, 2, 3, 4);
35 set_push @foo, 3, 1, 5, 1, 6;
36 # @foo is now (1, 2, 3, 4, 5, 6)
37
38 flatten()
39 If the first argument is an array reference, it returns the dereferenced
40 array. If the first argument is undefined (or there are no arguments),
41 it returns the empty list. Otherwise the argument list is returned as
42 is.
43
44 flex_grep(SCALAR, LIST)
45 Like "grep()", but compares the first argument to each flattened (see
46 "flatten()") version of each element of the list.
47
48 Examples:
49
50 flex_grep('foo', [ qw/foo bar baz/ ]) # true
51 flex_grep('foo', [ qw/bar baz flurble/ ]) # false
52 flex_grep('foo', 1..4, 'flurble', [ qw/foo bar baz/ ]) # true
53 flex_grep('foo', 1..4, [ [ 'foo' ] ], [ qw/bar baz/ ]) # false
54
55 is_deeply()
56 Like Test::More's "is_deeply()" except that this version respects
57 stringification overloads. If a package overloads stringification, it
58 means that it specifies how it wants to be compared. Recent versions of
59 Test::More break this behaviour, so here is a working version of
60 "is_deeply()". This subroutine only does the comparison; there are no
61 test diagnostics or results recorded or printed anywhere.
62
63 eq_array()
64 Like Test::More's "eq_array()" except that this version respects
65 stringification overloads. If a package overloads stringification, it
66 means that it specifies how it wants to be compared. Recent versions of
67 Test::More break this behaviour, so here is a working version of
68 "eq_array()". This subroutine only does the comparison; there are no
69 test diagnostics or results recorded or printed anywhere.
70
71 eq_hash()
72 Like Test::More's "eq_hash()" except that this version respects
73 stringification overloads. If a package overloads stringification, it
74 means that it specifies how it wants to be compared. Recent versions of
75 Test::More break this behaviour, so here is a working version of
76 "eq_hash()". This subroutine only does the comparison; there are no test
77 diagnostics or results recorded or printed anywhere.
78
79 is_defined(SCALAR)
80 A kind of "defined()" that is aware of Class::Value, which has its own
81 views of what is a defined value and what isn't. The issue arose since
82 Class::Value objects are supposed to be used transparently, mixed with
83 normal scalar values. However, it is not possible to overload
84 "definedness", and "defined()" used on a value object always returns
85 true since the object reference certainly exists. However, what we want
86 to know is whether the value encapsulated by the value object is
87 defined. Additionally, each value class can have its own ideas of when
88 its encapsulated value is defined. Therefore, Class::Value has an
89 "is_defined()" method.
90
91 This subroutine checks whether its argument is a value object and if so,
92 calls the value object's "is_defined()" method. Otherwise, the normal
93 "defined()" is used.
94
95 value_of(SCALAR)
96 Stringifies its argument, but returns undefined values (per
97 "is_defined()") as "undef".
98
99 str_value_of(SCALAR)
100 Stringifies its argument, but returns undefined values (per
101 "is_defined()") as the empty string.
102
103 class_map(SCALAR, HASH)
104 Takes an object or class name as the first argument (if it's an object,
105 the class name used will be the package name the object is blessed
106 into). Takes a hash whose keys are class names as the second argument.
107 The hash values are completely arbitrary.
108
109 Looks up the given class name in the hash and returns the corresponding
110 value. If no such hash key is found, the class hierarchy for the given
111 class name is traversed depth-first and checked against the hash keys in
112 turn. The first value found is returned.
113
114 If no key is found, a special key, "UNIVERSAL" is used.
115
116 As an example of how this might be used, consider a hierarchy of
117 exception classes. When evaluating each exception, we want to know how
118 severe this exception is, so we define constants for "RC_OK" (meaning
119 it's informational only), "RC_ERROR" (meaning some sort of action should
120 be taken) and "RC_INTERNAL_ERROR" (meaning something has gone badly
121 wrong and we might halt processing). In the following table assume that
122 if you have names like "Foo::Bar" and "Foo::Bar::Baz", then the latter
123 subclasses the former.
124
125 %map = (
126 'UNIVERSAL' => RC_INTERNAL_ERROR,
127 'My::Exception::Business' => RC_ERROR,
128 'My::Exception::Internal' => RC_INTERNAL_ERROR,
129 'My::Exception::Business::ValueNormalized' => RC_OK,
130 );
131
132 Assuming that "My::Exception::Business::IllegalValue" exists and that it
133 subclasses "My::Exception::Business", here are some outcomes:
134
135 class_map('My::Exception::Business::IllegalValue', \%map) # RC_ERROR
136 class_map('My::Exception::Business::ValueNormalzed', \%map) # RC_OK
137
138 trim(STRING)
139 Trims off whitespace at the beginning and end of the string and returns
140 the trimmed string.
141
142INSTALLATION
143 See perlmodinstall for information and options on installing Perl
144 modules.
145
146BUGS AND LIMITATIONS
147 No bugs have been reported.
148
149 Please report any bugs or feature requests through the web interface at
150 <http://rt.cpan.org/Public/Dist/Display.html?Name=Data-Miscellany>.
151
152AVAILABILITY
153 The latest version of this module is available from the Comprehensive
154 Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find a
155 CPAN site near you, or see
156 <http://search.cpan.org/dist/Data-Miscellany/>.
157
158 The development version lives at
159 <http://github.com/hanekomu/Data-Miscellany/>. Instead of sending
160 patches, please fork this project using the standard git and github
161 infrastructure.
162
163AUTHOR
164 Marcel Gruenauer <marcel@cpan.org>
165
166COPYRIGHT AND LICENSE
167 This software is copyright (c) 2004 by Marcel Gruenauer.
168
169 This is free software; you can redistribute it and/or modify it under
170 the same terms as the Perl 5 programming language system itself.
171
172