.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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::File::Contents 3pm"
.TH Test::File::Contents 3pm "2013-08-11" "perl v5.14.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"
.IX Header "Name"
Test::File::Contents \- Test routines for examining the contents of files
.SH "Synopsis"
.IX Header "Synopsis"
.Vb 1
\&  use Test::File::Contents;
\&
\&  file_contents_eq         $file,  $string,  $description;
\&  file_contents_eq_or_diff $file,  $string,  $description;
\&  file_contents_like       $file,  qr/foo/,  $description;
\&  file_md5sum_is           $file,  $md5sum,  $description;
\&  files_eq                 $file1, $file2,   $description;
\&  files_eq_or_diff         $file1, $file2,   $description;
.Ve
.SH "Description"
.IX Header "Description"
Got an app that generates files? Then you need to test those files to make
sure that their contents are correct. This module makes that easy. Use its
test functions to make sure that the contents of files are exactly what you
expect them to be.
.SH "Interface"
.IX Header "Interface"
.SS "Options"
.IX Subsection "Options"
These test functions take an optional hash reference of options which may
include one or more of these options:
.ie n .IP """encoding""" 4
.el .IP "\f(CWencoding\fR" 4
.IX Item "encoding"
The encoding in which the file is encoded. This will be used in an I/O layer
to read in the file, so that it can be properly decoded to Perl's internal
representation. Examples include \f(CW\*(C`UTF\-8\*(C'\fR, \f(CW\*(C`iso\-8859\-3\*(C'\fR, and \f(CW\*(C`cp1252\*(C'\fR. See
Encode::Supported for a list of supported encodings. May also be specified
as a layer, such as \*(L":utf8\*(R" or \*(L":raw\*(R". See perlio for a complete list of
layers.
.Sp
Note that it's important to specify the encoding if you have non-ASCII
characters in your file. And the value to be compared against (the string
argument to \f(CW\*(C`file_contents_eq()\*(C'\fR and the regular expression argument to
\&\f(CW\*(C`file_contents_like()\*(C'\fR, for example, must be decoded to Perl's internal
form. The simplest way to do so use to put
.Sp
.Vb 1
\&  use utf8;
.Ve
.Sp
In your test file and write it all in \f(CW\*(C`UTF\-8\*(C'\fR. For example:
.Sp
.Vb 3
\&  use utf8;
\&  use Test::More tests => 1;
\&  use Test::File::Contents;
\&
\&  file_contents_eq(\*(Aqutf8.txt\*(Aq,   \*(Aqa\*oa\*oa\*o\*(Aq, { encoding => \*(AqUTF\-8\*(Aq });
\&  file_contents_eq(\*(Aqlatin1.txt\*(Aq, \*(Aqa\*oa\*oa\*o\*(Aq, { encoding => \*(AqUTF\-8\*(Aq });
.Ve
.ie n .IP """style""" 4
.el .IP "\f(CWstyle\fR" 4
.IX Item "style"
The style of diff to output in the diagnostics in the case of a failure
in \f(CW\*(C`file_contents_eq_or_diff\*(C'\fR. The possible values are:
.RS 4
.IP "Unified" 4
.IX Item "Unified"
.PD 0
.IP "Context" 4
.IX Item "Context"
.IP "OldStyle" 4
.IX Item "OldStyle"
.IP "Table" 4
.IX Item "Table"
.RE
.RS 4
.RE
.ie n .IP """context""" 4
.el .IP "\f(CWcontext\fR" 4
.IX Item "context"
.PD
Determines the amount of context displayed in diagnostic diff output. If you
need to seem more of the area surrounding different lines, pass this option to
determine how many more links you'd like to see.
.SS "Test Functions"
.IX Subsection "Test Functions"
\fIfile_contents_eq\fR
.IX Subsection "file_contents_eq"
.PP
.Vb 3
\&  file_contents_eq $file, $string, $description;
\&  file_contents_eq $file, $string, { encoding => \*(AqUTF\-8\*(Aq };
\&  file_contents_eq $file, $string, { encoding => \*(Aq:bytes\*(Aq }, $description;
.Ve
.PP
Checks that the file's contents are equal to a string. Pass in a Unix-style
file name and it will be converted for the local file system. Supported
options:
.ie n .IP """encoding""" 4
.el .IP "\f(CWencoding\fR" 4
.IX Item "encoding"
.PP
The old name for this function, \f(CW\*(C`file_contents_is\*(C'\fR, remains as an
alias.
.PP
\fIfile_contents_eq_or_diff\fR
.IX Subsection "file_contents_eq_or_diff"
.PP
.Vb 3
\&  file_contents_eq_or_diff $file, $string, $description;
\&  file_contents_eq_or_diff $file, $string, { encoding => \*(AqUTF\-8\*(Aq };
\&  file_contents_eq_or_diff $file, $string, { style    => \*(Aqcontext\*(Aq }, $description;
.Ve
.PP
Like \f(CW\*(C`file_contents_eq()\*(C'\fR, only in the event of failure, the diagnostics will
contain a diff instead of the full contents of the file. This can make it
easier to test the contents of very large text files, and where only a subset
of the lines are different. Supported options:
.ie n .IP """encoding""" 4
.el .IP "\f(CWencoding\fR" 4
.IX Item "encoding"
.PD 0
.ie n .IP """style""" 4
.el .IP "\f(CWstyle\fR" 4
.IX Item "style"
.ie n .IP """context""" 4
.el .IP "\f(CWcontext\fR" 4
.IX Item "context"
.PD
.PP
\fIfile_contents_ne\fR
.IX Subsection "file_contents_ne"
.PP
.Vb 3
\&  file_contents_ne $file, $string, $description;
\&  file_contents_ne $file, $string, { encoding => \*(AqUTF\-8\*(Aq };
\&  file_contents_ne $file, $string, { encoding => \*(Aq:bytes\*(Aq }, $description;
.Ve
.PP
Checks that the file's contents do not equal a string. Pass in a Unix-style
file name and it will be converted for the local file system. Supported
options:
.ie n .IP """encoding""" 4
.el .IP "\f(CWencoding\fR" 4
.IX Item "encoding"
.PP
The old name for this function, \f(CW\*(C`file_contents_isnt\*(C'\fR, remains as an alias.
.PP
\fIfile_contents_like\fR
.IX Subsection "file_contents_like"
.PP
.Vb 3
\&  file_contents_like $file, qr/foo/, $description;
\&  file_contents_like $file, qr/foo/, { encoding => \*(AqUTF\-8\*(Aq };
\&  file_contents_like $file, qr/foo/, { encoding => \*(Aq:bytes\*(Aq }, $description;
.Ve
.PP
Checks that the contents of a file match a regular expression. The regular
expression must be passed as a regular expression object created by \f(CW\*(C`qr//\*(C'\fR.
Supported options:
.ie n .IP """encoding""" 4
.el .IP "\f(CWencoding\fR" 4
.IX Item "encoding"
.PP
\fIfile_contents_unlike\fR
.IX Subsection "file_contents_unlike"
.PP
.Vb 3
\&  file_contents_unlike $file, qr/foo/, $description;
\&  file_contents_unlike $file, qr/foo/, { encoding => \*(AqUTF\-8\*(Aq };
\&  file_contents_unlike $file, qr/foo/, { encoding => \*(Aq:bytes\*(Aq }, $description;
.Ve
.PP
Checks that the contents of a file \fIdo not\fR match a regular expression. The
regular expression must be passed as a regular expression object created by
\&\f(CW\*(C`qr//\*(C'\fR. Supported options:
.ie n .IP """encoding""" 4
.el .IP "\f(CWencoding\fR" 4
.IX Item "encoding"
.PP
\fIfile_md5sum_is\fR
.IX Subsection "file_md5sum_is"
.PP
.Vb 3
\&  file_md5sum_is $file, $md5sum, $description;
\&  file_md5sum_is $file, $md5sum, { encoding => \*(AqUTF\-8\*(Aq };
\&  file_md5sum_is $file, $md5sum, { encoding => \*(Aq:bytes\*(Aq }, $description;
.Ve
.PP
Checks whether a file matches a given \s-1MD5\s0 checksum. The checksum should be
provided as a hex string, for example, \f(CW\*(C`6df23dc03f9b54cc38a0fc1483df6e21\*(C'\fR.
Pass in a Unix-style file name and it will be converted for the local file
system. Supported options:
.ie n .IP """encoding""" 4
.el .IP "\f(CWencoding\fR" 4
.IX Item "encoding"
Probably not useful unless left unset or set to \f(CW\*(C`:raw\*(C'\fR.
.PP
The old name for this function, \f(CW\*(C`file_md5sum\*(C'\fR, remains as an alias.
.PP
\fIfiles_eq\fR
.IX Subsection "files_eq"
.PP
.Vb 3
\&  files_eq $file1, $file2, $description;
\&  files_eq $file1, $file2, { encoding => \*(AqUTF\-8\*(Aq };
\&  files_eq $file1, $file2, { encoding => \*(Aq:bytes\*(Aq }, $description;
.Ve
.PP
Tests that the contents of two files are the same. Pass in a Unix-style file
name and it will be converted for the local file system. Supported
options:
.ie n .IP """encoding""" 4
.el .IP "\f(CWencoding\fR" 4
.IX Item "encoding"
.PP
The old name for this function, \f(CW\*(C`file_contents_identical\*(C'\fR, remains as an
alias.
.PP
\fIfiles_eq_or_diff\fR
.IX Subsection "files_eq_or_diff"
.PP
.Vb 3
\&  files_eq_or_diff $file1, $file2, $description;
\&  files_eq_or_diff $file1, $file2, { encoding => \*(AqUTF\-8\*(Aq };
\&  files_eq_or_diff $file1, $file2, { style    => \*(Aqcontext\*(Aq }, $description;
.Ve
.PP
Like \f(CW\*(C`files_eq()\*(C'\fR, this function tests that the contents of two files are the
same. Unlike \f(CW\*(C`files_eq()\*(C'\fR, on failure this function outputs a diff of the two
files in the diagnostics. Supported options:
.ie n .IP """encoding""" 4
.el .IP "\f(CWencoding\fR" 4
.IX Item "encoding"
.PD 0
.ie n .IP """style""" 4
.el .IP "\f(CWstyle\fR" 4
.IX Item "style"
.ie n .IP """context""" 4
.el .IP "\f(CWcontext\fR" 4
.IX Item "context"
.PD
.SH "Authors"
.IX Header "Authors"
.IP "\(bu" 4
Kirrily Robert <skud@cpan.org>
.IP "\(bu" 4
David E. Wheeler <david@kineticode.com>
.SH "Support"
.IX Header "Support"
This module is stored in an open GitHub
repository <http://github.com/theory/test-file-contents/tree/>. Feel free to
fork and contribute!
.PP
Please file bug reports via GitHub
Issues <http://github.com/theory/test-file-contents/issues/> or by sending mail to
bug\-Test\-File\-Contents@rt.cpan.org <mailto:bug-Test-File-Contents@rt.cpan.org>.
.SH "Copyright and License"
.IX Header "Copyright and License"
Copyright (c) 2004\-2007 Kirrily Robert. Some Rights Reserved.
Copyright (c) 2007\-2011 David E. Wheeler. Some Rights Reserved.
.PP
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.