.\" Automatically generated by Pod::Man 2.27 (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 "Test::DatabaseRow::Object 3pm"
.TH Test::DatabaseRow::Object 3pm "2014-07-06" "perl v5.18.2" "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"
Test::DatabaseRow::Object \- examine database rows
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Test::More tests => 1;
\&  use Test::DatabaseRow::Object;
\& 
\&  # setup the test
\&  my $tdr = Test::DatabaseRow::Object\->new(
\&    sql_and_bind => "SELECT * FROM contacts WHERE cid = \*(Aq123\*(Aq",
\&    tests        => [ name => "trelane" ],
\&  );
\&
\&  # do the test and get a result back
\&  my $result_object = $tdr\->tests_ok();
\&
\&  # have those results render to Test::Builder
\&  $result_object\->pass_to_test_builder("my database test");
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides the underlying functionality of
\&\f(CW\*(C`Test::DatabaseRow\*(C'\fR.
.SS "Accessors"
.IX Subsection "Accessors"
These are the read only accessors of the object.  They may be
(optionally) set at object creation time by passing their name
and value to the constructor.
.PP
Each accessor may be queried by prefixing its name with the
\&\f(CW\*(C`has_\*(C'\fR to determine if it has been set or not.
.IP "db_results" 4
.IX Item "db_results"
An arrayref of hashrefs, each representing a row returned from
the database.  Each key in the hashref should be the column name
and the value the corresponding field's value.  This
datastructure is identical to that.
.Sp
If this accessor is not passed then it will be populated on
first use by executing the contents of \f(CW\*(C`sql_and_bind\*(C'\fR against the
passed \f(CW\*(C`dbh\*(C'\fR.
.IP "db_results_dumped" 4
.IX Item "db_results_dumped"
A string representation of the database results.
.Sp
If this accessor is not passed then it will be populated on
first use by using Test::Builder's explain function on
\&\f(CW\*(C`db_results\*(C'\fR
.IP "sql_and_bind" 4
.IX Item "sql_and_bind"
The \s-1SQL\s0 and bind variables to execute if no results were passed
into the db_results hash.  This should be an arrayref containing
the \s-1SQL\s0 as the first element and the bind values as further values.
.Sp
This accessor will automatically coerce a simple scalar passed
in into a single
.Sp
If this accessor is not passed then it will be populated on
first use by building \s-1SQL\s0 from the \f(CW\*(C`where\*(C'\fR and \f(CW\*(C`table\*(C'\fR accessors.
.IP "dbh" 4
.IX Item "dbh"
The database handle used to execute the \s-1SQL\s0 statement in
\&\f(CW\*(C`sql_and_bind\*(C'\fR if no \f(CW\*(C`db_results\*(C'\fR were passed.
.IP "table" 4
.IX Item "table"
The table name used to build the \s-1SQL\s0 query if no value is
passed to \f(CW\*(C`sql_and_bind\*(C'\fR.  String.
.IP "where" 4
.IX Item "where"
The data structure used to build the where clause of the \s-1SQL\s0
query if no value is passed to <sql_and_bind>.
.Sp
This accessor value should be a hashref of hashrefs, with the
outer keys being the \s-1SQL\s0 comparison operator, the inner keys
being the field names and the inner values being the values
to match against. For example:
.Sp
.Vb 4
\&  { 
\&    \*(Aq=\*(Aq    => { first => "Fred", last => "Flintstone", },
\&    \*(Aqlike\*(Aq => { address => "%Bedrock%" },
\&  }
.Ve
.Sp
Values of \f(CW\*(C`undef\*(C'\fR will automatically converted into checks
for NULLs.
.Sp
This accessor automatically coerces array refs that are
passed into a pure equals hashref.  For example:
.Sp
.Vb 1
\&  [ foo => "bar", bazz => "buzz" ]
.Ve
.Sp
Will be coerced into:
.Sp
.Vb 1
\&  { "=" => { foo => "bar", bazz => "buzz" } }
.Ve
.Sp
See \*(L"where\*(R" in Test::DatabaseRow for a more detailed explanation.
.IP "verbose" 4
.IX Item "verbose"
Truth value, default false.  Controls if the diagnostic messages
printed during \f(CW\*(C`row_ok\*(C'\fR on failure contain details of the \s-1SQL\s0
executed or not.
.IP "verbose_data" 4
.IX Item "verbose_data"
Truth value, default false.  Controls if the diagnostic messages
printed during \f(CW\*(C`row_ok\*(C'\fR on failure contain a Data::Dumper
style dump of the resulting rows from the database.
.IP "force_utf8" 4
.IX Item "force_utf8"
Truth value, default false.  Controls if the utf8 flag should be
turned on on values returned from the database.  See
\&\*(L"utf8 hacks\*(R" in Test::DatabaseRow for why this might be important.
.Sp
This flag only effects data that this module places into
\&\f(CW\*(C`db_resutls\*(C'\fR.  If you manually populate this accessor this
flag will have no effect.
.IP "tests" 4
.IX Item "tests"
If set, enables specified tests on the first element of
\&\f(CW\*(C`db_results\*(C'\fR when \f(CW\*(C`row_ok\*(C'\fR is called.
.Sp
This accessor value should be a hashref of hashrefs, with the
outer keys being the Perl comparison operator, the inner keys
being the field names and the inner values being the values to
test against. For example:
.Sp
.Vb 4
\&  { 
\&    \*(Aqeq\*(Aq => { first => "Fred", last => "Flintstone", },
\&    \*(Aq=~\*(Aq => { address => "%Bedrock%" },
\&  }
.Ve
.Sp
This accessor automatically coerces array refs that are
passed into a hashref structure, converting things that look
like strings into \f(CW\*(C`eq\*(C'\fR tests, things that look like numbers
into \f(CW\*(C`==\*(C'\fR tests and things that are references to regular
expressions into \f(CW\*(C`=~\*(C'\fR tests.  Foe example:
.Sp
.Vb 1
\&  [ num => 123, letters => "abc", kinda => qr/substring/ ]
.Ve
.Sp
Will be coerced into
.Sp
.Vb 5
\&  {
\&    \*(Aq==\*(Aq => { num => 123, },
\&    \*(Aqeq\*(Aq => { letters => "abc", },
\&    \*(Aq=~\*(Aq => { kinda => qr/substring/ },
\&  }
.Ve
.Sp
See \*(L"tests\*(R" in Test::DatabaseRow for a more detailed explanation.
.IP "check_all_rows" 4
.IX Item "check_all_rows"
Boolean to determine if we should test all rows (during
\&\f(CW\*(C`db_results_ok\*(C'\fR and \f(CW\*(C`test_ok\*(C'\fR) or just check the first
row.  Default true.
.IP "results" 4
.IX Item "results"
If set, enable tests to check the number of rows we returned by
\&\f(CW\*(C`db_results\*(C'\fR is exactly this value when \f(CW\*(C`row_ok\*(C'\fR is called.
Integer.
.IP "max_results" 4
.IX Item "max_results"
If set, enable tests to check the number of rows we returned by
\&\f(CW\*(C`db_results\*(C'\fR is at most this value when \f(CW\*(C`row_ok\*(C'\fR is called.
Integer.
.IP "min_results" 4
.IX Item "min_results"
If set, enable tests to check the number of rows we returned by
\&\f(CW\*(C`db_results\*(C'\fR is at least this value when \f(CW\*(C`row_ok\*(C'\fR is called.
Integer.
.SS "Methods"
.IX Subsection "Methods"
.IP "new(...)" 4
.IX Item "new(...)"
Simple constructor.  Passing arguments to the constructor sets
the values of the accessors.
.IP "number_of_results_ok" 4
.IX Item "number_of_results_ok"
Returns a Test::DatabaseRow::Result that represents if the
number of results in \f(CW\*(C`db_results\*(C'\fR match the requirements
for the number of results.
.ie n .IP "row_at_index_ok( $row_index )" 4
.el .IP "row_at_index_ok( \f(CW$row_index\fR )" 4
.IX Item "row_at_index_ok( $row_index )"
Returns a Test::DatabaseRow::Result that represents if the
element corresponding to the passed row index in \f(CW\*(C`db_results\*(C'\fR
match the tests defined in \f(CW\*(C`tests\*(C'\fR.
.IP "db_results_ok" 4
.IX Item "db_results_ok"
Returns a Test::DatabaseRow::Result that represents if all
elements in \f(CW\*(C`db_results\*(C'\fR match the tests defined in \f(CW\*(C`tests\*(C'\fR.
.IP "test_ok" 4
.IX Item "test_ok"
Returns a Test::DatabaseRow::Result that represents if the
number of results in \f(CW\*(C`db_results\*(C'\fR match the requirements
for the number of results and  all
elements in \f(CW\*(C`db_results\*(C'\fR match the tests defined in \f(CW\*(C`tests\*(C'\fR.
.SH "BUGS"
.IX Header "BUGS"
Bugs (and requests for new features) can be reported though
the \s-1CPAN RT\s0 system:
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test\-DatabaseRow>
.PP
Alternatively, you can simply fork this project on github and
send me pull requests.  Please see <http://github.com/2shortplanks/Test\-DatabaseRow>
.SH "AUTHOR"
.IX Header "AUTHOR"
Written by Mark Fowler \fBmark@twoshortplanks.com\fR
.PP
Copyright Profero 2003, 2004.  Copyright Mark Fowler 2011.
.PP
Some code taken from \fBTest::Builder\fR, written by Michael Schwern.
Some code taken from \fBRegexp::Common\fR, written by Damian Conway.  Neither
objected to its inclusion in this module.
.PP
Some code taken from \fBLingua::EN::Numbers::Ordinate\fR, written by Sean M. Burke.
.PP
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Test::DatabaseRow::Object, Test::DatabaseRow::Result, Test::More, \s-1DBI\s0