The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
File-CleanupTask-0.11
River stage zero No dependents
++
/ File::CleanupTask

NAME

File::CleanupTask - Delete or back up files using a task-based configuration

VERSION

Version 0.11

SYNOPSIS

    use File::CleanupTask;

    my $cleanup = File::Cleanup->new({
        conf => "/path/to/tasks_file.tasks",
        taskname => "TASK_LABEL_IN_TASKFILE",
    });

    $cleanup->run();

Once run() is called, the cleanup operation 'TASK_LABEL_IN_TASKFILE' specified in tasks_file.tasks is performed.

CONFIGURATION FORMAT

A .tasks file is a text file in which one or more cleanup tasks are specified. Each task has a label and a list of options specified as shown in the following example:

    [TASK_LABEL_IN_TASKFILE]
    path                = '/home/savio/results/'
    backup_path         = '/home/savio/old_results/'
    backup_gzip             = 1
    max_days                = 3
    recursive               = 1
    prune_empty_directories = 1
    keep_if_linked_in       = '/home/savio/results/'

    [ANOTHER_LABEL]
    path = 'C:\\this\\is\\a\\windows\\path'
        ...

In this case, [TASK_LABEL_IN_TASKFILE] is the name of the cleanup task to be executed.

The following options can be specified under a task label:

path

The path to the directory containing the files to be deleted or removed.

Note that for MS Windows the backslashes in a path should be escaped and single quotes are strictly needed when specifying a path name (see the example above).

backup_path

If specified, will cause files to be moved in the specified directory instead of being deleted. If backup_path doesn't exist, it will be created. Symlinks are not backed up. The files are backed up at the toplevel of backup_path in a .gz (or .tgz, depending on backup_gzip) archive, which preserves pathnames of the archived files.

backup_gzip

If set to "1", will gzip the files saved in backup_path. The resulting archive will preserve the pathname of the original file, and will be relative to 'path'.

For example, given the following configuration:

   [LABEL]
   path = /path/to/cleanup/
   backup_path = /path/to/backup/
   backup_gzip = 1

If /path/to/cleanup/my/target/file.txt is encountered, and it's old, it will be backed up in /path/to/backup/file.txt.gz. Uncompressing file.txt.gz using /path/to/backup as current working directory will result in:

   /path/to/backup/path/to/cleanup/my/target/file.txt

max_days

The number of maximum days within which the files in the cleanup directories are kept. If a file is older than the specified number of days, it is queued for deletion.

For example, max_days = 3 will delete files older than 3 days from the cleanup directory.

max_days defaults to 0 if it isn't specified, meaning that all the files are to be deleted.

recursive

If set to 0, only files within "path" can be deleted/backed up. If set to 1, files located at any level within "path" can be deleted.

If prune_empty_directories is enabled and recursive is disabled, then only empty directories that are direct children of "path" will be cleaned up.

By default, this takes the 0 value.

prune_empty_directories

If set to 1, empty directories will be deleted, respecting the max_days option. (In versions 0.09 and older, this would not respect the max_days option.)

By default, this takes the 0 value.

keep_if_linked_in

A pathname to a directory that may contain symlinks. If specified, it will prevent deletion of files and directories within path that are symlinked in this directory, regardless of their age.

This option will be ignored in MS Windows or in other operating systems that don't support symlinks.

do_not_delete

A regular expression that defines a pattern to look for. Any pathnames matching this pattern will not be erased, regardless of their age. The regular expression applies to the full pathname of the file or directory.

In the configuration file, it should be surrounded by forward slashes. Because the configuration file is parsed by Config::Simple, you will need to escape any backslashes in the regex with a backslash.

delete_all_or_nothing_in

If set to 1, immediate subfolders in path will be deleted only if all the files in it are deleted.

pattern

If specified, will apply any potential delete or backup action to the files that match the pattern. Any other file will be left untouched.

If set to 1, the symlinks inside 'path' will be deleted only if their target will be deleted. This option is disabled by default, which means that the target of symlinks within the path will not be questioned during deletion/backup, they will be just treated as regular files.

This option will be ignored in MS Windows or in other operating systems that don't support symlinks.

METHODS

new

Create and configure a new File::CleanupTask object.

The object must be initialised as follows:

    my $cleanup = File::Cleanup->new({
        conf => "/path/to/tasks_file.tasks",
        taskname => 'TASK_LABEL_IN_TASKFILE',
    });

command_line_run

Given the arguments specified in the command line, processes them, creates a new File::CleanupTask object, and then calls run.

Options include dryrun, verbose, task and conf.

dryrun: just build and show the plan, nothing will be executed or deleted.
verbose: produce more verbose output.
task: optional, will result in the execution of the specified task.
path: the path to the .tasks configuration file.

run

Perform the cleanup

run_one_task

Run a single cleanup task given its configuration and name. The name is used as a label for possible output and is an optional parameter of this method.

This will scan all files and directories in path in a depth first fashion. If a file is encountered a target action is performed based on the state of that file (file or directory, symlinked, old, empty directory...).

verbose, dryrun

Accessors that will tell you if running in dryrun or verbose mode.

AUTHOR

Savio Dimatteo, <savio at lokku.com>

BUGS

Please report any bugs or feature requests to bug-file-cleanuptask at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-CleanupTask. 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 File::CleanupTask

You can also look for information at:

ACKNOWLEDGEMENTS

Thanks Alex for devising the original format of a .tasks file and offering me the opportunity to publish this work on CPAN.

Thanks Mike for your feedback about canonical paths detection.

Thanks David for reviewing the code.

Thanks #london.pm for helping me choosing the name of this module.

LICENSE AND COPYRIGHT

Copyright 2012 Savio Dimatteo.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.