#!/usr/bin/perl
#######################################################################
# $Id: newest,v 1.26 2010-02-27 22:12:50 dpchrist Exp $
#######################################################################
# uses:
#----------------------------------------------------------------------

use strict;
use warnings;

use constant			DEBUG => 0;

use Carp;
use Data::Dumper;
use Dpchrist::Debug		qw( :all );
use Dpchrist::File::Newest	qw( :all );
use File::Spec::Functions	qw( rel2abs );
use File::Find;
use Getopt::Long;
use Pod::Usage;

#######################################################################
# globals:
#----------------------------------------------------------------------

our $VERSION	= sprintf "%d.%03d", q$Revision: 1.26 $ =~ /(\d+)/g;

### suppress 'Name "Dpchrist::File::Newest::opt" used only once'
$Dpchrist::File::Newest::opt{-used_only_once}++;

my $opt = \%Dpchrist::File::Newest::opt;

my @getoptions_args = (
    'help|h|?'          => \$opt->{-help},
    'man'               => \$opt->{-man},
    'number|n=i'	=> \$opt->{-number},
);

#######################################################################
# main script:
#----------------------------------------------------------------------

{
    ### process command-line options:

    Getopt::Long::Configure("bundling");

    my $r = GetOptions(@getoptions_args);

    if (DEBUG && debug_enabled()) {
	$Data::Dumper::Sortkeys	= 1;
	$|			= 1;
	ddump [$opt, \@ARGV],
	    [qw(opt   *ARGV)];
    }

    confess "ERROR processing command line options"
    unless $r;

    pod2usage(-verbose => 2, -exitval => 0) if $opt->{-man};

    pod2usage(0) if $opt->{-help};

    pod2usage(1) unless @ARGV;

    
    ### get sorted list of files, oldest to newest:

    my $ra = newest(@ARGV);


    ### print the newest ones:

    print(pop @$ra, "\n") while @$ra && $opt->{-number}--;
}

#######################################################################

=head1 NAME

newest - find newest files


=head1 SYNOPSIS

    $ newest [OPTION...] PATH...

    --help, -h, -?      Print a brief help message
    --man               Print the manual page
    --number, -n N      Print the N newest files


=head1 DESCRIPTION

B<newest> will recursively search all files and folders given by PATH
and print the path of the newest file.


=head2 PATHS WITH SPACES

If the path(s) output by this program contain spaces,
feeding the output to another program (such as 'ls') will fail:

    2009-08-31 00:48:38 Administrator@p43400e ~
    $ newest /cygdrive/c/Documents\ and\ Settings/Administrator/My\ Documents/
    /cygdrive/c/Documents and Settings/Administrator/My Documents/.viminfo

    2009-08-31 00:48:43 Administrator@p43400e ~
    $ ll -l `newest /cygdrive/c/Documents\ and\ Settings/Administrator/My\ Documents/`
    ls: cannot access /cygdrive/c/Documents: No such file or directory
    ls: cannot access and: No such file or directory
    ls: cannot access Settings/Administrator/My: No such file or directory
    ls: cannot access Documents/.viminfo: No such file or directory

This problem does not appear to be unique to B<newest>:

    2009-08-31 00:48:51 Administrator@p43400e ~
    $ echo '/cygdrive/c/Documents\ and\ Settings/Administrator/My\ Documents/'
    /cygdrive/c/Documents\ and\ Settings/Administrator/My\ Documents/

    2009-08-31 00:49:49 Administrator@p43400e ~
    $ ls -l `echo '/cygdrive/c/Documents\ and\ Settings/Administrator/My\ Documents/'`
    ls: cannot access /cygdrive/c/Documents\: No such file or directory
    ls: cannot access and\: No such file or directory
    ls: cannot access Settings/Administrator/My\: No such file or directory
    ls: cannot access Documents/: No such file or directory


A work-around is to write a Perl one-liner
that converts spaces to nulls
and install it as an alias in .bashrc:

    alias nl2null="perl -ne 's/\n/\00/; print'"


And then use 'xargs' with the -0 option:

    2009-10-30 21:20:06 dpchrist@p43400e ~
    $ newest -n 3 /cygdrive/c/Documents\ and\ Settings/dpchrist/My\ Documents/Dp* | nl2null | xargs -0 ls -dl
    -rwxr-xr-x 1 dpchrist None 5750 Oct 30 21:20 /cygdrive/c/Documents and Settings/dpchrist/My Documents/Dpchrist-File-Newest/bin/newest
    -rw-r--r-- 1 dpchrist None   23 Oct 30 21:12 /cygdrive/c/Documents and Settings/dpchrist/My Documents/Dpchrist-File-Newest/t/CVS/Repository
    -rw-r--r-- 1 dpchrist None   44 Oct 30 21:12 /cygdrive/c/Documents and Settings/dpchrist/My Documents/Dpchrist-File-Newest/t/CVS/Root 


=head1 INSTALLATION

    This software is installed as part of Dpchrist::File::Newest.


=head1 DEPENDENCIES

    Dpchrist::File::Newest


=head1 SEE ALSO

    Dpchrist::File::Newest


=head1 AUTHOR

    David Paul Christensen  dpchrist@holgerdanske.com


=head1 COPYRIGHT AND LICENSE

Copyright 2010 by David Paul Christensen dpchrist@holgerdanske.com

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

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307,
USA.

=cut

#######################################################################
