labster/perl6-File-Compare/lib/File/Compare

NAME

File::Compare - Compare files to check for equality/difference

SYNOPSIS

	use File::Compare;
	
	if files_are_equal("file1.txt", "file2.txt")
		{ say "These are identical files"; }
	files_are_different("foo", "bar") ?? say "diff" !! say "same";


	say "we match" if files_are_equal("x.png", "y.png", chunk_size=> 4*1024*1024);
	say "OH NOES" if files_are_different("i/dont/exist", "me/neither") ~~ Failure;

DESCRIPTION

File::Compare checks to see if files have the same contents, by comparing them as byte-buffers if they are of the same size.

(head2)  files_are_equal(), files_are_different()

  The function C<files_are_equal> returns Bool::True if the files have the same contents, Bool::False if any bytes are different, and a Failure object if an error occurs.  The other function, C<files_are_different>, returns the opposite boolean values, and is mostly provided for code readability sugar.  Note that Failure Boolifies to False, so the behavior is slightly different between the two functions.

(head2)  compare_multiple_files

Another function, compare_multiple_files , will compare the contents of an array of files (passed in as any mixture of Str and IO::Path objects). It will return an array of arrays of IO::Path objects, with matching files grouped together.

(head2)  chunk_size parameter

All three functions can take an optional named parameter, chunk_size , which accepts any positive integer. This parameter tells File::Compare what size of chunks should be read from the disk at once, since the read operation is often the slowest. The default reads 8 MiB of each file at a time. A smaller value may be more useful in a memory-limited environment, or when files are most likely different. A larger value could improve performance when files are most likely the same.

DIFFERENCES FROM PERL 5 VERSION

This code returns boolean values and Failure objects instead of 1, 0, -1 for difference, equality, and failure respectively. The read chunk size is also increased four-fold because you're not really trying to run Rakudo on a 80486 processor, are you?

(head2)  Comparing Text

This Perl 6 version drops the compare_text function that was included in Perl 5. Since most text files are of managable size, consider this code, which uses Perl's native newline handling:

	C<"file1".path.open.lines eq "file2".path.open.lines>

Functions can be evaluated on this as well:

	C<foo( "old/script.p6".path.open.lines ) eq foo( "new/script.p6".path.open.lines )>

Though, you may be better off looking at a module like L<Text::Diff> instead.

TODO

Support IO objects as parameters.

AUTHOR

Brent "Labster" Laabs, 2013. Released under the same terms as Perl 6; see the LICENSE file for details.