Dunce::Files - Protects against sloppy use of files.

  use Dunce::Files;

  # open() warns you that you forgot to check if it worked.
  open(FILE, $filename);
  while( <FILE> ) {
      chop;     # chop() warns you to use chomp() instead
      print;
  }
  exit;

  # *FILE will warn you that you forgot to close it.

One of the most common programming mistakes is failing to check if an open() worked. Same goes for other file and system operations. The world outside your program is a scary, unreliable place, and things you try to do with it might not always work.

Dunce::Files makes trick versions of all file functions which do some basic sanity checking.

If used in void context (ie. you didn't check to see if it worked), they will throw a warning. If the function returns a filehandle (like open() and readdir()) that filehandle will complain if its never closed, or if its never used.

This module is useful for automated code auditing. Its also useful as a dunce cap to place on junior programmers, make sure they're not making silly mistakes.

The list of overridden functions is:

             chdir
             chmod
             chop
             chown
             chroot
             dbmopen
             flock
             link
             mkdir
             open
             opendir
             read
             rename
             rmdir
             seek
             seekdir
             symlink
             syscall
             sysseek
             system
             syswrite
             truncate
             unlink
             write

A few functions have some additional warnings:

chmod

Often, people will gratuitiously grant files more permissions than they really need causing unnecessary security problems. Making non-program files executable is a common mistake. Unnecessarily giving world write permission is another. Dunce::Files will throw a warning if either is detected.

Note: It may be worthwhile to split this out into a seperate module

chop

chop() works a little differently. Using it in void context is fine, but if it looks like you're using it to strip newlines it will throw a warning reminding you about chomp().

NOTE chop() was non-overridable before 5.7.0, so this feature will only work on that perl or newer.

dbmopen

dbmopen() will warn you if the hash argument you gave it already contains data.

open

NOT YET IMPLEMENTED

open() will warn you if you don't close its filehandle explicitly before the program ends. It will also warn if you give it an already open filehandle.

XXX I'd also like to have made sure $! is checked, but $! can't be usefully tied. :(

#'# # Waiting on postamble callbacks in Function::Override.

opendir

NOT YET IMPLEMENTED

Same as open().

Because of the way perl compiles, the following code will produce a 'Name main::FILE used only once: possible typo' where it shouldn't.

    use Dunce::Files;
    open(FILE, $filename) or die $!;
    print <FILE>;

Because open() is really Dunce::Files::open() and not the real open, Perl doesn't realize that FILE is the filehandle *FILE, so it thinks its only being used once.

Turns out this is a useful feature. If you close FILE the warning will go away, and you should have closed it in the first place.

Make a flag to have Dunce::Files die instead of just warning.

Complete Function::Override so I can finish open() and opendir().

Michael G Schwern <schwern@pobox.com> with help from crysflame and Simon Cozens. Thanks to Jay A. Kreibich for the chop() idea.

Function::Override