NAME

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

SYNOPSIS

use Dir::Split;

%options = (   mode    =>    'num',

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

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


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

$return = $dir->split;

DESCRIPTION

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

CONSTRUCTOR

new

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;

It is of tremendous importance to notice that checking the return code is a must. Leaving the return code untouched will not allow appropriate gathering of harmless debug data (such as existing files) and system operations that failed. Dir::Split does only report verbose output of mkpath to STDOUT. See OPTIONS / debug on how to become aware of existing files and failed system operations (copy & unlink).

RETURN CODES

(1)

Files moved successfully.

(0)

No action.

(-1)

Exists.

(see OPTIONS / debug / existing).

(-2)

Failure.

(see OPTIONS / debug / failures).

OPTIONS

type indicators

(c)

character

(i)

integer

(s)

string

numeric

Split files to subdirectories with a numeric suffix.

%options = (  mode    =>    'num',

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

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

options (mandatory)

• mode

  (s) - num for numeric.

• source

  (s) - source directory.

• target

  (s) - target directory.

• options / verbose

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

  MODES
    1  enabled
    0  disabled

• options / override

  (i) - overriding of existing files.

  MODES
    1  enabled
    0  disabled

• 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

  (i) - numbering continuation.

  MODES
    1  enabled
    0  disabled    (will start at 1)

  If numbering continuation is enabled, and numeric subdirectories are found within target directory which match the given identifier and separator, then the suffix numbering will be continued. Disabling numbering continuation may cause interfering with existing files.

• 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 equal the leading character of their filenames.

%options = (  mode    =>    'char',

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

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

);

options (mandatory)

• mode

  (s) - char for characteristic.

• source

  (s) - source directory.

• target

  (s) - target directory.

• options / verbose

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

  MODES
    1  enabled
    0  disabled

• options / override

  (i) - overriding of existing files.

  MODES
    1  enabled
    0  disabled

• 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

tracking

%Dir::Split::track keeps count of how many files the source and directories / files the target consists of. It may prove its usefulness, if the amount of files that could not be transferred due to existing ones has to be counted. Each time a new splitting is attempted, the track will be reseted.

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

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

debug

existing

If split() returns a EXISTS, this implys that the override option is disabled and files could not be moved due to existing files within the target subdirectories; they will have their paths appearing in the according keys in %Dir::Split::exists.

file    @Dir::Split::exists    # existing files, not attempted to
                               # be overwritten.

failures

If split() returns a FAILURE, this most often implys that the override option is enabled and existing files could not be overriden. Files that could not be copied / unlinked, will have their paths appearing in the according keys in %Dir::Split::failure.

file    @{$Dir::Split::failure{'copy'}}      # files that couldn't be copied,
                                             # most often on overriding failures.

        @{$Dir::Split::failure{'unlink'}}    # files that could be copied but not unlinked,
                                             # rather seldom.

It is highly recommended to evaluate those arrays on FAILURE.

EXAMPLES

Assuming /source contains 5 files:

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

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

cpanm Dir::Split

perl -MCPAN -e shell
install Dir::Split