NAME

       File::Listing - Parse directory listing

VERSION

       version 6.15

SYNOPSIS

        use File::Listing qw(parse_dir);
        $ENV{LANG} = "C";  # dates in non-English locales not supported
        foreach my $file (parse_dir(`ls -l`)) {
            my ($name, $type, $size, $mtime, $mode) = @$file;
            next if $type ne 'f'; # plain file
            #...
        }

        # directory listing can also be read from a file
        open my $listing, "zcat ls-lR.gz|";
        $dir = parse_dir($listing, '+0000');

DESCRIPTION

       This module exports a single function called "parse_dir", which can be used to parse
       directory listings.

FUNCTIONS

   parse_dir
        my $dir = parse_dir( $listing );
        my $dir = parse_dir( $listing, $time_zone );
        my $dir = parse_dir( $listing, $time_zone, $type );
        my $dir = parse_dir( $listing, $time_zone, $type, $error );
        my @files = parse_dir( $listing );
        my @files = parse_dir( $listing, $time_zone );
        my @files = parse_dir( $listing, $time_zone, $type );
        my @files = parse_dir( $listing, $time_zone, $type, $error );

       The first parameter ($listing) is the directory listing to parse.  It can be a scalar, a
       reference to an array of directory lines or a glob representing a filehandle to read the
       directory listing from.

       The second parameter ($time_zone) is the time zone to use when parsing time stamps in the
       listing. If this value is undefined, then the local time zone is assumed.

       The third parameter ($type) is the type of listing to assume.  Currently supported formats
       are 'unix', 'apache' and 'dosftp'. The default value is 'unix'. Ideally, the listing type
       should be determined automatically.

       The fourth parameter ($error) specifies how unparseable lines should be treated. Values
       can be 'ignore', 'warn' or a code reference.  Warn means that the perl warn() function
       will be called.  If a code reference is passed, then this routine will be called and the
       return value from it will be incorporated in the listing.  The default is 'ignore'.

       Only the first parameter is mandatory.

        # list context
        foreach my $file (parse_dir($listing)) {
            my($name, $type, $size, $mtime, $mode) = @$file;
        }

        # scalar context
        my $dir = parse_dir($listing);
        foreach my $file (@$dir) {
            my($name, $type, $size, $mtime, $mode) = @$file;
        }

       The return value from parse_dir() is a list of directory entries.  In a scalar context the
       return value is a reference to the list.  The directory entries are represented by an
       array consisting of:

       name
           The name of the file.

       type
           One of: "f" file, "d" directory, "l" symlink, "?" unknown.

       size
           The size of the file.

       time
           The number of seconds since January 1, 1970.

       mode
           Bitmask a la the mode returned by "stat".

SEE ALSO

       File::Listing::Ftpcopy
           Provides the same interface but uses XS and the parser implementation from "ftpcopy".

AUTHOR

       Original author: Gisle Aas

       Current maintainer: Graham Ollis <plicease@cpan.org>

       Contributors:

       Adam Kennedy

       Adam Sjogren

       Alex Kapranoff

       Alexey Tourbin

       Andreas J. Koenig

       Bill Mann

       Bron Gondwana

       DAVIDRW

       Daniel Hedlund

       David E. Wheeler

       David Steinbrunner

       Erik Esterer

       FWILES

       Father Chrysostomos

       Gavin Peters

       Graeme Thompson

       Hans-H. Froehlich

       Ian Kilgore

       Jacob J

       Mark Stosberg

       Mike Schilli

       Ondrej Hanak

       Peter John Acklam

       Peter Rabbitson

       Robert Stone

       Rolf Grossmann

       Sean M. Burke

       Simon Legner

       Slaven Rezic

       Spiros Denaxas

       Steve Hay

       Todd Lipcon

       Tom Hukins

       Tony Finch

       Toru Yamaguchi

       Ville Skyttä

       Yuri Karaban

       Zefram

       amire80

       jefflee

       john9art

       mschilli

       murphy

       phrstbrn

       ruff

       sasao

       uid39246

COPYRIGHT AND LICENSE

       This software is copyright (c) 1996-2020 by Gisle Aas.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.