1MooseX::Role::Matcher(3U)ser Contributed Perl DocumentatiMoonoseX::Role::Matcher(3)
2
3
4

NAME

6       MooseX::Role::Matcher - generic object matching based on attributes and
7       methods
8

VERSION

10       version 0.05
11

SYNOPSIS

13         package Person;
14         use Moose;
15         with 'MooseX::Role::Matcher' => { default_match => 'name' };
16
17         has name  => (is => 'ro', isa => 'Str');
18         has age   => (is => 'ro', isa => 'Num');
19         has phone => (is => 'ro', isa => 'Str');
20
21         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
28         # is James 22?
29         $people[0]->match(age => 22);
30
31         # which people are not 22?
32         my @not_twenty_two = Person->grep_matches([@people], '!age' => 22);
33
34         # 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
37         # does everyone's name start with either J or E?
38         Person->all_match([@people], name => [qr/^J/, qr/^E/]);
39
40         # 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

DESCRIPTION

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

PARAMETERS

51       MooseX::Role::Matcher is a parameterized role (see
52       MooseX::Role::Parameterized). The parameters it takes are:
53
54       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
59       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

METHODS

65   first_match
66         my $four = Person->first_match([@people], sub { length == 4 });
67
68       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
73   grep_matches
74         my @not_twenty_two = Person->grep_matches([@people], '!age' => 22);
75
76       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
81   any_match
82         Person->any_match([@people], age => 22, number => qr/4$/);
83
84       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
89   all_match
90         Person->all_match([@people], name => [qr/^J/, qr/^E/]);
91
92       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
97   match
98         $person->match(age => 22);
99
100       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
105       SCALAR
106           Returns true if the result of the method is equal to ("eq") the
107           value of the scalar, otherwise returns false.
108
109       REGEXP
110           Returns true if the result of the method matches the regexp,
111           otherwise returns false.
112
113       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
117       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
121       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
126       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
132       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

AUTHOR

138         Jesse Luehrs <doy at tozt dot net>
139
141       This software is copyright (c) 2008-2009 by Jesse Luehrs.
142
143       This is free software; you can redistribute it and/or modify it under
144       the same terms as perl itself.
145

TODO

147       Better error handling/reporting
148

SEE ALSO

150       Moose
151
152       MooseX::Role::Parameterized
153

BUGS

155       No known bugs.
156
157       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

SUPPORT

163       You can find this documentation for this module with the perldoc
164       command.
165
166           perldoc MooseX::Role::Matcher
167
168       You can also look for information at:
169
170       ·   AnnoCPAN: Annotated CPAN documentation
171
172           http://annocpan.org/dist/MooseX-Role-Matcher
173           <http://annocpan.org/dist/MooseX-Role-Matcher>
174
175       ·   CPAN Ratings
176
177           http://cpanratings.perl.org/d/MooseX-Role-Matcher
178           <http://cpanratings.perl.org/d/MooseX-Role-Matcher>
179
180       ·   RT: CPAN's request tracker
181
182           http://rt.cpan.org/NoAuth/Bugs.html?Dist=MooseX-Role-Matcher
183           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=MooseX-Role-Matcher>
184
185       ·   Search CPAN
186
187           http://search.cpan.org/dist/MooseX-Role-Matcher
188           <http://search.cpan.org/dist/MooseX-Role-Matcher>
189
190
191
192perl v5.12.3                      2009-02-04          MooseX::Role::Matcher(3)
Impressum