view release on metacpan or  search on metacpan

lib/Directory/Diff.pod  view on Meta::CPAN

they are different. It is callback-based and takes actions only if
required.

=head1 FUNCTIONS

The main function of this module is L</directory_diff>. The other
functions listed here are helper functions, but these can be exported
on request.

=head2 directory_diff

     directory_diff ("dir1", "dir2", 
                     {dir1_only => \&dir1_only,
                      diff => \& diff});

Given two directories F<dir1> and F<dir2>, this calls back a
user-supplied routine for each of three cases:

=over

=item A file is only in the first directory

In this case a callback specified by C<dir1_only> is called once

     &{$third_arg->{dir1_only}} ($third_arg->{data}, "dir1", $file);

for each file C<$file> which is in F<dir1> but not in F<dir2>,
including files in subdirectories.

=item A file is only in the second directory

In this case a callback specified by C<dir2_only> is called once

     &{$third_arg->{dir2_only}} ($third_arg->{data}, "dir2", $file);

for each file C<$file> which is in F<dir2> but not in F<dir1>,
including files in subdirectories.

=item A file with the same name but different contents is in both directories

In this case a callback specified by C<diff> is called once

     &{$third_arg->{diff}} ($third_arg->{data}, "dir1", "dir2", $file);

for each file name C<$file> which is in both F<dir1> and in F<dir2>,
including files in subdirectories.

=back

The first argument to each of the callback functions is specified by
C<data>. The second argument to C<dir1_only> and C<dir2_only> is the
directory's name. The third argument is the file name, which includes
the subdirectory part. The second and third arguments to C<diff> are
the two directories, and the fourth argument is the file name
including the subdirectory part.

If the user does not supply a callback, no action is taken, even if a
file is found.

The routine does not return a meaningful value. It does not check the
return values of the callbacks. Therefore if it is necessary to stop
midway, the user must use something like C<eval { }> and C<die>.

A fourth argument, if set to any true value, causes directory_diff to
print messages about what it finds and what it does.

=head2 ls_dir

     my %ls = ls_dir ("dir");

C<ls_dir> makes a hash containing a true value for each file and
directory which is found under the directory given as the first
argument.

If a second argument with a true value is set, it prints debugging
messages. For example

     my %ls = ls_dir ("dir", 1);

As a debugging measure it halts execution if its return value is
ignored.

=head2 get_only

     my %only = get_only (\%dir1, \%dir2);

Given two hashes containing true values for each file or directory
under two directories, return a hash containing true values for the
files and directories which are in the first directory hash but not in
the second directory hash.

For example, if

     %dir1 = ("file" => 1, "dir/" => 1, "dir/file" => 1);

and 

     %dir2 = ("dir/" => 1, "dir2/" => 1);

C<get_only> returns

     %only = ("file" => 1, "dir/file" => 1);

A third parameter for debugging makes the module print messages
on what is found if set to a true value, for example,

     my %only = get_only (\%dir1, \%dir2, 1);

=head2 get_diff

     my %diff = get_diff ("dir1", \%dir1_ls, "dir2", \%dir2_ls);

Get a list of files which are in both C<dir1> and C<dir2>, but which
are different. This uses L<File::Compare> to test the files for
differences. It searches subdirectories. Usually the hashes
C<%dir1_ls> and C<%dir2_ls> are those output by L</ls_dir>.

=head1 SEE ALSO

=head2 CPAN modules