File::Fu - file and directory objects

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

Index

Code Index:

NAME

Top

File::Fu - file and directory objects

SYNOPSIS

Top

The directory constructor:

  use File::Fu;

  my $dir = File::Fu->dir("bar");
  print "$dir\n"; # 'bar/'

  my $file = $dir + 'bar.txt';
  print "$file\n"; # 'bar/bar.txt'

  my $d2 = $dir % 'baz'; # 'barbaz/'
  my $d3 = $dir / 'bat'; # 'bar/bat/'

  my $file2 = $dir / 'bat' + 'foo.txt'; # 'bar/bat/foo.txt'

The file constructor:

  my $file = File::Fu->file("foo");
  $file->e and warn "$file exists";
  $file->l and warn "$file is a link";
  warn "file is in ", $file->dir;

ABOUT

Top

This class provides the toplevel interface to File::Fu directory and file objects, with operator overloading which allows precise path composition and support for most builtin methods, as well as creation of temporary files/directories, finding files, and more.

The interface and style are quite different than the perl builtins or File::Spec. The syntax is concise. Errors are thrown with croak(), so you never need to check a return code.

Constructors

Top

The actual objects are in the 'Dir' and 'File' sub-namespaces.

dir

  my $dir = File::Fu->dir($path);

See new in File::Fu::Dir

file

  my $file = File::Fu->file($path);

See new in File::Fu::File

Class Constants

Top

tmp

Your system's '/tmp/' directory (or equivalent of that.)

  my $dir = File::Fu->tmp;

home

User's $HOME directory.

  my $dir = File::Fu->home;

program_name

The absolute name of your program. This will be relative from the time File::Fu was loaded. It dies if the name is '-e'.

  my $prog = File::Fu->program_name;

If File::Fu was loaded after a chdir and the $0 was relative, calling program_name() throws an error. (Unless you set $0 correctly before requiring File::Fu.)

program_dir

Returns what typically corresponds to program_name()->dirname, but just the compile-time cwd() when $0 is -e/-E.

  my $dir = File::Fu->program_dir;

Class Methods

Top

THIS_FILE

A nicer way to say __FILE__.

  my $file = File::Fu->THIS_FILE;

cwd

The current working directory.

  my $dir = File::Fu->cwd;

which

Returns File::Fu::File objects of ordered candidates for $name found in the path.

  my @prog = File::Fu->which($name) or die "cannot find $name";

If called in scalar context, returns a single File::Fu::File object or throws an error if no candidates were found.

  my $prog = File::Fu->which($name);

Temporary Directories and Files

Top

These class methods call the corresponding File::Fu::Dir methods on the value of tmp(). That is, you get a temporary file/dir in the '/tmp/' directory.

temp_dir

  my $dir = File::Fu->temp_dir;

temp_file

  my $handle = File::Fu->temp_file;

Subclassing

Top

You may wish to subclass File:Fu and override the dir_class() and/or file_class() class methods to point to your own Dir/File subclasses.

  my $class = 'My::FileFu';
  my $dir = $class->dir("foo");

See File::Fu::File and File::Fu::Dir for more info.

See Also

Top

File::Fu::why if I need to explain my motivations.

Path::Class, from which many an idea was taken.

File::stat, IO::File, File::Spec, File::Find, File::Temp, File::Path, File::Basename, perlfunc, perlopentut.

AUTHOR

Top

Eric Wilhelm @ <ewilhelm at cpan dot org>

http://scratchcomputing.com/

BUGS

Top

If you found this module on CPAN, please report any bugs or feature requests through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

If you pulled this development version from my /svn/, please contact me directly.

COPYRIGHT

Top

Copyright (C) 2008 Eric L. Wilhelm, All Rights Reserved.

NO WARRANTY

Top

Absolutely, positively NO WARRANTY, neither express or implied, is offered with this software. You use this software at your own risk. In case of loss, no person or entity owes you anything whatsoever. You have been warned.

LICENSE

Top

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

File-Fu documentation Contained in the File-Fu distribution. 
package File::Fu;
$VERSION = v0.0.7;

use warnings;
use strict;
use Carp;


use Cwd ();

use File::Fu::File;
use File::Fu::Dir;
use File::Spec ();

use constant dir_class => 'File::Fu::Dir';
use constant file_class => 'File::Fu::File';


sub dir {
  my $package = shift;

  $package or croak("huh?");
  # also as a function call
  unless($package and $package->isa(__PACKAGE__)) {
    unshift(@_, $package);
    $package = __PACKAGE__;
  }

  $package->dir_class->new(@_);
} # end subroutine dir definition
########################################################################


sub file {
  my $package = shift;

  # also as a function call
  unless($package->isa(__PACKAGE__)) {
    unshift(@_, $package);
    $package = __PACKAGE__;
  }

  $package->file_class->new(@_);
} # end subroutine file definition
########################################################################


{
my $tmp; # XXX needs locking?
sub tmp {
  my $package = shift;
  $tmp and return($tmp);
  return($tmp = $package->dir(File::Spec->tmpdir));
}}
########################################################################


{
my $home; # XXX needs locking!
sub home {
  my $package = shift;
  $home and return($home);
  return($home = $package->dir($ENV{HOME}));
}} # end subroutine home definition
########################################################################


{
# fun startup stuff and various logic:
my $prog = $0;
my $name_sub;
my $dir_sub;
if(lc($prog) eq '-e') {
  my $prog_dir = Cwd::cwd();
  $dir_sub  = eval(qq(sub {shift->dir("$prog_dir")}));
  $name_sub = eval(qq(sub {croak("program_name => '$prog'")}));
}
else {
  if(-e $prog) {
    my $prog_name = __PACKAGE__->file($prog)->absolutely;
    my $prog_dir = $prog_name->dirname;
    $name_sub = eval(qq(sub {shift->file('$prog_name')}));
    $dir_sub  = eval(qq(sub {shift->dir('$prog_dir')}));
  }
  else {
    # runtime error
    $dir_sub  = sub {croak("$prog not found => no program_dir known")};
    $name_sub = sub {croak("$prog not found => no program_name known")};
  }
}
*program_name = $name_sub;
*program_dir  = $dir_sub;
} # program_name/program_dir
########################################################################


sub THIS_FILE {
  my $package = shift;
  my $name = (caller)[1];
  return $package->file($name);
} # end subroutine THIS_FILE definition
########################################################################


sub cwd {
  my $package = shift;

  defined(my $ans = Cwd::cwd()) or croak("cwd() failed");
  return $package->dir($ans);
} # end subroutine cwd definition
########################################################################


sub which {
  my $package = shift;
  croak("must have an argument") unless(@_);
  my ($what) = @_;

  require File::Which;
  if(wantarray) {
    return map({$package->file($_)} File::Which::which($what));
  }
  else {
    my $found = scalar(File::Which::which($what)) or
      croak("cannot locate '$what' in PATH");
    return $package->file($found);
  }
} # which ##############################################################


sub temp_dir {
  my $package = shift;
  $package->tmp->temp_dir(@_);
} # end subroutine temp_dir definition
########################################################################


sub temp_file {
  my $package = shift;
  $package->tmp->temp_file(@_);
} # end subroutine temp_file definition
########################################################################


# vi:ts=2:sw=2:et:sta
1;