/ 
Dir-Split-0.3
River stage zero No dependents
/ Dir::Split

NAME

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

SYNOPSIS

use Dir::Split;

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

               options => {  verbose   =>  1,
               },

               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 dirs
$source_dir = '/var/tmp/src';
$target_dir = '/var/tmp/target';

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

# changes 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.

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,
               },

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

               suffix  => {  continue_num   =>         'y',
                             separator      =>         '-',
                             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
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 - sorting order of files.

MODES
  +  ascending sort order
  -  descending sort order
suffix/continue_num

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

MODES
  y   yes
  ''  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
options/warn

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

LEVELS
  none
  files
  dirs
  all
options/override

string - override of existing files/dirs.

LEVELS
  none
  files
  dirs
  all
suffix/case

string - lower/upper case of the suffix.

MODES
  lower
  upper

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.

EXAMPLES

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

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

the directory tree in the target directory /var/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

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

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