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

SYNOPSIS
     use Dir::Split;

     $dir = Dir::Split->new(
         source => $source_dir,
         target => $target_dir,
     );

     $dir->split_num;

     # or

     $dir->split_num(
         verbose => 1,
         ...
     );

     $dir->print_summary;

DESCRIPTION
    "Dir::Split" splits files of a directory to subdirectories with a number
    or characters as suffix.

CONSTRUCTOR
  new
    Creates a new "Dir::Split" object.

     $dir = Dir::Split->new(
         source => $source_dir,
         target => $target_dir,
     );

    *   "source"

        Path to source directory.

    *   "target"

        Path to target directory.

METHODS
  split_num
    Splits to subdirectories with number as suffix. Arguments to
    "split_num()" are options and not necessarily required.

     $dir->split_num(
         verbose   => [0|1],
         override  => [0|1],
         sort      => 'asc',
         limit     => 5,
         prefix    => 'sub',
         separator => '-',
         continue  => [0|1],
         length    => 5,
     );

    *   "verbose"

        Be verbose. Accepts a boolean, defaults to false.

    *   "override"

        Replace existing files. Accepts a boolean, defaults to false.

    *   "sort"

        Sort mode. Accepts 'asc' for ascending, 'desc' for descending;
        defaults to ascending.

    *   "limit"

        Maximum of files per subdirectory. Accepts a number, defaults to 5.

    *   "prefix"

        Prefix of subdirectories. Accepts a string, defaults to 'sub'.

    *   "separator"

        Separator between prefix and suffix of subdirectory. Accepts a
        string, defaults to '-'.

    *   "continue"

        Resume suffix from ones already existing. Accepts a boolean,
        defaults to false.

    *   "length"

        Length of suffix. Accepts a number, defaults to 5.

  split_char
    Splits to subdirectories with characters as suffix. Arguments to
    "split_char()" are options and not necessarily required.

     $dir->split_char(
         verbose   => [0|1],
         override  => [0|1],
         prefix    => 'sub',
         separator => '-',
         case      => 'upper',
         length    => 1,
     );

    *   "verbose"

        Be verbose. Accepts a boolean, defaults to false.

    *   "override"

        Replace existing files. Accepts a boolean, defaults to false.

    *   "prefix"

        Prefix of subdirectories. Accepts a string, defaults to 'sub'.

    *   "separator"

        Separator between prefix and suffix of subdirectory. Accepts a
        string, defaults to '-'.

    *   "case"

        Case of suffix. Accepts 'lower' for lower case, 'upper' for upper
        case; defaults to upper case.

    *   "length"

        Length of suffix. Accepts a number, defaults to 1.

  print_summary
    Prints a summary.

EXAMPLES
    Assume the source directory contains following files:

     +- _123
     +- abcd
     +- efgh
     +- ijkl
     +- mnop

    Splitting the source to the target directory could result in:

    number as suffix

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

    characters as suffix

     +- sub-_
     +-- _123
     +- sub-A
     +-- abcd
     +- sub-E
     +-- efgh
     +- sub-I
     +-- ijkl
     +- sub-M
     +-- mnop

BUGS & CAVEATS
    As of "v0.80_01", currently no value is returned from the splitting
    methods. Also, direct access to global tracking and debug variables has
    been removed. Furthermore, unlinking of source files and directories
    must be handled manually.

AUTHOR
    Steven Schubiger <schubiger@cpan.org>

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

    See <http://dev.perl.org/licenses/>