NAME

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

SYNOPSIS

use Dir::Split;

%options = (   mode    =>    'num',

               source  =>    '/tmp/source',
               target  =>    '/tmp/target',

               options => {  verbose      =>         1,
                             warn         =>     'all',
                             override     =>    'none',
               },
               sub_dir => {  identifier   =>     'sub',
                             file_limit   =>         2,
                             file_sort    =>       '+',
               },
               suffix  => {  separator    =>       '-',
                             continue     =>       'y',
                             length       =>         5,
               },
);


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

$return = $dir->split;

$dir->{'source'} = '/tmp/dir1';
$dir->{'target'} = '/tmp/dir2';

$return = $dir->split;

DESCRIPTION

Dir::Split moves files to either numbered or characteristic subdirectories.

CONSTRUCTOR

new ( \%options )

Creates an object. %options contains the key/value pairs which will influence the splitting process.

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

METHODS

split

Split files to subdirectories.

$return = $dir->split;

RETURN CODES

(1)

Files moved successfully.

Implies access to %Dir::Split::track (see OPTIONS / tracking).

(0)

No action.

(-1)

Existing directories/files found.

Implies access to %Dir::Split::track (see OPTIONS / tracking).

OPTIONS

type indicators

(c)

character

(i)

integer

(s)

string

numeric

Split files to subdirectories with a numeric suffix.

%options = (  mode    =>    'num',

              source  =>    '/tmp/source',
              target  =>    '/tmp/target',

              options => {  verbose     =>         1,
                            warn        =>     'all',
                            override    =>    'none',
              },
              sub_dir => {  identifier  =>     'sub',
                            file_limit  =>         2,
                            file_sort   =>       '+',
              },
              suffix  => {  separator   =>       '-',
                            continue    =>       'y',
                            length      =>         5,
              },
);

• mode

  (s) - num for numeric.

• source

  (s) - the source directory.

• target

  (s) - the target directory.

• options / verbose

  (i) - if enabled, mkpath will output the pathes on creating subdirectories.

  MODES
    1  enabled
    0  disabled

• options / warn

  (s) - warnings upon the encounter of existing files/dirs.

  LEVELS
    none
    file
    dir
    all

• options / override

  (s) - overriding of existing files/dirs.

  LEVELS
    none
    file
    dir
    all

• sub_dir / identifier

  (s) - prefix of each subdirectory created.

• sub_dir / file_limit

  (i) - limit of files per subdirectory.

• sub_dir / file_sort

  (c) - sort order of files.

  MODES
    +  ascending
    -  descending

• suffix / separator

  (s) - suffix separator.

• suffix / continue

  (c) - numbering continuation.

  MODES
    y  yes
    n  no     (will start at 1)

  If numbering continuation is set to yes, and numeric subdirectories are found within the target directory which match the given identifier and separator, then the suffix numbering will be continued.

• suffix / length

  (i) - length of the suffix in characters.

  This option will have no effect if its smaller than the current size of the highest suffix number.

characteristic

Split files to subdirectories with a characteristic suffix. Files are assigned to subdirectories which suffixes correspond with the leading character of the filenames.

%options = (  mode    =>    'char',

              source  =>    '/tmp/source',
              target  =>    '/tmp/target',

              options => {  verbose     =>         1,
                            warn        =>     'all',
                            override    =>    'none',
              },
              sub_dir => {  identifier  =>     'sub',
              },
              suffix  => {  separator   =>       '-',
                            case        =>   'lower',
              },

);

• mode

  (s) - char for characteristic.

• source

  (s) - the source directory.

• target

  (s) - the target directory.

• options / verbose

  (i) - if enabled, mkpath will output the pathes on creating subdirectories.

  MODES
    1  enabled
    0  disabled

• options / warn

  (s) - warnings upon the encounter of existing files/dirs.

  LEVELS
    none
    file
    dir
    all

• options / override

  (s) - overriding of existing files/dirs.

  LEVELS
    none
    file
    dir
    all

• sub_dir / identifier

  (s) - prefix of each subdirectory created.

• suffix / separator

  (s) - suffix separator.

• suffix / case

  (s) - lower/upper case of the suffix.

  MODES
    lower
    upper

warnings

The warning messages upon the encounter of existing directories/files; paths of existing directories/files will be applied after the messages.

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

tracking

Keeps track of how many files the source and directories/files the target consists of.

%Dir::Split::track = (  source  =>    {  files  =>    512,
                        },
                        target  =>    {  dirs   =>    128,
                                         files  =>    512,
                        },
);

Above example: directory consisting 512 files successfully splitted to 128 directories.

The override option will depending upon your operating system and/or file permissions not always be able to override existing directories/files. In case split() returns a EXISTS (implying existing directories/files), following code will print the amount of files that could not be moved.

my $not_moved = $Dir::Split::track{'source'}{'files'} -
                $Dir::Split::track{'target'}{'files'};

warn "Could not move $not_moved files.\n";

Currently there is no possibility to access the paths of directories/files that could not be moved.

EXAMPLES

Assuming /tmp/source contains 5 files:

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

After splitting the directory tree in /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