/ 
Sort-Sub-0.121
River stage three • 27 direct dependents • 266 total dependents
/ Sort::Sub

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.