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

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.

numeric splitting

Numeric splitting is an attempt to gather files from a source directory and split them to numbered subdirectories within a target directory. Its purpose is to automate the archiving of a great amount of files, that are likely to be indexed by numbers.

characteristic splitting

Characteristic splitting allows indexing by using leading characters of filenames. While numeric splitting is being characterised by dividing file amounts, characteristic splitting tries to keep up the contentual recognition of data.

CONSTRUCTOR

new

Creates an object. The key / value pairs may be supplied as hash reference or directly dumped to the constructor.

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

or

$dir = Dir::Split->new (
     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,
     },
);

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) - character length of the suffix.

    This option will have no effect if its smaller than the current length 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 (s) of their filenames.

%options = (  mode    =>    'char',

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

              options => {  verbose     =>         1,
                            override    =>         0,
              },
              sub_dir => {  identifier  =>     'sub',
              },
              suffix  => {  separator   =>       '-',
                            case        =>   'upper',
                            length      =>         1,
              },
);

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

  • suffix / length

    (i) - character length of the suffix.

    < 4 is highly recommended (26 (alphabet) ^ 3 == 17'576 suffix possibilites). Dir::Split will not prevent using suffix lengths greater than 3. Imagine splitting 1'000 files and using a character length > 20. The file rate per subdirectory will almost certainly approximate 1/1 - which equals 1'000 subdirectories.

    Whitespaces in suffixes will be removed.

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 weren't moved due to existing files within the target subdirectories; they will have their paths appearing 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 recommended to evaluate those arrays on FAILURE.

A @Dir::Split::exists array may coexist.

traversing

Traversal processing of files within the source directory may not be activated by passing an argument to the object constructor, it requires the following variable to be set to true:

# traversal mode
$Dir::Split::Traverse = 1;

No depth limit e.g. all underlying directories / files will be evaluated.

options

# unlink files in source
$Dir::Split::Traverse_unlink = 1;

Unlinks files after they have been moved to their new locations.

# remove directories in source
$Dir::Split::Traverse_rmdir = 1;

Removes the directories themselves after the files have been moved. In order to take effect, this option requires the $Dir::Split::Traverse_unlink to be set.

It is not recommended to turn on the latter options $Dir::Split::Traverse_unlink and $Dir::Split::Traverse_rmdir, unless you're aware of the consequences they imply.

EXAMPLES

Assuming /source contains 5 files:

+- _123
+- abcd
+- efgh
+- hijk
+- lmno

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

numeric splitting

+- system-00001
+-- _123
+-- abcd
+- system-00002
+-- efgh
+-- ijkl
+- system-00003
+-- mnop

characteristic splitting

+- system-_
+-- _123
+- system-a
+-- abcd
+- system-e
+-- efgh
+- system-i
+-- ijkl
+- system-m
+-- mnop

FAQ

Has the functionality of Dir::Split been tested?

Yes. I may not have covered all permuting cases, but it should behave mostly sane, if certain options such as numbering continuation are enabled and others, like overriding, are disabled.

Portability?

Has not yet been extensively tested. Dir::Split relies mostly upon File:: nested modules in spite of filesystem operations such as copying, unlinking and selecting an appropriate path separator; thus it should probably be portable.

Will you add any additional features?

Not unless they prove to be of unique usefulness. Dir::Split is already heavyweight enough and I am rather careful in terms of new inclusions; proposals towards additions should be well grounded.

DEPENDENCIES

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

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

20 POD Errors

The following errors were encountered while parsing the POD:

Around line 718:

Expected '=item *'

Around line 722:

Expected '=item *'

Around line 726:

Expected '=item *'

Around line 730:

Expected '=item *'

Around line 739:

Expected '=item *'

Around line 747:

Expected '=item *'

Around line 751:

Expected '=item *'

Around line 755:

Expected '=item *'

Around line 763:

Expected '=item *'

Around line 767:

Expected '=item *'

Around line 780:

Expected '=item *'

Around line 817:

Expected '=item *'

Around line 821:

Expected '=item *'

Around line 825:

Expected '=item *'

Around line 829:

Expected '=item *'

Around line 838:

Expected '=item *'

Around line 846:

Expected '=item *'

Around line 850:

Expected '=item *'

Around line 854:

Expected '=item *'

Around line 862:

Expected '=item *'