NAME
Module::Release::Select - Notation to select release(s)
VERSION
This document describes version 0.002 of Module::Release::Select (from
Perl distribution Module-Release-Select), released on 2023-01-15.
SYNOPSIS
use Module::Release::Select qw(select_release select_releases);
my @releases = (0.005, 0.004, 0.003, 0.002, 0.001);
my $rel = select_release('0.002', \@releases); # => 0.002
my $rel = select_release('0.002 + 1', \@releases); # => 0.003
my $rel = select_release('> 0.002', \@releases); # => 0.005
my $rel = select_release('latest', \@releases); # => 0.005
my $rel = select_release('latest-1', \@releases); # => 0.004
my @rels = select_releases('> oldest', \@releases); # => (0.005, 0.004, 0.003, 0.002)
DESCRIPTION
This module lets you select one or more releases via an expression. Some
example expressions:
# exact version number ('=')
0.002
=0.002 # ditto
# version number range with '>', '>=', '<', '<=', '!='. use '&' to join
# multiple conditions with "and" logic, use '|' or ',' to join with "or" logic.
>0.002
>=0.002
>=0.002 & <=0.015
<0.002 | >0.015
0.001, 0.002, 0.003
# "latest" and "oldest" can replace version number
latest
=latest
<latest # all releases except the latest
!= latest # ditto
>oldest # all releases except the oldest
# +n and -m to refer to n releases after and n releases before
latest-1 # the release before the latest
0.002 + 1 # the release after 0.002
> (oldest+1) # all releases except the oldest and one after that (oldest+1)
# select by date, any date supported by DateTime::Format::Natural is supported
date < {yesterday} # all releases released 2 days ago
date > {2 months ago} # all releases after 2 months ago
# select by author
author="PERLANCAR" # all releases released by PERLANCAR
author != "PERLANCAR" # all releases not released by PERLANCAR
author="PERLANCAR" & > 0.005 # all releases after 0.005 that are released by PERLANCAR
To actually select releases, you provide a list of releases in the form
of version numbers in descending order. If you want to select by date or
author, each release will need to be a hashref containing "date" and
"author" keys. Below is an example of a list of releases for App::orgadb
distribution. This structure is returned by App::MetaCPANUtils'
"list_metacpan_release":
my @releases = (
{
abstract => "An opinionated Org addressbook toolset",
author => "PERLANCAR",
date => "2022-11-04T12:57:07",
distribution => "App-orgadb",
first => "",
maturity => "released",
release => "App-orgadb-0.015",
status => "latest",
version => 0.015,
},
...
{
abstract => "An opinionated Org addressbook tool",
author => "PERLANCAR",
date => "2022-06-23T23:21:58",
distribution => "App-orgadb",
first => "",
maturity => "released",
release => "App-orgadb-0.002",
status => "backpan",
version => 0.002,
},
{
abstract => "An opinionated Org addressbook tool",
author => "PERLANCAR",
date => "2022-06-13T00:15:18",
distribution => "App-orgadb",
first => 1,
maturity => "released",
release => "App-orgadb-0.001",
status => "backpan",
version => 0.001,
},
);
Some examples on selecting release(s):
# select a single release, if notation selects multiple releases, the latest
# one will be picked. returns undef when no releases are selected.
my $rel = select_release('0.002', \@releases); # => 0.002
my $rel = select_release('0.002 + 1', \@releases); # => 0.003
my $rel = select_release('> 0.002', \@releases); # => 0.015
# instead of returning the latest one when multiple releases are selected,
# select the oldest instead.
my $rel = select_release({oldest=>1}, '> 0.002', \@releases); # => 0.003
# return detailed record instead of just version
my $rel = select_release({detail=>1}, '0.002', \@releases); # => {version=>0.002, date=>'2022-06-23T23:21:58', ...}
# select releases, returns empty list when no releases are selected
my $rel = select_releases('>= latest-2 & <= latest', \@releases); # => 0.015, 0.014, 0.013
Expression grammar
EXPR ::= AND_EXPR ( ("," | "|") AND_EXPR )*
AND_EXPR ::= SIMPLE_EXPR ( "&" SIMPLE_EXPR )*
SIMPLE_EXPR ::= COMP
COMP ::= VER_COMP
| DATE_COMP
| AUTHOR_COMP
VER_COMP ::= "version" OP VER_VALUE
| OP VER_VALUE
| VER_VALUE ; for when OP ='='
DATE_COMP ::= "date" OP DATE_VAL
AUTHOR_COMP ::= "author" OP STR_VAL
OP ::= "=" | "!=" | ">" | ">=" | "<" | "<=" | "=~" | "!~"
VER_VALUE ::= VER_LITERAL
| VER_OFFSET
VER_OFFSET ::= VER_LITERAL ("+" | "-") [0-9]+
STR_VAL ::= STR_LITERAL
STR_LITERAL ::= '"' ( [^"\] | "\\" | "\" '"' )* '"'
DATE_VAL ::= DATE_LITERAL
DATE_LITERAL ::= "{" [^{]+ "}"
VER_LITERAL ::= ("v")? [0-9]+ ( "." [0-9]+ )*
| ("v")? [0-9]+ ( "." [0-9]+ )+ ( "_" [0-9]+ )?
| "latest"
| "oldest"
FUNCTIONS
parse_releases_expr
my $parsed = parse_releases_expr($expr_str);
Parse an expression string and return parsed structure. Mostly for
internal use only.
select_releases
my @rels = select_release( [ \%opts , ] $expr, \@releases );
Select releases from @releases using expression $expr. Will die on
invalid syntax in expression or on invalid entry in @releases.
Known options:
* detail
Bool. If true, will return detailed release records instead of just
version numbers.
* single
Bool. If true, will return only a single release instead of
multiple.
* oldest
Bool. By default, when expression selects multiple releases and only
one is requested, the newest is returned. If this option is set to
true, then the oldest will be returned instead.
select_release
Usage:
my $rel = select_release( [ \%opts , ] $expr, \@releases );
Equivalent to "select_releases({%opts, single=>1}, $expr, \@releases)".
See "select_releases" for more details on list of known options.
TODO
These notations are not yet supported but might be supported in the
future:
# "latest" & "oldest" can take argument
latest(author="PERLANCAR") # the latest release by PERLANCAR
latest(author="PERLANCAR") + 1 # the release after the latest release by PERLANCAR
oldest(date > {2022-10-01}) # the oldest release after 2022-10-01
# functions
# abstract =~ /foo/ # all releases with abstract matching a regex
# distribution ne "App-orgadb" # all releases with distribution not equal to "App-orgadb"
# first is true # all releases with "first" key being true
HOMEPAGE
Please visit the project's homepage at
<https://metacpan.org/release/Module-Release-Select>.
SOURCE
Source repository is at
<https://github.com/perlancar/perl-Module-Release-Select>.
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=Module-Release-Select
>
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.