.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DBIx::Class::Helper::ResultSet::SearchOr 3pm"
.TH DBIx::Class::Helper::ResultSet::SearchOr 3pm "2014-09-17" "perl v5.20.1" "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"
DBIx::Class::Helper::ResultSet::SearchOr \- Combine ResultSet searches with OR's
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& package MyApp::Schema::ResultSet::Tests;
\&
\& use base \*(AqDBIx::Class::ResultSet\*(Aq;
\&
\& _\|_PACKAGE_\|_\->load_components(qw(Helper::ResultSet::IgnoreWantarray Helper::ResultSet::SearchOr));
\&
\& sub failed {
\&   my $self = shift;
\&
\&   my $me = $self\->current_source_alias;
\&
\&   $self\->search({ "$me.passed" => \*(Aq0\*(Aq });
\& }
\&
\& sub untested {
\&   my $self = shift;
\&
\&   my $me = $self\->current_source_alias;
\&
\&   $self\->search({ "$me.passed" => undef });
\& }
\&
\& sub not_passed {
\&   my $self = shift;
\&
\&   my $me = $self\->current_source_alias;
\&
\&   $self\->search_or([$self\->failed, $self\->untested]);
\& }
\&
\& 1;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
I would argue that the most important feature of DBIx::Class is the fact
that you can \*(L"chain\*(R" ResultSet searches.  Unfortunately this can cause problems
when you need to reuse multiple ResultSet methods as... well as or's.  In the
past I got around this by doing:
.PP
.Vb 1
\& $rs\->foo\->union([ $rs\->bar]);
.Ve
.PP
While this works, it can generate some hairy \s-1SQL\s0 pretty fast.  This Helper is
supposed to basically be a lightweight union.  Note that it therefor has a
number of \*(L"\s-1LIMITATIONS\*(R"\s0.  The thing that makes this module special is that
the ResultSet that is doing the \*(L"search_or\*(R" ing still limits everything
correctly.  To be clear, the following only returns \f(CW$user\fR's friends that
match either of the following criteria:
.PP
.Vb 5
\& my $friend_rs = $schema\->resultset(\*(AqFriend\*(Aq);
\& my @internet_friends = $user\->friends\->search_or([
\&   $friend_rs\->on_facebook,
\&   $friend_rs\->on_twitter,
\& ])\->all;
.Ve
.PP
With a union, you'd have to implement it like this:
.PP
.Vb 1
\& $user\->friends\->on_facebook\->union([ $user\->friends\->on_twitter ]);
.Ve
.PP
The union will work, but it will generate more complex \s-1SQL\s0 that may have lower
performance on your database.
.PP
See \*(L"\s-1NOTE\*(R"\s0 in DBIx::Class::Helper::ResultSet for a nice way to apply it to
your entire schema.
.SH "METHODS"
.IX Header "METHODS"
.SS "search_or"
.IX Subsection "search_or"
.Vb 1
\& my $new_rs = $rs\->search_or([ $rs\->foo, $rs\->bar ]);
.Ve
.PP
\&\f(CW\*(C`search_or\*(C'\fR takes a single arrayref of ResultSets.  The ResultSets \fBmust\fR
point to the same source or you will get an error message.  Additionally, no
check is made to ensure that more than one ResultSet is in the ArrayRef, but
only passing one ResultSet would not make any sense.
.SH "LIMITATIONS"
.IX Header "LIMITATIONS"
Because this module us basically an expression union and not a true union,
\&\f(CW\*(C`JOIN\*(C'\fR's won't Just Work.  If you have a ResultSet method that uses a \f(CW\*(C`JOIN\*(C'\fR
and you want to \f(CW\*(C`OR\*(C'\fR it with another method, you'll need to do something like
this:
.PP
.Vb 4
\& my @authors = $authors\->search(undef, { join => \*(Aqbooks\*(Aq })\->search_or([
\&    $authors\->wrote_good_books,
\&    $authors\->wrote_bestselling_books,
\& ])\->all;
.Ve
.PP
Furthermore, if you want to \f(CW\*(C`OR\*(C'\fR two methods that \f(CW\*(C`JOIN\*(C'\fR in the same
relationship via alternate paths you \fBmust\fR use
union.
.SH "AUTHOR"
.IX Header "AUTHOR"
Arthur Axel \*(L"fREW\*(R" Schmidt <frioux+cpan@gmail.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2014 by Arthur Axel \*(L"fREW\*(R" Schmidt.
.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.