Jerrad Pierce > clobber-0.10_1 > clobber

Download:
clobber-0.10_1.tgz

Dependencies

Annotate this POD

View/Report Bugs
Source  

NAME ^

clobber - pragma to optionally prevent over-writing files

SYNOPSIS ^

  BEGIN{ no clobber }

  #These fail if /tmp/xyzzy exists
      open(HNDL, '>   /tmp/xyzzy');
  #   open(HNDL, '>', /tmp/xyzzy');
  #sysopen(HNDL,     '/tmp/xyzzy', O_WRONLY|O_CREAT);

  #It's clobberin' time
  do{
    use clobber; open(HNDL, '>/tmp/xyzzy');
  }

DESCRIPTION ^

Do you occasionally get +> and +< mixed up, or accidentally leave off an > in the mode of an open? Want to run some relatively trustworthy code--such as some spaghetti monster you created in the days of yore--but can't be bothered to check it's semantics? Or perhaps you'd like to add a level of protection to operations on user-supplied files without coding the logic yourself.

Yes? Then this pragma could help you from blowing away valuable data, similar to the noclobber variable of some shells or -i option of mv. This behavior can be controlled at the block level, as demonstrated in the "SYNOPSIS".

All modes restrict rename to mimic the -i option of mv.

If a backup extension is not supplied for perl's -inplace edit mode, it is set to ~

The protections afforded to open and <sysopen> are configurable:

Default protection

This includes modes that truncate or allow modification of data.

open

> | +> | +<

sysopen

O_WRONLY | O_RDWR | O_TRUNC

Lax protection

This only includes modes that explicitly truncate.

open

> | +>

sysopen

O_TRUNC

You may loosen clobber's reigns by passing :lax to (un)import, for a usage similar similar to strict:

  no clobber;
  ...
  {
    use clobber ':lax';
    ...
  }

DIAGNOSTICS ^

The pragma may throw the following exceptions:

%s: File exists

We saved data!

Failed to parse EXPR of 2-arg open: %s

The pragma could not figure out what mode was used, and decided to bail for safety.

This shouldn't happen.

ENVIRONMENT ^

You may disable clobber protection at compile-time by setting the environment variable clobber.pm to 1. This allows you to include clobber.pm in PERL5OPT as -M-clobber for general protection, but override it as needed for programs invoked via a pipeline.

CAVEATS ^

As noted in the "DESCRIPTION", this is meant to be used with code which is generally believed to be safe, and is a layer of protection against human error, not malicious intent. I know it could have prevented many 1-liner-enabled, self-inflicted gunshot wounds of the foot in the past.

Any number of other actions could result in data loss including the invocation of external programs via pipe-opens, qx, or system (with or without shell redirection) and calls to fuctions implemented in XS.

NOTES ^

Requires Perl 5.6 or higher. the basic premise could be implemented in 5.005, but we translate (nearly) every 2-arg open to 3-arg for 'simplicity'/safety/shits-n-giggles; the exceptions are dups and fdopens for Perl 5.6, where 3-arg open doesn't grok these modes.

TODO ^

Tests

If interactive ask to run the more complex tests, with timeout to skip the initial query.

:quiet mode to continue despite failed command?

Not by default. Other bad things may happen if a filehandle is not available, but file renaming may be okay. Should it threfore default to carp?

wrap other data-damaging functions in a :strict mode?

e.g; truncate, unlink, and calls to external commands.

AUTHOR ^

Jerrad Pierce <JPIERCE circle-a CPAN full-stop ORG>

LICENSE ^

Or, if you prefer:

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.0 or, at your option, any later version of Perl 5 you may have available.

syntax highlighting: