NAME
    Module::Release::Select - Notation to select release(s)

VERSION
    This document describes version 0.001 of Module::Release::Select (from
    Perl distribution Module-Release-Select), released on 2023-01-14.

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.

