File::is - file is older? oldest? is newer? newest? similar? the same?

File-is documentation Contained in the File-is distribution.

Index

Code Index:

NAME

Top

File::is - file is older? oldest? is newer? newest? similar? the same?

SYNOPSIS

Top

    use File::is;

    # return if F<file1> is newer than F<file2> or F<file3>.
    return
        if File::is->newer('file1', 'file2', 'file3');

    # do something if F<path1/file1> is older than F<file2> or F<path3/file3>.
    do_some_work()
        if File::is->older([ 'path1', 'file1'], 'file2', [ 'path3', 'file3' ]);

DESCRIPTION

Top

This module is a result of /me not wanting to write:

    if ($(stat('filename'))[9] < $(stat('tmp/other-filename'))[9]) { do_someting(); };

Instead I wrote a module with ~80 lines of code and ~90 lines of tests for it... So how is the module different from the above if? Should be reusable, has more functionality, should be clear from the code it self what the condition is doing and was fun to play with it. Another advantage is that the file names can be passed as array refs. In this case catfile in File::Spec is used to construct the filename. The resulting code is:

    if (File::is->older('filename', [ 'tmp', 'other-filename' ])) { do_something(); };

FUNCTIONS

Top

newer($primary_filename, $other_filename, $other_filename2, ...)

Returns true/false if the $primary_filename is newer (has modification time-stamp recent) then any of the rest passed as argument.

newest($primary_filename, $other_filename, $other_filename2, ...)

Returns true/false if the $primary_filename is newest (has the biggest modification time-stamp) compared to the rest of the passed filenames.

older($primary_filename, $other_filename, $other_filename2, ...)

Returns true/false if the $primary_filename is older (has the later modification time-stamp) then any of the rest passed as argument.

oldest($primary_filename, $other_filename, $other_filename2, ...)

Returns true/false if the $primary_filename is oldest (has the latest modification time-stamp) compared to the rest of the passed filenames.

similar($primary_filename, $other_filename, $other_filename2, ...)

Returns true/false if the $primary_filename has the same size and modification time-stamp than any of the rest of the passed filenames.

thesame($primary_filename, $other_filename, $other_filename2, ...)

Returns true/false if the $primary_filename has the same inode and dev (is hard link) to any of the rest of the passed filenames.

NOTE: see http://perlmonks.org/?node_id=859612, File::Same

bigger($primary_filename, $other_filename, $other_filename2, ...)

Returns true/false if the $primary_filename is bigger (has the bigger size) then any of the rest passed as argument.

biggest($primary_filename, $other_filename, $other_filename2, ...)

Returns true/false if the $primary_filename is biggest (has the biggest size) compared to the rest of the passed filenames.

smaller($primary_filename, $other_filename, $other_filename2, ...)

Returns true/false if the $primary_filename is smaller (has the smaller size) then any of the rest passed as argument.

smallest($primary_filename, $other_filename, $other_filename2, ...)

Returns true/false if the $primary_filename is smallest (has the smallest size) compared to the rest of the passed filenames.

INTERNALS

Top

Call/use at your own risk ;-)

_construct_filename()

Accepts one or more arguments. It passes them to <File::Spec-catfile()>> dereferencing the array if one argument array ref is passed.

Example:

    _construct_filename('file')               => 'file'
    _construct_filename([ 'folder', 'file' ]) => File::Spec->catfile('folder', 'file');
    _construct_filename('folder', 'file')     => File::Spec->catfile('folder', 'file');

This function is called on every argument passed to cmp methods (newer, smaller, older, ...).

_cmp_stat($class, $return_value_if_match, $cmp_function, $primary_filename, $other_filename, $other_filename2, ...)

This function is called by all of the public newer(), smaller(), older(), ... methods do loop through files and do some cmp on them.

SEE ALSO

Top

http://perldoc.perl.org/functions/stat.html

AUTHOR

Top

Jozef Kutej, <jkutej at cpan.org>

CONTRIBUTORS

Top

