diff options
author | Sergey Poznyakoff <gray@gnu.org> | 2020-01-19 11:02:00 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org> | 2020-01-19 11:08:05 +0200 |
commit | bfd076f64698d8985723547726cd6adb9b30eb67 (patch) | |
tree | 0cc0f43ce11d5b23fbc3975b415b2817394eb15e /lib | |
parent | e3d9037c37a934718c9bc8fb196006fa7c002ac0 (diff) | |
download | file-backup-bfd076f64698d8985723547726cd6adb9b30eb67.tar.gz file-backup-bfd076f64698d8985723547726cd6adb9b30eb67.tar.bz2 |
Add documentation
Diffstat (limited to 'lib')
-rw-r--r-- | lib/File/Backup.pm | 117 |
1 files changed, 114 insertions, 3 deletions
diff --git a/lib/File/Backup.pm b/lib/File/Backup.pm index 8aed3bb..2550bdf 100644 --- a/lib/File/Backup.pm +++ b/lib/File/Backup.pm @@ -2,11 +2,12 @@ package File::Backup; use strict; use warnings; use File::Copy; -use File::Temp qw(tempdir); +use File::Temp; use File::Basename; use Exporter; use re '/aa'; use Carp; +use Errno; our $VERSION = '1.00'; our @ISA = qw(Exporter); @@ -71,8 +72,7 @@ sub backup_simple { sub backup_numbered_opt { my ($file_name, $if_exists) = @_; - my $dir = tempdir(DIR => dirname($file_name), CLEANUP => 1); - my $fh = File::Temp->new(DIR => $dir); + my $fh = File::Temp->new(DIR => dirname($file_name)); copy($file_name, $fh) or croak "failed to make a temporary copy of $file_name: $!"; @@ -94,6 +94,9 @@ sub backup_numbered_opt { while (1) { $backup_name = "$file_name.~$num~"; last if symlink($fh->filename, $backup_name); + unless ($!{EEXIST}) { + croak "can't link ".$fh->filename." to $backup_name: $!"; + } ++$num; } @@ -114,4 +117,112 @@ sub backup_auto { } 1; +__END__ + +=head1 NAME + +File::Backup - create a backup of the file. + +=head1 SYNOPSIS + + use File::Backup; + + $backup_name = backup($file_name); + + $backup_name = backup($file_name, BACKUP_NUMBERED); + +=head1 DESCRIPTION + +The File::Backup module provides functions for creating backup copies of +files. Normally, the name of the backup copy is created by appending a +single C<~> character to the original file name. This naming is called +I<simple backup>. Another naming scheme is I<numbered backup>. In this +scheme, the name of the backup is created by suffixing the original file +name with C<.~I<N>~>, where I<N> is a decimal number starting with 1. +In this backup naming scheme, the backup copies of file F<test> would be +called F<test.~1~>, F<test.~2~> and so on. + +=head2 backup + + $backup_name = backup($orig_name) + + $backup_name = backup($orig_name, $scheme) + +The B<backup> function is the principal interface for managing backup +copies. Its first argument specifies the name of the existing file for +which a backup copy is required. Optional second argument controls the +backup naming scheme. Its possible values are: + +=over 4 + +=item BACKUP_NONE + +Don't create backup. + +=item BACKUP_SINGLE or BACKUP_SIMPLE + +Create simple backup (F<I<FILE>~>). + +=item BACKUP_NUMBERED + +Create numbered backup (F<I<FILE>.~B<N>~>). + +=item BACKUP_AUTO + +Automatic selection of the naming scheme. Create numbered backup if the +file has numbered backups already. Otherwise, make simple backup. + +=back + +If the second argument is omitted, the function will consult the value of +the environment variable B<VERSION_CONTROL>. Its possible values are: + +=over 4 + +=item none, off + +Don't create any backups (B<BACKUP_NONE>). + +=item simple, never + +Create simple backups (B<BACKUP_SIMPLE>). + +=item numbered, t + +Create numbered backups (B<BACKUP_NUMBERED>). + +=item existing, nil + +Automatic selection of the naming scheme (B<BACKUP_AUTO>). + +=back + +If B<VERSION_CONTROL> is unset or set to any other value than those listed +above, B<BACKUP_AUTO> is assumed. + +The function returns the name of the backup file it created (C<undef> if +called with B<BACKUP_NONE>). On error, it calls B<croak()>. + +The following functions are provided for explicitly using a specific backup +naming scheme: + +=head2 backup_simple + + $backup_name = backup_simple($orig_name); + +Creates simple backup. + +=head2 backup_numbered + $backup_name = backup_numbered($orig_name); + +Creates numbered backup. + +=head2 backup_auto + + $backup_name = backup_auto($orig_name); + +Creates numbered backup if any numbered backup version already exists for +the file. Otherwise, creates simple backup. + +=cut |