1MooseX::Role::Matcher(3U)ser Contributed Perl DocumentatiMoonoseX::Role::Matcher(3)
2
6 MooseX::Role::Matcher - generic object matching based on attributes and
7 methods
8
10 version 0.05
11
13 package Person;
14 use Moose;
15 with 'MooseX::Role::Matcher' => { default_match => 'name' };
16 has name => (is => 'ro', isa => 'Str');
18 has age => (is => 'ro', isa => 'Num');
19 has phone => (is => 'ro', isa => 'Str');
20 package main;
22 my @people = (
23 Person->new(name => 'James', age => 22, phone => '555-1914'),
24 Person->new(name => 'Jesse', age => 22, phone => '555-6287'),
25 Person->new(name => 'Eric', age => 21, phone => '555-7634'),
26 );
27 # is James 22?
29 $people[0]->match(age => 22);
30 # which people are not 22?
32 my @not_twenty_two = Person->grep_matches([@people], '!age' => 22);
33 # do any of the 22-year-olds have a phone number ending in 4?
35 Person->any_match([@people], age => 22, phone => qr/4$/);
36 # does everyone's name start with either J or E?
38 Person->all_match([@people], name => [qr/^J/, qr/^E/]);
39 # find the first person whose name is 4 characters long (using the
41 # default_match of name)
42 my $four = Person->first_match([@people], sub { length == 4 });
43
45 This role adds flexible matching and searching capabilities to your
46 Moose class. It provides a match method, which tests attributes and
47 methods of your object against strings, regexes, or coderefs, and also
48 provides several class methods for using match on lists of objects.
49
51 MooseX::Role::Matcher is a parameterized role (see
52 MooseX::Role::Parameterized). The parameters it takes are:
53 default_match
55 Which attribute/method to test against by default, if none are
56 specified explicitly. Setting default_match to 'foo' allows using
57 "$obj->match('bar')" rather than "$obj->match(foo => 'bar')".
58 allow_missing_methods
60 If set to true, matching against a method that doesn't exist is
61 treated as though matching against undef. Otherwise, the match call
62 dies.
63
65 first_match
66 my $four = Person->first_match([@people], sub { length == 4 });
67 Class method which takes an arrayref of objects in the class that
69 consumed this role, and calls "match" on each object in the arrayref,
70 passing it the remaining arguments, and returns the first object for
71 which match returns true.
72 grep_matches
74 my @not_twenty_two = Person->grep_matches([@people], '!age' => 22);
75 Class method which takes an arrayref of objects in the class that
77 consumed this role, and calls "match" on each object in the arrayref,
78 passing it the remaining arguments, and returns the each object for
79 which match returns true.
80 any_match
82 Person->any_match([@people], age => 22, number => qr/4$/);
83 Class method which takes an arrayref of objects in the class that
85 consumed this role, and calls "match" on each object in the arrayref,
86 passing it the remaining arguments, and returns true if any "match"
87 calls return true, otherwise returns false.
88 all_match
90 Person->all_match([@people], name => [qr/^J/, qr/^E/]);
91 Class method which takes an arrayref of objects in the class that
93 consumed this role, and calls "match" on each object in the arrayref,
94 passing it the remaining arguments, and returns false if any "match"
95 calls return false, otherwise returns true.
96 match
98 $person->match(age => 22);
99 This method provides the majority of the functionality of this role. It
101 accepts a hash of arguments, with keys being the methods (usually
102 attributes) of the object to be tested, and values being things to test
103 against them. Possible types of values are:
104 SCALAR
106 Returns true if the result of the method is equal to ("eq") the
107 value of the scalar, otherwise returns false.
108 REGEXP
110 Returns true if the result of the method matches the regexp,
111 otherwise returns false.
112 CODEREF
114 Calls the coderef with $_ set to the result of the method,
115 returning true if the coderef returns true, and false otherwise.
116 UNDEF
118 Returns true if the method returns undef, or if the object doesn't
119 have a method by this name, otherwise returns false.
120 ARRAYREF
122 Matches the result of the method against each element in the
123 arrayref as described above, returning true if any of the
124 submatches return true, and false otherwise.
125 HASHREF
127 If the method does not return an object which does
128 MooseX::Role::Matcher, returns false. Otherwise, returns the result
129 of calling "match" on the returned object, with the contents of the
130 hashref as arguments.
131 Method names can also be given with a leading '!', which inverts that
133 test. The first key can be omitted from the argument list if it is the
134 method name passed to the default_match parameter when composing this
135 role.
136
138 Jesse Luehrs <doy at tozt dot net>
139
141 This software is copyright (c) 2008-2009 by Jesse Luehrs.
142 This is free software; you can redistribute it and/or modify it under
144 the same terms as perl itself.
145
147 Better error handling/reporting
148
150 Moose
151 MooseX::Role::Parameterized
153
155 No known bugs.
156 Please report any bugs through RT: email "bug-moosex-role-matcher at
158 rt.cpan.org", or browse to
159 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MooseX-Role-Matcher
160 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MooseX-Role-Matcher>.
161
163 You can find this documentation for this module with the perldoc
164 command.
165 perldoc MooseX::Role::Matcher
167 You can also look for information at:
169 · AnnoCPAN: Annotated CPAN documentation
171 http://annocpan.org/dist/MooseX-Role-Matcher
173 <http://annocpan.org/dist/MooseX-Role-Matcher>
174 · CPAN Ratings
176 http://cpanratings.perl.org/d/MooseX-Role-Matcher
178 <http://cpanratings.perl.org/d/MooseX-Role-Matcher>
179 · RT: CPAN's request tracker
181 http://rt.cpan.org/NoAuth/Bugs.html?Dist=MooseX-Role-Matcher
183 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=MooseX-Role-Matcher>
184 · Search CPAN
186 http://search.cpan.org/dist/MooseX-Role-Matcher
188 <http://search.cpan.org/dist/MooseX-Role-Matcher>
189perl v5.12.3 2009-02-04 MooseX::Role::Matcher(3)