NAME
    Path::Classy - Augmented Path::Class (fancy stuff)

SYNOPSIS
        use Path::Classy qw( file );

        my $f = file( 'my/file' );

        my $size = $f->size(); # size in bytes
        my $h_size = $f->size({ format => 'h'}); # eg. '12K'

        my $mtime = $f->mtime; # secs since epoch
        my $mtime_days = $f->mtime({ as => 'days' }); # days since epoch
        my $mtime_dt = $f->mtime({ as => 'dt' }); # as a DateTime

        my $uri = $f->uri; # URI->new( 'file://...' );

DESCRIPTION
        This module is pretty much an experience by now.
        It is quite superfluous.

    This module augments the API of Path::Class objects with a few more
    methods. The idea is: since you turned your paths into objects, why not
    take it as far as possible?

    For example, after creating a Path::Class object:

        use Path::Class qw( file );

        my $f = file( 'foo.txt' );

    there are some info you can get from the file attached to the current
    path:

        my $st = $f->stat;

    But if you want to know if it exists already or its size (preferably in
    a nice format like '1G')? With Path::Class, you have to say

        print "exists already\n" if -e $f;
        printf "size: %s\n", -s $f;
                           # $f->stat->size works too

    The filetest operators are quite nice and short. But if you want more
    consistency, you would expect methods to access this info:

        print "exists already\n" if $f->exists;
        printf "size: %s\n", $f->size;

    `Path::Classy' provides some of these missing methods. It is far
    complete, as it is a very recent code. But it may occasionally be
    useful.

    ATTENTION: `Path::Classy' does not export anything by default, while
    `Path::Class' exports 'file' and 'dir'.

METHODS
    So far, only files were contemplated with extra methods. These are
    described below.

    In the description below, `$f' is typically created with statements like

      use Path::Classy qw( file );
      $f = file( 'Path-Classy-0.001_0.tar.gz' );

    size [ equiv: -s ]
          $size = $f->size(); 
          $size = $f->size(\%options);

        Returns the file size. By the default, it returns the raw byte
        count. A 'format' option is accepted which support the following
        choices:

        h   Returns the size in a human readable format (like '12K', '1G').
            This is done by using Number::Bytes::Human.

        ''  Returns the raw byte size.

        Equivalence to a filetest expression:

          $f->size      ~~     -s $f

        Examples:

          # assume $f is a file with 24475 bytes
          $f->size() # 24475
          $f->size({ format => 'h' }) # '24K'
          $f->size({ format => '' }) # 24475

    exists [ equiv: -e ]
          $yn = $f->exists;

        Tells if the file exists or not.

        Equivalence to a filetest expression:

          $f->exists    ~~     -e $f

    mtime [ equiv: -M ]
          $mtime = $f->mtime;
          $mtime = $f->mtime(\%options);

        Returns the modification time of the file. By default, it returns
        the number of seconds from epoch (as `$f->stat->mtime' does). It
        supports options 'from' and 'as'. The option 'from' specifies the
        time from a certain reference and the possible choices are:

        'epoch'
            The time is specified since the epoch. (The epoch was at 00:00
            January 1, 1970 GMT.)

        'start'
            The time is specified since the start time of the script (as
            given by `$^T').

        The default is 'epoch'.

        The option 'as' determines how the time is returned. The supported
        choices are:

        'sec'
            The time in seconds since the reference specified by 'from'.

        'days'
            The time in days since the reference specifed by 'from'.

        'dt'
            The time as a DateTime object. It should be independent of the
            reference given by 'from'.

        The default is 'sec'.

        With this method, the equivalence to a filetest expression is not
        that nice:

          $f->mtime({ from => 'start', as => 'days' })

        is

          -( -M $f )

        because `M $f' is the script start time minus file modification time
        in days. In turn,

          $f->mtime()  ~~ $f->stat->mtime

        Examples:

          $f->mtime(); # file mod time since epoch (in secs)
          $f->mtime({ as => 'days' }); # idem (in days)
          $f->mtime({ as => 'dt' }); # file mod time as a DateTime

          $f->mtime({ from => 'epoch', as => 'days' }); # same as $f->mtime

          $f->mtime({ from => 'start' }); # file mod time since script start time (in secs)
          $f->mtime({ from => 'start', as => 'days' }); # same as -( -M $f )
          $f->mtime({ from => 'start', as => 'dt' }); # as a DateTime

        When using `as => 'dt'', it should not make any difference which
        reference time ('epoch' or 'start') is chosen (minus computation
        errors). Prefer `from => 'epoch'' (which can be omitted) because
        there are less involved computations.

    atime [ equiv: -A ]
          $atime = $f->atime;
          $atime = $f->atime(\%options);

        Returns the access time of the file. Everything that was said about
        `mtime' applies here. By default, it returns the number of seconds
        from epoch (as `$f->stat->atime' does). And it supports the options
        'from' and 'as' with the same choices as 'mtime' does.

    ctime [ equiv: -C ]
          $ctime = $f->ctime;
          $ctime = $f->ctime(\%options);

        Returns the creation (or inode change) time of the file (for
        filesystems which support it). Everything that was said about
        `mtime' applies here. By default, it returns the number of seconds
        from epoch (as `$f->stat->ctime' does). And it supports the options
        'from' and 'as' with the same choices as 'mtime' does.

    uri
          $uri = $f->uri;

        Returns a 'file:/' URI pointing to the actual file.