NAME
    Sort::Half::Maker - Create half-sort subs easily

SYNOPSIS
        use Sort::Half::Maker qw(make_halfsort);

        $sub = make_halfsort(
                      start => [ qw(x y z) ],
                      end => [ qw(a b c) ],
                      fallback => sub { $_[0] cmp $_[1] },
        );
        @list = sort $sub qw(a y f h w z b t x);
        # qw(x y z f h t w a b)

DESCRIPTION
    Before anything, what it a half-sort?

    A half-sort is a sort subroutine defined by a starting list, an ending
    list and an ordinary sort subroutine. Elements in the starting list
    always go first in comparison to others and keep the original order.
    Elements in the ending list always go last in comparison to others and
    keep their original order. The remaining elements are sorted via the
    given ordinary sort subroutine.

    An example, please?

    Imagine we want to sort the list of key/value pairs of a hash, such that
    `qw(name version abstract license author)' come first and
    `qw(meta-spec)' comes last, using case-insensitive comparison
    in-between. With this module, this is done so:

        $sub = make_halfsort(
                   start => [ qw(name version abstract license author) ],
                   end => [ qw(meta-spec) ],
                   fallback => sub { lc $_[0] cmp lc $_[1] }
               );
        my @pairs = map { ($_, $h{$_}) } sort $sub keys(%h);

    Why is it good for?

    I don't see many uses for it. I played with the concept while writing a
    patch to improve META.yml generation by ExtUtils::MakeMaker. There we
    wanted to dump some keys (like name, version, abstract, license, author)
    before and then the ones the module author provided as extra
    information.

  FUNCTIONS
    make_halfsort
            $sub = make_halfsort(start => \@start_list,
                                 end => \@end_list,
                                 fallback => &\sort_sub
                   );
            @sorted = sort $sub @unsorted;

        Builds a sort subroutine which can be used with `sort'. It splits
        the sorted list into (possibly) three partitions: the elements
        contained in `@start_list', the elements contained in `@end_list'
        and the remaining ones. For the elements in `@start_list' and
        `@end_list', the list order is preserved. For the remaining ones,
        the given sort sub (or the default) is used.

        If `fallback' is ommited, it defaults to use the sort sub `sub ($$)
        { $_[0] cmp $_[1] }'.

        The arguments `start' or `end' may be ommited as well. But if you
        omit both, you could have done it without a half-sort ;)

SEE ALSO
    Sort::Maker

BUGS
    Please report bugs via CPAN RT
    http://rt.cpan.org/NoAuth/Bugs.html?Dist=Sort-Half-Maker.

AUTHOR
    Adriano R. Ferreira, <ferreira@cpan.org>

COPYRIGHT AND LICENSE
    Copyright (C) 2007 by Adriano R. Ferreira

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