File Coverage

blib/lib/DBIx/Class/Helper/ResultSet/Shortcut.pm
Criterion Covered Total %
statement 9 9 100.0
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 12 12 100.0


line stmt bran cond sub pod time code
1             package DBIx::Class::Helper::ResultSet::Shortcut;
2             $DBIx::Class::Helper::ResultSet::Shortcut::VERSION = '2.036000';
3             # ABSTRACT: Shortcuts to common searches (->order_by, etc)
4              
5 57     57   93338 use strict;
  57         139  
  57         1557  
6 57     57   282 use warnings;
  57         117  
  57         2531  
7              
8 57         312 use parent (qw(
9             DBIx::Class::Helper::ResultSet::Shortcut::AddColumns
10             DBIx::Class::Helper::ResultSet::Shortcut::Columns
11             DBIx::Class::Helper::ResultSet::Shortcut::Distinct
12             DBIx::Class::Helper::ResultSet::Shortcut::GroupBy
13             DBIx::Class::Helper::ResultSet::Shortcut::HasRows
14             DBIx::Class::Helper::ResultSet::Shortcut::HRI
15             DBIx::Class::Helper::ResultSet::Shortcut::Limit
16             DBIx::Class::Helper::ResultSet::Shortcut::OrderByMagic
17             DBIx::Class::Helper::ResultSet::Shortcut::Prefetch
18             DBIx::Class::Helper::ResultSet::Shortcut::LimitedPage
19             DBIx::Class::Helper::ResultSet::Shortcut::RemoveColumns
20             DBIx::Class::Helper::ResultSet::Shortcut::ResultsExist
21             DBIx::Class::Helper::ResultSet::Shortcut::Rows
22             DBIx::Class::Helper::ResultSet::Shortcut::Page
23             DBIx::Class::Helper::ResultSet::Shortcut::Search
24 57     57   320 ));
  57         152  
