--- /dev/null
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
+.\"
+.\" 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" ''
+'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.
+.ie \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.el \{\
+. de IX
+..
+.\}
+.\"
+.\" 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::Differences 3"
+.TH Test::Differences 3 "2009-10-17" "perl v5.8.7" "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::Differences \- Test strings and data structures and show differences if not ok
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 2
+\& use Test; ## Or use Test::More
+\& use Test::Differences;
+\&
+\& eq_or_diff $got, "a\enb\enc\en", "testing strings";
+\& eq_or_diff \e@got, [qw( a b c )], "testing arrays";
+\&
+\& ## Passing options:
+\& eq_or_diff $got, $expected, $name, { context => 300 }; ## options
+\&
+\& ## Using with DBI\-like data structures
+\&
+\& use DBI;
+\&
+\& ... open connection & prepare statement and @expected_... here...
+\&
+\& eq_or_diff $sth\->fetchall_arrayref, \e@expected_arrays "testing DBI arrays";
+\& eq_or_diff $sth\->fetchall_hashref, \e@expected_hashes, "testing DBI hashes";
+\&
+\& ## To force textual or data line numbering (text lines are numbered 1..):
+\& eq_or_diff_text ...;
+\& eq_or_diff_data ...;
+.Ve
+.SH "EXPORT"
+.IX Header "EXPORT"
+This module exports three test functions and four diff-style functions:
+.IP "\(bu" 4
+Test functions
+.RS 4
+.IP "\(bu" 4
+\&\f(CW\*(C`eq_or_diff\*(C'\fR
+.IP "\(bu" 4
+\&\f(CW\*(C`eq_or_diff_data\*(C'\fR
+.IP "\(bu" 4
+\&\f(CW\*(C`eq_or_diff_text\*(C'\fR
+.RE
+.RS 4
+.RE
+.IP "\(bu" 4
+Diff style functions
+.RS 4
+.IP "\(bu" 4
+\&\f(CW\*(C`table_diff\*(C'\fR (the default)
+.IP "\(bu" 4
+\&\f(CW\*(C`unified_diff\*(C'\fR
+.IP "\(bu" 4
+\&\f(CW\*(C`oldstyle_diff\*(C'\fR
+.IP "\(bu" 4
+\&\f(CW\*(C`context_diff\*(C'\fR
+.RE
+.RS 4
+.RE
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+When the code you're testing returns multiple lines, records or data
+structures and they're just plain wrong, an equivalent to the Unix
+\&\f(CW\*(C`diff\*(C'\fR utility may be just what's needed. Here's output from an
+example test script that checks two text documents and then two
+(trivial) data structures:
+.PP
+.Vb 10
+\& t/99example....1..3
+\& not ok 1 \- differences in text
+\& # Failed test ((eval 2) at line 14)
+\& # +\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\& # | Ln|Got |Expected |
+\& # +\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\& # | 1|this is line 1 |this is line 1 |
+\& # * 2|this is line 2 |this is line b *
+\& # | 3|this is line 3 |this is line 3 |
+\& # +\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\& not ok 2 \- differences in whitespace
+\& # Failed test ((eval 2) at line 20)
+\& # +\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\& # | Ln|Got |Expected |
+\& # +\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\& # | 1| indented | indented |
+\& # * 2| indented |\etindented *
+\& # | 3| indented | indented |
+\& # +\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\& not ok 3
+\& # Failed test ((eval 2) at line 22)
+\& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\& # | Elt|Got |Expected |
+\& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\& # * 0|bless( [ |[ *
+\& # * 1| \*(AqMove along, nothing to see here\*(Aq | \*(AqDry, humorless message\*(Aq *
+\& # * 2|], \*(AqTest::Builder\*(Aq ) |] *
+\& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\& # Looks like you failed 3 tests of 3.
+.Ve
+.PP
+eq_or_diff_...() compares two strings or (limited) data structures and
+either emits an ok indication or a side-by-side diff. Test::Differences
+is designed to be used with Test.pm and with Test::Simple, Test::More,
+and other Test::Builder based testing modules. As the \s-1SYNOPSIS\s0 shows,
+another testing module must be used as the basis for your test suite.
+.PP
+These functions assume that you are presenting it with \*(L"flat\*(R" records,
+looking like:
+.PP
+.Vb 4
+\& \- scalars composed of record\-per\-line
+\& \- arrays of scalars,
+\& \- arrays of arrays of scalars,
+\& \- arrays of hashes containing only scalars
+.Ve
+.PP
+All of these are flattened in to single strings which are then compared
+for differences. Differently data structures can be compared, as long
+as they flatten identically.
+.PP
+All other data structures are run through Data::Dumper first. This is a
+bit dangerous, as some versions of perl shipped with Data::Dumpers that
+could do the oddest things with unexpected, like core dump. Only as of
+5.8.0 does Data::Dumper sort hash keys, which is necessary for \s-1HASH\s0
+dumps to be fully predictable. This will be changed when this bites
+somebody or I get some free time.
+.PP
+\&\f(CW\*(C`eq_or_diff()\*(C'\fR starts counting records at 0 unless you pass it two text
+strings:
+.PP
+.Vb 3
+\& eq_or_diff $a, $b; ## First line is line number 1
+\& eq_or_diff @a, @b; ## First element is element 0
+\& eq_or_diff $a, @b; ## First line/element is element 0
+.Ve
+.PP
+If you want to force a first record number of 0, use \f(CW\*(C`eq_or_diff_data\*(C'\fR. If
+you want to force a first record number of 1, use \f(CW\*(C`eq_or_diff_text\*(C'\fR. I chose
+this over passing in an options hash because it's clearer and simpler this way.
+\&\s-1YMMV\s0.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+There is currently only one option: \*(L"context\*(R". This allows you to
+control the amount of context shown:
+.PP
+.Vb 1
+\& eq_or_diff $got, $expected, $name, { context => 50000 };
+.Ve
+.PP
+will show you lots and lots of context. Normally, \fIeq_or_diff()\fR uses
+some heuristics to determine whether to show 3 lines of context (like
+a normal unified diff) or 25 lines.
+.SH "DIFF STYLES"
+.IX Header "DIFF STYLES"
+For extremely long strings, a table diff can wrap on your screen and be hard
+to read. If you are comfortable with different diff formats, you can switch
+to a format more suitable for your data. These are the four formats supported
+by the Text::Diff module and are set with the following functions:
+.IP "\(bu" 4
+\&\f(CW\*(C`table_diff\*(C'\fR (the default)
+.IP "\(bu" 4
+\&\f(CW\*(C`unified_diff\*(C'\fR
+.IP "\(bu" 4
+\&\f(CW\*(C`oldstyle_diff\*(C'\fR
+.IP "\(bu" 4
+\&\f(CW\*(C`context_diff\*(C'\fR
+.PP
+You can run the following to understand the different diff output styles:
+.PP
+.Vb 2
+\& use Test::More \*(Aqno_plan\*(Aq;
+\& use Test::Differences;
+\&
+\& my $long_string = join \*(Aq\*(Aq => 1..40;
+\&
+\& TODO: {
+\& local $TODO = \*(AqTesting diff styles\*(Aq;
+\&
+\& # this is the default and does not need to explicitly set unless you need
+\& # to reset it back from another diff type
+\& table_diff;
+\& eq_or_diff $long_string, "\-$long_string", \*(Aqtable diff\*(Aq;
+\&
+\& unified_diff;
+\& eq_or_diff $long_string, "\-$long_string", \*(Aqunified diff\*(Aq;
+\&
+\& context_diff;
+\& eq_or_diff $long_string, "\-$long_string", \*(Aqcontext diff\*(Aq;
+\&
+\& oldstyle_diff;
+\& eq_or_diff $long_string, "\-$long_string", \*(Aqoldstyle diff\*(Aq;
+\& }
+.Ve
+.SH "DEPLOYING"
+.IX Header "DEPLOYING"
+There are several basic ways of deploying Test::Differences requiring more or less
+labor by you or your users.
+.IP "\(bu" 4
+Fallback to \f(CW\*(C`is_deeply\*(C'\fR.
+.Sp
+This is your best option if you want this module to be optional.
+.Sp
+.Vb 6
+\& use Test::More;
+\& BEGIN {
+\& if (!eval q{ use Test::Differences; 1 }) {
+\& *eq_or_diff = \e&is_deeply;
+\& }
+\& }
+.Ve
+.IP "\(bu" 4
+
+.Sp
+.Vb 1
+\& eval "use Test::Differences";
+.Ve
+.Sp
+If you want to detect the presence of Test::Differences on the fly, something
+like the following code might do the trick for you:
+.Sp
+.Vb 1
+\& use Test qw( !ok ); ## get all syms *except* ok
+\&
+\& eval "use Test::Differences";
+\& use Data::Dumper;
+\&
+\& sub ok {
+\& goto &eq_or_diff if defined &eq_or_diff && @_ > 1;
+\& @_ = map ref $_ ? Dumper( @_ ) : $_, @_;
+\& goto Test::&ok;
+\& }
+\&
+\& plan tests => 1;
+\&
+\& ok "a", "b";
+.Ve
+.IP "\(bu" 4
+\&\s-1PREREQ_PM\s0 => { .... \*(L"Test::Differences\*(R" => 0, ... }
+.Sp
+This method will let \s-1CPAN\s0 and \s-1CPANPLUS\s0 users download it automatically. It
+will discomfit those users who choose/have to download all packages manually.
+.IP "\(bu" 4
+t/lib/Test/Differences.pm, t/lib/Text/Diff.pm, ...
+.Sp
+By placing Test::Differences and its prerequisites in the t/lib directory, you
+avoid forcing your users to download the Test::Differences manually if they
+aren't using \s-1CPAN\s0 or \s-1CPANPLUS\s0.
+.Sp
+If you put a \f(CW\*(C`use lib "t/lib";\*(C'\fR in the top of each test suite before the
+\&\f(CW\*(C`use Test::Differences;\*(C'\fR, \f(CW\*(C`make test\*(C'\fR should work well.
+.Sp
+You might want to check once in a while for new Test::Differences releases
+if you do this.
+.SH "LIMITATIONS"
+.IX Header "LIMITATIONS"
+.ie n .SS """Test"" or ""Test::More"""
+.el .SS "\f(CWTest\fP or \f(CWTest::More\fP"
+.IX Subsection "Test or Test::More"
+This module \*(L"mixes in\*(R" with Test.pm or any of the test libraries based on
+Test::Builder (Test::Simple, Test::More, etc). It does this by peeking to see
+whether Test.pm or Test/Builder.pm is in \f(CW%INC\fR, so if you are not using one of
+those, it will print a warning and play dumb by not emitting test numbers (or
+incrementing them). If you are using one of these, it should interoperate
+nicely.
+.SS "Exporting"
+.IX Subsection "Exporting"
+Exports all 3 functions by default (and by design). Use
+.PP
+.Vb 1
+\& use Test::Differences ();
+.Ve
+.PP
+to suppress this behavior if you don't like the namespace pollution.
+.PP
+This module will not override functions like \fIok()\fR, \fIis()\fR, \fIis_deeply()\fR, etc. If
+it did, then you could \f(CW\*(C`eval "use Test::Differences qw( is_deeply );"\*(C'\fR to get
+automatic upgrading to diffing behaviors without the \f(CW\*(C`sub my_ok\*(C'\fR shown above.
+Test::Differences intentionally does not provide this behavior because this
+would mean that Test::Differences would need to emulate every popular test
+module out there, which would require far more coding and maintenance that I'm
+willing to do. Use the eval and my_ok deployment shown above if you want some
+level of automation.
+.SS "Unicode"
+.IX Subsection "Unicode"
+Perls before 5.6.0 don't support characters > 255 at all, and 5.6.0
+seems broken. This means that you might get odd results using perl5.6.0
+with unicode strings.
+.ie n .SS """Data::Dumper"" and older Perls."
+.el .SS "\f(CWData::Dumper\fP and older Perls."
+.IX Subsection "Data::Dumper and older Perls."
+Relies on Data::Dumper (for now), which, prior to perl5.8, will not always
+report hashes in the same order. \f(CW $Data::Dumper::SortKeys \fR \fIis\fR set to 1,
+so on more recent versions of Data::Dumper, this should not occur. Check \s-1CPAN\s0
+to see if it's been peeled out of the main perl distribution and backported.
+Reported by Ilya Martynov <ilya@martynov.org>, although the SortKeys \*(L"future
+perfect\*(R" workaround has been set in anticipation of a new Data::Dumper for a
+while. Note that the two hashes should report the same here:
+.PP
+.Vb 10
+\& not ok 5
+\& # Failed test (t/ctrl/05\-home.t at line 51)
+\& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\& # | Elt|Got | Elt|Expected |
+\& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\& # | 0|{ | 0|{ |
+\& # | 1| \*(Aqpassword\*(Aq => \*(Aq\*(Aq, | 1| \*(Aqpassword\*(Aq => \*(Aq\*(Aq, |
+\& # * 2| \*(Aqmethod\*(Aq => \*(Aqlogin\*(Aq, * | |
+\& # | 3| \*(Aqctrl\*(Aq => \*(Aqhome\*(Aq, | 2| \*(Aqctrl\*(Aq => \*(Aqhome\*(Aq, |
+\& # | | * 3| \*(Aqmethod\*(Aq => \*(Aqlogin\*(Aq, *
+\& # | 4| \*(Aqemail\*(Aq => \*(Aqtest\*(Aq | 4| \*(Aqemail\*(Aq => \*(Aqtest\*(Aq |
+\& # | 5|} | 5|} |
+\& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+.Ve
+.PP
+Data::Dumper also overlooks the difference between
+.PP
+.Vb 2
+\& $a[0] = \e$a[1];
+\& $a[1] = \e$a[0]; # $a[0] = \e$a[1]
+.Ve
+.PP
+and
+.PP
+.Vb 3
+\& $x = \e$y;
+\& $y = \e$x;
+\& @a = ( $x, $y ); # $a[0] = \e$y, not \e$a[1]
+.Ve
+.PP
+The former involves two scalars, the latter 4: \f(CW$x\fR, \f(CW$y\fR, and \f(CW@a\fR[0,1].
+This was carefully explained to me in words of two syllables or less by
+Yves Orton <demerphq@hotmail.com>. The plan to address this is to allow
+you to select Data::Denter or some other module of your choice as an
+option.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+.Vb 1
+\& Barrie Slaymaker <barries@slaysys.com>
+.Ve
+.SH "MAINTAINER"
+.IX Header "MAINTAINER"
+.Vb 1
+\& Curtis "Ovid" Poe <ovid@cpan.org>
+.Ve
+.SH "LICENSE"
+.IX Header "LICENSE"
+Copyright 2001\-2008 Barrie Slaymaker, All Rights Reserved.
+.PP
+You may use this software under the terms of the \s-1GNU\s0 public license, any
+version, or the Artistic license.
projects / catagits/Gitalist.git / blobdiff