The following people have contributed to the File::is by committing their code, sending patches, reporting bugs, asking questions, suggesting useful advises, nitpicking, chatting on IRC or commenting on my blog (in no particular order):

    Ronald Fischer

BUGS

Top

Please report any bugs or feature requests to bug-file-is at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-is. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

Top

You can find documentation for this module with the perldoc command.

    perldoc File::is

You can also look for information at:

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-is

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/File-is

* CPAN Ratings

http://cpanratings.perl.org/d/File-is

* Search CPAN

http://search.cpan.org/dist/File-is

LICENSE AND COPYRIGHT

Top

Copyright 2010 jkutej@cpan.org

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

File-is documentation Contained in the File-is distribution. 
package File::is;


use warnings;
use strict;

our $VERSION = '0.03';

use Carp 'confess';
use File::Spec;

#my $stat_mode    = 2;
#my $stat_nlink   = 3;
#my $stat_uid     = 4;
#my $stat_gid     = 5;
#my $stat_rdev    = 6;
#my $stat_atime   = 8;
#my $stat_ctime   = 10;
#my $stat_blksize = 11;
#my $stat_blocks  = 12;

my $stat_dev   = 0;
my $stat_ino   = 1;
my $stat_size  = 7;
my $stat_mtime = 9;


sub newer {
    return shift->_cmp_stat(1, sub { $_[0]->[$stat_mtime] > $_[1]->[$stat_mtime] }, @_);
}

sub newest {
    return shift->_cmp_stat(0, sub { $_[0]->[$stat_mtime] <= $_[1]->[$stat_mtime] }, @_);
}

sub older {
    return shift->_cmp_stat(1, sub { $_[0]->[$stat_mtime] < $_[1]->[$stat_mtime] }, @_);
}

sub oldest {
    return shift->_cmp_stat(0, sub { $_[0]->[$stat_mtime] >= $_[1]->[$stat_mtime] }, @_);
}

sub similar {
    return shift->_cmp_stat(
        1,
        sub {
            $_[0]->[$stat_size] == $_[1]->[$stat_size]
              and $_[0]->[$stat_mtime] == $_[1]->[$stat_mtime];
        },
        @_
    );
}

sub thesame {
    confess 'unsupported on MSWin32 (see http://perlmonks.org/?node_id=859612)'
        if $^O eq 'MSWin32';
    
    return shift->_cmp_stat(1, sub {
        ($_[0]->[$stat_ino] == $_[1]->[$stat_ino])
        && ($_[0]->[$stat_dev] == $_[1]->[$stat_dev])
    }, @_);
}

sub bigger {
    return shift->_cmp_stat(1, sub { $_[0]->[$stat_size] > $_[1]->[$stat_size] }, @_);
}

sub biggest {
    return shift->_cmp_stat(0, sub { $_[0]->[$stat_size] <= $_[1]->[$stat_size] }, @_);
}

sub smaller {
    return shift->_cmp_stat(1, sub { $_[0]->[$stat_size] < $_[1]->[$stat_size] }, @_);
}

sub smallest {
    return shift->_cmp_stat(0, sub { $_[0]->[$stat_size] >= $_[1]->[$stat_size] }, @_);
}


sub _construct_filename {
    confess 'need at least one argument'
        if @_ == 0;
    
    return File::Spec->catfile(@{$_[0]})
        if ((@_ == 1) and (ref $_[0] eq 'ARRAY'));
    
    return File::Spec->catfile(@_);
}


sub _cmp_stat {
    my $class    = shift;
    my $return   = shift;
    my $cmp_func = shift;
    my $file1    = _construct_filename(shift);
    my @files    = @_;
    
    my @file1_stat = stat $file1;
    confess 'file "'.$file1.'" not reachable'
        if not @file1_stat;

    foreach my $file (@files) {
        $file = _construct_filename($file);
        my @file_stat = stat $file;
        confess 'file "'.$file.'" not reachable'
            if not @file_stat;

        # return success if condition is met
        return $return
            if $cmp_func->(\@file1_stat, \@file_stat);
    }

    # no file was newer
    return not $return;
}

'sleeeeeeeeeeep';

__END__