25              
26             1;
27              
28             __END__
29              
30             =pod
31              
32             =head1 NAME
33              
34             DBIx::Class::Helper::ResultSet::Shortcut - Shortcuts to common searches (->order_by, etc)
35              
36             =head1 SYNOPSIS
37              
38             package MyApp::Schema::ResultSet::Foo;
39              
40             __PACKAGE__->load_components(qw{Helper::ResultSet::Shortcut});
41              
42             ...
43              
44             1;
45              
46             And then elsewhere:
47              
48             # let's say you grab a resultset from somewhere else
49             my $foo_rs = get_common_rs()
50             # but I'd like it sorted!
51             ->order_by({ -desc => 'power_level' })
52             # and without those other dumb columns
53             ->columns([qw/cromulence_ratio has_jimmies_rustled/])
54             # but get rid of those duplicates
55             ->distinct
56             # and put those straight into hashrefs, please
57             ->hri
58             # but only give me the first 3
59             ->rows(3);
60              
61             =head1 DESCRIPTION
62              
63             This helper provides convenience methods for resultset modifications.
64              
65             See L<DBIx::Class::Helper::ResultSet/NOTE> for a nice way to apply it to your
66             entire schema.
67              
68             =head1 SEE ALSO
69              
70             This component is actually a number of other components put together. It will
71             get more components added to it over time. If you are worried about all the
72             extra methods you won't use or something, using the individual shortcuts is
73             a simple solution. All the documentation will remain here, but the individual
74             components are:
75              
76             =over 2
77              
78             =item * L<DBIx::Class::Helper::ResultSet::Shortcut::HRI>
79              
80             =item * L<DBIx::Class::Helper::ResultSet::Shortcut::OrderBy>
81              
82             =item * L<DBIx::Class::Helper::ResultSet::Shortcut::OrderByMagic>
83              
84             (adds the "magic string" functionality to
85             C<DBIx::Class::Helper::ResultSet::Shortcut::OrderBy>))
86              
87             =item * L<DBIx::Class::Helper::ResultSet::Shortcut::GroupBy>
88              
89             =item * L<DBIx::Class::Helper::ResultSet::Shortcut::Distinct>
90              
91             =item * L<DBIx::Class::Helper::ResultSet::Shortcut::Rows>
92              
93             =item * L<DBIx::Class::Helper::ResultSet::Shortcut::Limit>
94              
95             (inherits from C<DBIx::Class::Helper::ResultSet::Shortcut::Rows>)
96              
97             =item * L<DBIx::Class::Helper::ResultSet::Shortcut::HasRows>
98              
99             (inherits from C<DBIx::Class::Helper::ResultSet::Shortcut::Rows>)
100              
101             =item * L<DBIx::Class::Helper::ResultSet::Shortcut::Columns>
102              
103             =item * L<DBIx::Class::Helper::ResultSet::Shortcut::AddColumns>
104              
105             =item * L<DBIx::Class::Helper::ResultSet::Shortcut::Page>
106              
107             =item * L<DBIx::Class::Helper::ResultSet::Shortcut::LimitedPage>
108              
109             (inherits from C<DBIx::Class::Helper::ResultSet::Shortcut::Page> and
110             L<DBIx::Class::Helper::ResultSet::Shortcut::Rows>)
111              
112             =item * L<DBIx::Class::Helper::ResultSet::Shortcut::ResultsExist>
113              
114             =back
115              
116             =head1 METHODS
117              
118             =head2 distinct
119              
120             $foo_rs->distinct
121              
122             # equivalent to...
123             $foo_rs->search(undef, { distinct => 1 });
124              
125             =head2 group_by
126              
127             $foo_rs->group_by([ qw/ some column names /])
128              
129             # equivalent to...
130             $foo_rs->search(undef, { group_by => [ qw/ some column names /] });
131              
132             =head2 order_by
133              
134             $foo_rs->order_by({ -desc => 'col1' });
135              
136             # equivalent to...
137             $foo_rs->search(undef, { order_by => { -desc => 'col1' } });
138              
139             You can also specify the order as a "magic string", e.g.:
140              
141             $foo_rs->order_by('!col1') # ->order_by({ -desc => 'col1' })
142             $foo_rs->order_by('col1,col2') # ->order_by([qw(col1 col2)])
143             $foo_rs->order_by('col1,!col2') # ->order_by([{ -asc => 'col1' }, { -desc => 'col2' }])
144             $foo_rs->order_by(qw(col1 col2)) # ->order_by([qw(col1 col2)])
145              
146             Can mix it all up as well:
147              
148             $foo_rs->order_by(qw(col1 col2 col3), 'col4,!col5')
149              
150             =head2 hri
151              
152             $foo_rs->hri;
153              
154             # equivalent to...
155             $foo_rs->search(undef, {
156             result_class => 'DBIx::Class::ResultClass::HashRefInflator'
157             });
158              
159             =head2 rows
160              
161             $foo_rs->rows(10);
162              
163             # equivalent to...
164             $foo_rs->search(undef, { rows => 10 })
165              
166             =head2 limit
167              
168             This is an alias for C<rows>.
169              
170             $foo_rs->limit(10);
171              
172             # equivalent to...
173             $foo_rs->rows(10);
174              
175             =head2 has_rows
176              
177             A lighter way to check the resultset contains any data rather than
178             calling C<< $rs->count >>.
179              
180             =head2 page
181              
182             $foo_rs->page(2);
183              
184             # equivalent to...
185             $foo_rs->search(undef, { page => 2 })
186              
187             =head2 limited_page
188              
189             $foo_rs->limited_page(2, 3);
190              
191             # equivalent to...
192             $foo_rs->search(undef, { page => 2, rows => 3 })
193              
194             =head2 columns
195              
196             $foo_rs->columns([qw/ some column names /]);
197              
198             # equivalent to...
199             $foo_rs->search(undef, { columns => [qw/ some column names /] });
200              
201             =head2 add_columns
202              
203             $foo_rs->add_columns([qw/ some column names /]);
204              
205             # equivalent to...
206             $foo_rs->search(undef, { '+columns' => [qw/ some column names /] });
207              
208             =head2 remove_columns
209              
210             $foo_rs->remove_columns([qw/ some column names /]);
211              
212             # equivalent to...
213             $foo_rs->search(undef, { remove_columns => [qw/ some column names /] });
214              
215             =head2 prefetch
216              
217             $foo_rs->prefetch('bar');
218              
219             # equivalent to...
220             $foo_rs->search(undef, { prefetch => 'bar' });
221              
222             =head2 results_exist($cond?)
223              
224             my $results_exist = $schema->resultset('Bar')->search({...})->results_exist;
225              
226             # there is no easily expressable equivalent, so this is not exactly a
227             # shortcut. Nevertheless kept in this class for historical reasons
228              
229             Uses C<EXISTS> SQL function to check if the query would return anything.
230             Usually much less resource intensive the more common C<< foo() if $rs->count >>
231             idiom.
232              
233             The optional C<$cond> argument can be used like in C<search()>.
234              
235             =head2 results_exist_as_query($cond?)
236              
237             ...->search(
238             {},
239             { '+columns' => {
240             subquery_has_members => $some_correlated_rs->results_exist_as_query
241             }},
242             );
243              
244             # there is no easily expressable equivalent, so this is not exactly a
245             # shortcut. Nevertheless kept in this class for historical reasons
246              
247             The query generator behind L</results_exist>. Can be used standalone in
248             complex queries returning a boolean result within a larger query context.
249              
250             =head2 null(@columns || \@columns)
251              
252             $rs->null('status');
253             $rs->null(['status', 'title']);
254              
255             =head2 not_null(@columns || \@columns)
256              
257             $rs->not_null('status');
258             $rs->not_null(['status', 'title']);
259              
260             =head2 like($column || \@columns, $cond)
261              
262             $rs->like('lyrics', '%zebra%');
263             $rs->like(['lyrics', 'title'], '%zebra%');
264              
265             =head2 not_like($column || \@columns, $cond)
266              
267             $rs->not_like('lyrics', '%zebra%');
268             $rs->not_like(['lyrics', 'title'], '%zebra%');
269              
270             =head1 AUTHOR
271              
272             Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>
273              
274             =head1 COPYRIGHT AND LICENSE
275              
276             This software is copyright (c) 2020 by Arthur Axel "fREW" Schmidt.
277              
278             This is free software; you can redistribute it and/or modify it under
279             the same terms as the Perl 5 programming language system itself.
280              
281             =cut