[gentoo-dev] RFD: Replacement for versionator.eclass in PMS (for EAPI 7?)

[Ulrich Mueller <ulm@gentoo.org>]

[-- Attachment #1: Type: text/plain, Size: 4325 bytes --]

As you may know, we intend to move the functionality of
versionator.eclass to the package manager, possibly in EAPI 7.
The following is what mgorny and myself have come up with, see
bug 482170 [1], especially comments 15 and 16 there.

Currently there are 15 functions defined in that eclass, and we
believe that it will not be feasible to implement all of them.
However, several of the functions are similar to each other and can
be combined. Two of them, namely get_version_component_range() and
replace_version_separator(), account for the vast majority of what
is used by ebuilds.

We therefore think that the following three functions would be
sufficient to cover all ebuilds' needs:


version_test [VERSION1] OP VERSION2
===================================

This comes in a two and a three argument form. Syntax is based on
test(1) (therefore the name).

- Compares VERSION1 with VERSION2, using the usual PMS version
  comparison algorithm.

- OP can be one of -eq, -ne, -lt, -le, -gt, -ge, i.e. the binary
  arithmetic operators from test(1). (We avoid C style <, >, etc.
  because they suffer from quoting issues.)

- Both VERSION1 and VERSION2 must be valid Gentoo versions.

- VERSION1 can be omitted and defaults to PVR.

version_cut RANGE [VERSION]
===========================

Since this (and the next) function is intended to aid with conversion
from Gentoo versions to foreign versions and vice versa, it is neither
required that VERSION is a valid Gentoo version, nor will the function
use Gentoo version syntax for splitting. Instead, the following simple
rules will be applied:

A version string is composed of one or more version components,
delimited by (possibly empty) version separators. Each component is a
sequence made purely of letters [A-Za-z] or purely of digits [0-9].
Separators are sequences of other characters [^A-Za-z0-9]. A version
string must start and end with a component (if it doesn't, an empty
first or last component is implied).

For example, the version:

   1.2.3b_alpha4

would be split into (c being component indexes, s separator indexes):

   1  .  2  .  3  '' b  _  alpha '' 4

   ^  ^  ^  ^  ^  ^  ^  ^  ^     ^  ^
   c1 s1 c2 s2 c3 s3 c4 s4 c5    s5 c6

Now to the version_cut() function itself:

- Extracts a part of the version string, containing components from
  the specified RANGE along with separators that are inbetween.

- RANGE is START[-[END]], i.e. START for one index, START-END for a
  range of indexes, or START- for up to the last component.

- All separators contained between the requested version components
  are included; separators preceding and following them are not.
  For example, "version_cut 2-4 1.2.3b_alpha4" would return "2.3b".

- VERSION can be omitted and defaults to PV.

version_replace_separator RANGE REPL [RANGE REPL...] [VERSION]
==============================================================

Especially for this function's name, bikeshedding is still needed.
The name should be reasonably short, as it will be used in global
scope command substitution.

Version components and separators are determined as for the
version_cut() function.

- Replaces version separators by index.

- RANGE is START[-[END]], i.e. START for one index, START-END for a
  range of indexes, or START- for up to the last separator.

- If RANGE includes empty separators, they are replaced as well.
  For example, "replace_version_sep 3 - 1.2.3b" outputs "1.2.3-b".

- REPL is a replacement string. It can be any string, and will be
  repeated for each replaced separator.

- Multiple pairs of RANGE and REPL can be specified. For example,
  "replace_version_sep 1 - 3 '~' 1.2.3b" would output "1-2.3~b".

- VERSION can be omitted and defaults to PV.

- It is not yet entirely clear what should be done in case of
  overlapping ranges. It could be an error, or the last replacement
  could win. Similarly, what should be done if there are less
  separators than specified? (versionator.eclass silently ignores the
  surplus ones.)


Questions:
1. Will these three functions be sufficient, or have we overlooked
   anything important?
2. Are the proposed specifications sane?
3. Some bikeshedding for the names, especially for the name of the
   version_replace_separator() function is needed.

Ulrich


[1] https://bugs.gentoo.org/show_bug.cgi?id=482170

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]