NAME App::FileSortUtils - Utilities related to sorting files in one or more directories VERSION This document describes version 0.008 of App::FileSortUtils (from Perl distribution App-FileSortUtils), released on 2023-11-14. 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) * dirs => *array[dirname]* (default: ["."]) 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. * recursive => *true* Recurse into subdirectories. * 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) * dirs => *array[dirname]* (default: ["."]) 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. * recursive => *true* Recurse into subdirectories. * 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 one or more directories. 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) * dirs => *array[dirname]* (default: ["."]) 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. * recursive => *true* Recurse into subdirectories. * 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 one or more directories. 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) * dirs => *array[dirname]* (default: ["."]) 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. * recursive => *true* Recurse into subdirectories. * 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 one or more directories. 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 /somewhere/else or, from "/somewhere/else": % mv C . If you want to see the filename on stderr as well: % mv C . 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) * dirs => *array[dirname]* (default: ["."]) 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. * recursive => *true* Recurse into subdirectories. * 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 one or more directories. 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) * dirs => *array[dirname]* (default: ["."]) 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. * recursive => *true* Recurse into subdirectories. * 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 one or more directories. 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) * dirs => *array[dirname]* (default: ["."]) 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. * recursive => *true* Recurse into subdirectories. * 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 one or more directories. 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) * dirs => *array[dirname]* (default: ["."]) 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. * recursive => *true* Recurse into subdirectories. * 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 one or more directories 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) * dirs => *array[dirname]* (default: ["."]) 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. * recursive => *true* Recurse into subdirectories. * 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 . SOURCE Source repository is at . SEE ALSO App::DownloadsDirUtils AUTHOR perlancar 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 . 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 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.