NAME
    Sort::Sub - Collection of sort subroutines

VERSION
    This document describes version 0.121 of Sort::Sub (from Perl
    distribution Sort-Sub), released on 2024-07-17.

SYNOPSIS
     use Sort::Sub qw($naturally);

     my @sorted = sort $naturally ('track1.mp3', 'track10.mp3', 'track2.mp3', 'track1b.mp3', 'track1a.mp3');
     # => ('track1.mp3', 'track1a.mp3', 'track1b.mp3', 'track2.mp3', 'track10.mp3')

    Request as subroutine:

     use Sort::Sub qw(naturally);

     my @sorted = sort {naturally} (...);

    Request a reverse sort:

     use Sort::Sub qw($naturally<r>);

     my @sorted = sort $naturally (...);
     # => ('track10.mp3', 'track2.mp3', 'track1b.mp3', 'track1a.mp3', 'track1.mp3')

    Request a case-insensitive sort:

     use Sort::Sub qw($naturally<i>);

     my @sorted = sort $naturally (...);

    Request a case-insensitive, reverse sort:

     use Sort::Sub qw($naturally<ir>);

     my @sorted = sort $naturally ('track2.mp3', 'Track1.mp3', 'Track10.mp3');
     => ('Track10.mp3', 'track2.mp3', 'Track1.mp3')

    Pass arguments to sort generator routine:

     use Sort::Sub '$by_num_of_colons', {pattern=>':'};

     my @sorted = sort $by_num_of_colons ('a::','b:','c::::','d:::');
     => ('b:','a::','d:::','c::::')

    Request a coderef directly, without using the import interface:

     use Sort::Sub;

     my $naturally = Sort::Sub::get_sorter('naturally');
     my $naturally = Sort::Sub::get_sorter('$naturally');
     my $rev_naturally = Sort::Sub::get_sorter('naturally<r>');

DESCRIPTION
    Sort::Sub and "Sort::Sub::*" are a convenient packaging of any kind of
    subroutine which you can use for sort().

    To use Sort::Sub, you import a list of:

     ["$"]NAME [ "<" [i][r] ">" ]

    Where NAME is actually searched under "Sort::Sub::*" namespace. For
    example:

     naturally

    will attempt to load "Sort::Sub::naturally" module and call its
    "gen_sorter" subroutine.

    You can either request a subroutine name like the above or a variable
    name (e.g. $naturally).

    After the name, you can add some options, enclosed with angle brackets
    "<>". There are some known options, e.g. "i" (for case-insensitive sort)
    or "r" (for reverse sort). Some examples:

     naturally<i>
     naturally<r>
     naturally<ri>

GUIDELINES FOR WRITING A SORT::SUB::* MODULE
    The name should be in lowercase. It should be an adverb (e.g.
    "naturally") or a phrase with words separated by underscore ("_") and
    the phrase begins with "by" (e.g. "by_num_and_non_num_parts").

    The module must contain a "gen_sorter" subroutine. It will be called
    with:

     ($is_reverse, $is_ci, $args)

    Where $is_reserve will be set to true if user requests a reverse sort,
    $is_ci will be set to true if user requests a case-insensitive sort.
    $args is hashref to pass additional arguments to the gen_sorter()
    routine. The subroutine should return a code reference.

    The module should also contain a "meta" subroutine which returns a
    metadata DefHash. Known properties (keys) include: "v" (currently at 1),
    "summary", "compares_record" (bool, if set to true then sorter will be
    fed records "[$data, $order]" instead of just $data; $order is a number
    that can be line number of array index; this allows sorter to sort by
    additional information instead of just the data items). Other metadata
    properties will be added in the future.

FUNCTIONS
  get_sorter
    Usage:

     my $coderef = Sort::Sub::get_sorter('SPEC' [ , \%args [ , $with_meta ] ]);

    Example:

     my $rev_naturally = Sort::Sub::get_sorter('naturally<r>');

    This is an alternative to using the import interface. This function is
    not imported.

    If $with_meta is set to true, will return this:

     ($sorter, $meta)

    instead of just the $sorter subroutine.

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Sort-Sub>.

SOURCE
    Source repository is at <https://github.com/perlancar/perl-Sort-Sub>.

SEE ALSO
    Other additional "Sort::Sub::*" not bundled in this distribution.

    Supporting CLI's: sortsub (from App::sortsub), sorted (from
    App::sorted), CLI's from App::SortSubUtils.

AUTHOR
    perlancar <perlancar@cpan.org>

CONTRIBUTING
    To contribute, you can send patches by email/via RT, or send pull
    requests on GitHub.

    Most of the time, you don't need to build the distribution yourself. You
    can simply modify the code, then test via:

     % prove -l

    If you want to build the distribution (e.g. to try to install it locally
    on your system), you can install Dist::Zilla,
    Dist::Zilla::PluginBundle::Author::PERLANCAR,
    Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two
    other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps
    required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE
    This software is copyright (c) 2024, 2020, 2019, 2018, 2016, 2015 by
    perlancar <perlancar@cpan.org>.

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

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=Sort-Sub>

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.