/ 
Backup-SingleFile-0.12
/ Backup::SingleFile

NAME

Backup::SingleFile - copies one file to a predefined backup-directory, appends the date and a counter for keeping the history.

EXAMPLE

my $ok = File::SimpleBackup::backup_file("MyContacts.txt", "MyBackupDir");

Creates a copy of MyContacts.txt named MyBackupDir/MyContacts_2009-07-19.txt (on the 19th of July 2009)

If the same file copied again on the same day a second copy named MyBackupDir/MyContacts_2009-07-19_000.txt is created.

TRANSLATIONS

The following documentation is still in German - a short description can be found in the README. If you want to help speeding up the translating, please drop me an email to <perl at lantschner.name>

VERSION

Version 0.12

SYNOPSIS

Dieses Modul kopiert eine Datei in ein vordefiniertes Backupverzeichnis. Dabei wir das Datum im ISO-Format (YYYY-MM-DD) angehängt und ggf. durch einen Zähler ergänzt. Im Backup-Verzeichnis vorhandene Sicherungskopien, werden also niemals gelöscht.

Typischer Anwendungsfall ist die Erstellung von Sicherungskopien einzelner Dateien von z.B. mobilen Geräten auf einen Computer.

Beispiel:

    use File::SimpleBackup;
	my $src_file = "/Volumes/Garmin/Current.gpx";
	my $sik_dir = "~/MyBackups/Garmin/";

    my $ok = File::SimpleBackup::backup_file($src_file, $sik_dir);
    ...

Dieser Beispiel-Code kopiert am 28. 06. 2008 die Current.gpx eines unter /Volumes/Garmin eingehängten GPS-Gerätes in das Verzeichnis MyBackups/Garmin und legt diese dort unter dem Namen Current_2009-06-28.gpx ab. Bei weiteren Aufrufen am selben Kalendertag, wird ein Zähler angehängt (Current_2009-06-28_000.gpx, Current_2009-06-28_001.gpx).

EXPORT

backup - Argumente und Optionen siehe unten

append_date - Anhängen des Datums an den Dateinamen (vor die Extension)

increment - hochzählen des angehängten Zählers bis 999

DEPENDENCIES

Needs the following modules:

  • Carp

  • File::Basename

  • Time::localtime

  • File::Copy

FUNCTIONS

backup

Diese Funktion benötigt zwei Parameter:

src_file: Die zu kopierende Datei. Pfad entweder absolut oder relativ zum Arbeitsverzeichnis.

sik_dir: Das Verzeichnis, in dem die Sicherungsdateien abgelegt werden.

OPTIONEN

time: UNIX-Time (Epochensekunden) für den Zeitstempel, Voreinstellung ist die aktuelle Systemzeit

seperator: Dateiname und Suffix (Datum bzw. Datum plus Zähler) werden meist durch Leerzeichen oder Underscore getrennt. Der Underscore ist die sicherere Wahl, da er auf wohl allen Plattformen akzeptiert wird. Das Leerzeichen ist dafür schöner und wird inzwischen in vielen Dateisystemen als gültiges Zeichen in Dateinamen akzeptiert. Die Voreinstellung ist aber der Underscore. Zusätzlich werden noch Dash und Hashmark unterstützt.

increment_existing: Wenn 1 (wahr), dann werden bei nochmaligem Aufruf am selben Tag weitere Backups angelegt indem ein an den Dateinamen angehängter, 3-stelliger Zähler jeweils hoch gezählt wird. So sind insgesamt 1001 Backups je Tag möglich (Datei+Datum, Datei+Datum+000, Datei+Datum+001, ... Datei+Datum+999). Bei Übergabe einer zu sichernden Datei (src_file) mit dem Suffix 999 wird abgebrochen und ein Fehler ausgegeben. Ist diese Option 0 oder undef (falsch), kann nur eine Sicherungskopie je Tag angelegt werden. Die Voreinstellung ist 1. Siehe auch das Beispiel in SYNOPSIS oben.

RÜCKGABEWERT

Die Funktion backup() gibt 1 bei Erfolg und 0 bei Fehlschlag zurück.

append_date

Diese Funktion hängt an einen als erstes Argument übergebenen Dateinamen das Tagesdatum im ISO-Format an. Wird kein zweites Argument übergeben, so verwendet diese Funktion die aktuelle UNIX-Time des Systems, andernfalls die als zweites Argument übergebene Zeit (UNIX-Time, also Epochensekunden).

$new_filename = append_date("Current.gpx");
print "$new_filename";
# gibt am 13. 02. 2009 "Current_2009-02-13.gpx" aus 

$new_filename = append_date("Current.gpx", 1234567890);
print "$new_filename";
# gibt "Current_2009-02-14.gpx" aus - unabhängig vom aktuellen Datum

Die Erstellung des Strings für das Datum erfolgt passend zur jeweiligen Zeitzone des Systems.

VARIABLES

Ist die Variable $SEPERATOR gesetzt, wird das darin gespeicherte Zeichen als Trennzeichen zwischen Dateiname und Datums-Suffix verwendet. Andernfalls wird der Underscore verwendet.

$SEPERATOR = q{_} ==> Current_2009-02-13.gpx  # Underscore
$SEPERATOR = q{ } ==> Current 2009-02-13.gpx  # Space
$SEPERATOR = q{#} ==> Current#2009-02-13.gpx  # Hashmark
$SEPERATOR = q{-} ==> Current-2009-02-13.gpx  # Dash

RÜCKGABEWERT und FEHLERMELDUNGEN

Die Funktion gibt undef zurück, wenn Fehler aufgetreten sind. GGf. werden zuvor noch Fehlermeldungen nach stderr ausgegeben.

increment

Diese Funktion hängt an einen als erstes Argument übergebenen Dateinamen einen 3-stelligen Zähler an: 000, 001, ... Bei der Übergabe von Dateien, deren Namen bereits mit einem solchen Zähler endet, wird der Dateiname mit dem nächst höheren Zähler retourniert. Bei Übergabe eines Dateinamens mit 999 am Ende, wird eine Fehlermeldung nach stderr ausgegeben. Der Rückgabewert ist in diesem Fall undef.

$new_filename = increment(Current_2009-06-23.gpx);
print "$new_filename";
# gibt "Current_2009-06-23_000.gpx" aus

$new_filename = increment(Current_2009-06-23_000.gpx);
print "$new_filename";
# gibt "Current_2009-06-23_001.gpx" aus

$new_filename = increment(somefile.gpx);
print "$new_filename";
# gibt "somefile_000.gpx" aus

AUTHOR

Ingo Lantschner, <perl at lantschner.name>

BUGS

Please report any bugs or feature requests to bug-backup-singlefile at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Backup-SingleFile. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Backup::SingleFile

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2009 Ingo Lantschner, all rights reserved.

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