NAME
    App::FileSortUtils - Utilities related to sorting files in a directory

VERSION
    This document describes version 0.006 of App::FileSortUtils (from Perl
    distribution App-FileSortUtils), released on 2023-11-02.

DESCRIPTION
    This distribution provides the following command-line utilities:

    1. foremost
    2. hindmost
    3. largest
    4. longest-name
    5. newest
    6. oldest
    7. shortest-name
    8. smallest
    9. sort-files

FUNCTIONS
  foremost
    Usage:

     foremost(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Return file(s) which are alphabetically the first.

    Notes: - by default dotfiles are not included, use "--all" ("-a") to
    include them

    Some examples:

     # return foremost file in current directory
     % foremost -f

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   all => *true*

        Do not ignore entries starting with .

    *   detail => *true*

        (No description)

    *   dir => *dirname::default_curdir*

        Directory to sort files of, defaults to current directory.

    *   exclude_filename_pattern => *re_from_str*

        Exclude filenames that match a regex pattern.

    *   ignore_case => *bool*

        (No description)

    *   include_filename_pattern => *re_from_str*

        Only include filenames that match a regex pattern.

    *   num_ranks => *uint*

        Number of ranks to return.

        Difference between "num_results" and "num_ranks": "num_results"
        ("-n" option) specifies number of results regardless of ranks while
        "num_ranks" ("-N" option) returns number of ranks. For example, if
        sorting is by reverse size and if "num_results" is set to 1 and
        there are 2 files with the same largest size then only 1 of those
        files will be returned. With "num_ranks" set to 1, both files will
        be returned because are they both rank #1.

    *   num_results => *uint*

        Number of results to return.

    *   type => *str*

        Only include files of certain type.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  hindmost
    Usage:

     hindmost(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Return file(s) which are alphabetically the last.

    Notes: - by default dotfiles are not included, use "--all" ("-a") to
    include them

    Some examples:

     # return hindmost file in current directory
     % hindmost -f

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   all => *true*

        Do not ignore entries starting with .

    *   detail => *true*

        (No description)

    *   dir => *dirname::default_curdir*

        Directory to sort files of, defaults to current directory.

    *   exclude_filename_pattern => *re_from_str*

        Exclude filenames that match a regex pattern.

    *   ignore_case => *bool*

        (No description)

    *   include_filename_pattern => *re_from_str*

        Only include filenames that match a regex pattern.

    *   num_ranks => *uint*

        Number of ranks to return.

        Difference between "num_results" and "num_ranks": "num_results"
        ("-n" option) specifies number of results regardless of ranks while
        "num_ranks" ("-N" option) returns number of ranks. For example, if
        sorting is by reverse size and if "num_results" is set to 1 and
        there are 2 files with the same largest size then only 1 of those
        files will be returned. With "num_ranks" set to 1, both files will
        be returned because are they both rank #1.

    *   num_results => *uint*

        Number of results to return.

    *   type => *str*

        Only include files of certain type.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  largest
    Usage:

     largest(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Return the largest file(s) in a directory.

    Some examples:

     # return largest file in current directory
     % largest -f
 
     # return largest file(s) in /some/dir (if there are multiple files with the
     # same size they will all be returned
     % largest -N1 -f /some/dir

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   all => *true*

        Do not ignore entries starting with .

    *   detail => *true*

        (No description)

    *   dir => *dirname::default_curdir*

        Directory to sort files of, defaults to current directory.

    *   exclude_filename_pattern => *re_from_str*

        Exclude filenames that match a regex pattern.

    *   include_filename_pattern => *re_from_str*

        Only include filenames that match a regex pattern.

    *   num_ranks => *uint*

        Number of ranks to return.

        Difference between "num_results" and "num_ranks": "num_results"
        ("-n" option) specifies number of results regardless of ranks while
        "num_ranks" ("-N" option) returns number of ranks. For example, if
        sorting is by reverse size and if "num_results" is set to 1 and
        there are 2 files with the same largest size then only 1 of those
        files will be returned. With "num_ranks" set to 1, both files will
        be returned because are they both rank #1.

    *   num_results => *uint*

        Number of results to return.

    *   type => *str*

        Only include files of certain type.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  longest_name
    Usage:

     longest_name(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Return file(s) with the longest name in a directory.

    Notes: - by default dotfiles are not included, use "--all" ("-a") to
    include them

    Some examples:

     # return file with the longest name in current directory
     % longest-name -f
 
     # return file(s) with the longest name in /some/dir. if there are multiple
     # files with the same length, they will all be returned.
     % longest-name -N1 -f /some/dir

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   all => *true*

        Do not ignore entries starting with .

    *   detail => *true*

        (No description)

    *   dir => *dirname::default_curdir*

        Directory to sort files of, defaults to current directory.

    *   exclude_filename_pattern => *re_from_str*

        Exclude filenames that match a regex pattern.

    *   include_filename_pattern => *re_from_str*

        Only include filenames that match a regex pattern.

    *   num_ranks => *uint*

        Number of ranks to return.

        Difference between "num_results" and "num_ranks": "num_results"
        ("-n" option) specifies number of results regardless of ranks while
        "num_ranks" ("-N" option) returns number of ranks. For example, if
        sorting is by reverse size and if "num_results" is set to 1 and
        there are 2 files with the same largest size then only 1 of those
        files will be returned. With "num_ranks" set to 1, both files will
        be returned because are they both rank #1.

    *   num_results => *uint*

        Number of results to return.

    *   type => *str*

        Only include files of certain type.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  newest
    Usage:

     newest(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Return the newest file(s) in a directory.

    Notes: - by default dotfiles are not included, use "--all" ("-a") to
    include them

    Suppose a new file is downloaded in "~/Downloads", but you are not sure
    of its name. You just want to move that file, which you are pretty sure
    is the newest in the "Downloads" directory, somewhere else. So from the
    CLI in "~/Downloads":

     % mv C<newest -f> /somewhere/else

    or, from "/somewhere/else":

     % mv C<newest -f ~/Downloads> .

    If you want to see the filename on stderr as well:

     % mv C<newest --verbose -f ~/Downloads> .

    File is deemed as newest by its mtime.

    Some examples:

     # return newest file in current directory
     % newest -f
 
     # return newest file(s) in /some/dir (if there are multiple files with the
     # same newest mtime) they will all be returned
     % newest -N1 -f /some/dir

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   all => *true*

        Do not ignore entries starting with .

    *   detail => *true*

        (No description)

    *   dir => *dirname::default_curdir*

        Directory to sort files of, defaults to current directory.

    *   exclude_filename_pattern => *re_from_str*

        Exclude filenames that match a regex pattern.

    *   include_filename_pattern => *re_from_str*

        Only include filenames that match a regex pattern.

    *   num_ranks => *uint*

        Number of ranks to return.

        Difference between "num_results" and "num_ranks": "num_results"
        ("-n" option) specifies number of results regardless of ranks while
        "num_ranks" ("-N" option) returns number of ranks. For example, if
        sorting is by reverse size and if "num_results" is set to 1 and
        there are 2 files with the same largest size then only 1 of those
        files will be returned. With "num_ranks" set to 1, both files will
        be returned because are they both rank #1.

    *   num_results => *uint*

        Number of results to return.

    *   type => *str*

        Only include files of certain type.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  oldest
    Usage:

     oldest(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Return the oldest file(s) in a directory.

    Notes: - by default dotfiles are not included, use "--all" ("-a") to
    include them

    File is deemed as oldest by its mtime.

    Some examples:

     # return oldest file in current directory
     % oldest -f
 
     # return oldest file(s) in /some/dir (if there are multiple files with the
     # same oldest mtime) they will all be returned
     % oldest -N1 -f /some/dir

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   all => *true*

        Do not ignore entries starting with .

    *   detail => *true*

        (No description)

    *   dir => *dirname::default_curdir*

        Directory to sort files of, defaults to current directory.

    *   exclude_filename_pattern => *re_from_str*

        Exclude filenames that match a regex pattern.

    *   include_filename_pattern => *re_from_str*

        Only include filenames that match a regex pattern.

    *   num_ranks => *uint*

        Number of ranks to return.

        Difference between "num_results" and "num_ranks": "num_results"
        ("-n" option) specifies number of results regardless of ranks while
        "num_ranks" ("-N" option) returns number of ranks. For example, if
        sorting is by reverse size and if "num_results" is set to 1 and
        there are 2 files with the same largest size then only 1 of those
        files will be returned. With "num_ranks" set to 1, both files will
        be returned because are they both rank #1.

    *   num_results => *uint*

        Number of results to return.

    *   type => *str*

        Only include files of certain type.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  shortest_name
    Usage:

     shortest_name(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Return file(s) with the shortest name in a directory.

    Notes: - by default dotfiles are not included, use "--all" ("-a") to
    include them

    Some examples:

     # return file with the shortest name in current directory
     % shortest-name -f
 
     # return file(s) with the shortest name in /some/dir. if there are multiple
     # files with the same length, they will all be returned.
     % shortest-name -N1 -f /some/dir

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   all => *true*

        Do not ignore entries starting with .

    *   detail => *true*

        (No description)

    *   dir => *dirname::default_curdir*

        Directory to sort files of, defaults to current directory.

    *   exclude_filename_pattern => *re_from_str*

        Exclude filenames that match a regex pattern.

    *   include_filename_pattern => *re_from_str*

        Only include filenames that match a regex pattern.

    *   num_ranks => *uint*

        Number of ranks to return.

        Difference between "num_results" and "num_ranks": "num_results"
        ("-n" option) specifies number of results regardless of ranks while
        "num_ranks" ("-N" option) returns number of ranks. For example, if
        sorting is by reverse size and if "num_results" is set to 1 and
        there are 2 files with the same largest size then only 1 of those
        files will be returned. With "num_ranks" set to 1, both files will
        be returned because are they both rank #1.

    *   num_results => *uint*

        Number of results to return.

    *   type => *str*

        Only include files of certain type.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  smallest
    Usage:

     smallest(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Return the smallest file(s) in a directory.

    Some examples:

     # return smallest file in current directory
     % smallest -f
 
     # return smallest file(s) in /some/dir (if there are multiple files with the
     # same size they will all be returned
     % smallest -N1 -f /some/dir

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   all => *true*

        Do not ignore entries starting with .

    *   detail => *true*

        (No description)

    *   dir => *dirname::default_curdir*

        Directory to sort files of, defaults to current directory.

    *   exclude_filename_pattern => *re_from_str*

        Exclude filenames that match a regex pattern.

    *   include_filename_pattern => *re_from_str*

        Only include filenames that match a regex pattern.

    *   num_ranks => *uint*

        Number of ranks to return.

        Difference between "num_results" and "num_ranks": "num_results"
        ("-n" option) specifies number of results regardless of ranks while
        "num_ranks" ("-N" option) returns number of ranks. For example, if
        sorting is by reverse size and if "num_results" is set to 1 and
        there are 2 files with the same largest size then only 1 of those
        files will be returned. With "num_ranks" set to 1, both files will
        be returned because are they both rank #1.

    *   num_results => *uint*

        Number of results to return.

    *   type => *str*

        Only include files of certain type.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  sort_files
    Usage:

     sort_files(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Sort files in a directory and display the result in a flexible way.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   all => *true*

        Do not ignore entries starting with .

    *   by_code => *code_from_str*

        Perl code to sort.

    *   by_field => *str*

        Field name to sort against.

    *   by_sortsub => *str*

        Sort::Sub routine name to sort.

    *   detail => *true*

        (No description)

    *   dir => *dirname::default_curdir*

        Directory to sort files of, defaults to current directory.

    *   exclude_filename_pattern => *re_from_str*

        Exclude filenames that match a regex pattern.

    *   include_filename_pattern => *re_from_str*

        Only include filenames that match a regex pattern.

    *   key => *code_from_str*

        Perl code to generate key to sort against.

        If "key" option is not specified, then: 1) if sorting is "by_code"
        then the code will receive files as records (hashes) with keys like
        "name", "size", etc; 2) if sorting is "by_field" then the associated
        field is used as key; 3) if sorting is "by_sortsub" then by default
        the "name" field will be used as the key.

        To select a field, use this:

         '$_->{FIELDNAME}'

        for example:

         '$_->{size}'

        Another example, to generate length of name as key:

         'length($_->{name})'

    *   num_ranks => *uint*

        Number of ranks to return.

        Difference between "num_results" and "num_ranks": "num_results"
        ("-n" option) specifies number of results regardless of ranks while
        "num_ranks" ("-N" option) returns number of ranks. For example, if
        sorting is by reverse size and if "num_results" is set to 1 and
        there are 2 files with the same largest size then only 1 of those
        files will be returned. With "num_ranks" set to 1, both files will
        be returned because are they both rank #1.

    *   num_results => *uint*

        Number of results to return.

    *   reverse => *true*

        Reverse order of sorting.

    *   sortsub_args => *hash*

        Arguments to pass to Sort::Sub routine.

    *   type => *str*

        Only include files of certain type.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

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

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

SEE ALSO
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) 2023 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=App-FileSortUtils>

    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.

