NAME

Dir::Split - Split the files of a directory to subdirectories.

SYNOPSIS

 use Dir::Split;

 # numeric options
 %behavior = (  mode    =>    'num',

                options => {  verbose        =>           1,
                              warn           =>       'all',
                              override       =>      'none',
                },

                sub_dir => {  identifier     =>    'system',
                              file_limit     =>           2,
                              file_sort      =>         '+',
                },

                suffix  => {  continue_num   =>         'y',
                              separator      =>         '-',
                              length         =>           5,
                },
 );

 # create object
 $dir = Dir::Split->new (\%behavior);

 # set source & target dir
 $source_dir = '/tmp/src';
 $target_dir = '/tmp/target';

 # split files to subdirs
 $files_moved = $dir->split (\$source_dir, \$target_dir);

 # change the subdir identifier
 $dir->{'sub_dir'}{'identifier'} = 'test';

 # split files to subdirs
 $files_moved = $dir->split (\$source_dir, \$target_dir);

DESCRIPTION

Dir::Split moves files from a source directory to numbered subdirectories within a target directory.

METHODS

new ( \%behavior )

Object constructor.

 $dir = Dir::Split->new (\%behavior);

%behavior contains the options that will influence the splitting process.

split ( \$source_dir, \$target_dir )

Split files to subdirectories.

 $files_moved = $dir->split (\$source_dir, \$target_dir);

$source_dir specifies the source directory.

$target_dir specifies the target directory.

Returns the amount of files that have been successfully moved; if none, it will return undef.

OPTIONS

numeric splitting

Split files to subdirectories with a numeric suffix. Numbering may be continued or started at 1 one each time. Options are explained below. See EXAMPLES to gain an understanding how numeric splitting works.

    %behavior = (  mode    =>    'num',

                   options => {  verbose        =>           1,
                                 warn           =>       'all',
                                 override       =>      'none',
                   },

                   sub_dir => {  identifier     =>    'system',
                                 file_limit     =>           2,
                                 file_sort      =>         '+',
                   },

                   suffix  => {  separator      =>         '-',
                                 continue_num   =>         'y',
                                 length         =>           5,
                   },
    );

characteristic splitting

Split files to subdirectories with a characteristic suffix. Files are assigned to subdirectories which suffixes correspond with the leading character of the filenames. Options are explained below. See EXAMPLES to gain an understanding how characteristic splitting works.

    %behavior = (  mode    =>    'char',

                   options => {  verbose     =>           1,
                                 warn        =>       'all',
                                 override    =>      'none',
                   },

                   sub_dir => {  identifier  =>    'system',
                   },

                   suffix  => {  separator   =>         '-',
                                 case        =>     'lower',
                   },

    );

generic behavior

mode

string - either num for numeric or char for characteristic.

options/verbose

integer - verbosity; if enabled, mkpath will output the pathes on creating subdirectories.

 MODES
   0  disabled
   1  enabled

options/warn

string - warn upon the encounter of existing files/dirs.

 LEVELS
   none
   file
   dir
   all

options/override

string - override of existing files/dirs.

 LEVELS
   none
   file
   dir
   all

sub_dir/identifier

string - prefix of each subdirectory created.

suffix/separator

string - separates the identifier from the suffix.

numeric behavior

sub_dir/file_limit

integer - limit of files per subdirectory.

sub_dir/file_sort

string - sort order of files.

 MODES
   +  ascending
   -  descending

suffix/continue_num

string - numbering continuation (will start at 1 if no).

 MODES
   y  yes
   n  no

suffix/length

integer - amount of zeros to be added to the suffix.

Differing identifiers or separators do affect the numbering e.g. systm- does not equal system-, system_ does not equal system-. file_limit, file_sort and length options have no influence on decisions whether the numbering shall be continued, whereas identifier, separator and continue_num do.

characteristic behavior

suffix/case

string - lower/upper case of the suffix.

 MODES
   lower
   upper

presets

The warning messages upon the encounter of existing files/dirs.

    %Dir::Split::Warn = (  dir  =>    "exists (d)\t",
                           file =>    "exists (f)\t",
    );

EXAMPLES

Assuming the source directory /tmp/src contains 5 files:

    +- _12.tmp
    +- abc.tmp
    +- def.tmp
    +- ghi.tmp
    +- jkl.tmp

After splitting the directory tree in the target directory /tmp/target will look as following:

numeric splitting

    +- system-00001
    +-- _12.tmp
    +-- abc.tmp
    +- system-00002
    +-- def.tmp
    +-- ghi.tmp
    +- system-00003
    +-- jkl.tmp

characteristic splitting

    +- system-_
    +-- _12.tmp
    +- system-a
    +-- abc.tmp
    +- system-d
    +-- def.tmp
    +- system-g
    +-- ghi.tmp
    +- system-j
    +-- jkl.tmp

DEPENDENCIES

Perl 5.6.1; File::Copy, File::Path, File::Spec.

CAVEATS & BUGS

Recursive source directory processing is not supported; existing directories within the source directory will be ignored.

Minus integer values in file_limit and length options cause an odd behavior at runtime.

SEE ALSO

perl(1)

LICENSE

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

AUTHOR

Steven Schubiger

cpanm Dir::Split

perl -MCPAN -e shell
install Dir::Split