1 |
As you may know, we intend to move the functionality of |
2 |
versionator.eclass to the package manager, possibly in EAPI 7. |
3 |
The following is what mgorny and myself have come up with, see |
4 |
bug 482170 [1], especially comments 15 and 16 there. |
5 |
|
6 |
Currently there are 15 functions defined in that eclass, and we |
7 |
believe that it will not be feasible to implement all of them. |
8 |
However, several of the functions are similar to each other and can |
9 |
be combined. Two of them, namely get_version_component_range() and |
10 |
replace_version_separator(), account for the vast majority of what |
11 |
is used by ebuilds. |
12 |
|
13 |
We therefore think that the following three functions would be |
14 |
sufficient to cover all ebuilds' needs: |
15 |
|
16 |
|
17 |
version_test [VERSION1] OP VERSION2 |
18 |
=================================== |
19 |
|
20 |
This comes in a two and a three argument form. Syntax is based on |
21 |
test(1) (therefore the name). |
22 |
|
23 |
- Compares VERSION1 with VERSION2, using the usual PMS version |
24 |
comparison algorithm. |
25 |
|
26 |
- OP can be one of -eq, -ne, -lt, -le, -gt, -ge, i.e. the binary |
27 |
arithmetic operators from test(1). (We avoid C style <, >, etc. |
28 |
because they suffer from quoting issues.) |
29 |
|
30 |
- Both VERSION1 and VERSION2 must be valid Gentoo versions. |
31 |
|
32 |
- VERSION1 can be omitted and defaults to PVR. |
33 |
|
34 |
version_cut RANGE [VERSION] |
35 |
=========================== |
36 |
|
37 |
Since this (and the next) function is intended to aid with conversion |
38 |
from Gentoo versions to foreign versions and vice versa, it is neither |
39 |
required that VERSION is a valid Gentoo version, nor will the function |
40 |
use Gentoo version syntax for splitting. Instead, the following simple |
41 |
rules will be applied: |
42 |
|
43 |
A version string is composed of one or more version components, |
44 |
delimited by (possibly empty) version separators. Each component is a |
45 |
sequence made purely of letters [A-Za-z] or purely of digits [0-9]. |
46 |
Separators are sequences of other characters [^A-Za-z0-9]. A version |
47 |
string must start and end with a component (if it doesn't, an empty |
48 |
first or last component is implied). |
49 |
|
50 |
For example, the version: |
51 |
|
52 |
1.2.3b_alpha4 |
53 |
|
54 |
would be split into (c being component indexes, s separator indexes): |
55 |
|
56 |
1 . 2 . 3 '' b _ alpha '' 4 |
57 |
|
58 |
^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ |
59 |
c1 s1 c2 s2 c3 s3 c4 s4 c5 s5 c6 |
60 |
|
61 |
Now to the version_cut() function itself: |
62 |
|
63 |
- Extracts a part of the version string, containing components from |
64 |
the specified RANGE along with separators that are inbetween. |
65 |
|
66 |
- RANGE is START[-[END]], i.e. START for one index, START-END for a |
67 |
range of indexes, or START- for up to the last component. |
68 |
|
69 |
- All separators contained between the requested version components |
70 |
are included; separators preceding and following them are not. |
71 |
For example, "version_cut 2-4 1.2.3b_alpha4" would return "2.3b". |
72 |
|
73 |
- VERSION can be omitted and defaults to PV. |
74 |
|
75 |
version_replace_separator RANGE REPL [RANGE REPL...] [VERSION] |
76 |
============================================================== |
77 |
|
78 |
Especially for this function's name, bikeshedding is still needed. |
79 |
The name should be reasonably short, as it will be used in global |
80 |
scope command substitution. |
81 |
|
82 |
Version components and separators are determined as for the |
83 |
version_cut() function. |
84 |
|
85 |
- Replaces version separators by index. |
86 |
|
87 |
- RANGE is START[-[END]], i.e. START for one index, START-END for a |
88 |
range of indexes, or START- for up to the last separator. |
89 |
|
90 |
- If RANGE includes empty separators, they are replaced as well. |
91 |
For example, "replace_version_sep 3 - 1.2.3b" outputs "1.2.3-b". |
92 |
|
93 |
- REPL is a replacement string. It can be any string, and will be |
94 |
repeated for each replaced separator. |
95 |
|
96 |
- Multiple pairs of RANGE and REPL can be specified. For example, |
97 |
"replace_version_sep 1 - 3 '~' 1.2.3b" would output "1-2.3~b". |
98 |
|
99 |
- VERSION can be omitted and defaults to PV. |
100 |
|
101 |
- It is not yet entirely clear what should be done in case of |
102 |
overlapping ranges. It could be an error, or the last replacement |
103 |
could win. Similarly, what should be done if there are less |
104 |
separators than specified? (versionator.eclass silently ignores the |
105 |
surplus ones.) |
106 |
|
107 |
|
108 |
Questions: |
109 |
1. Will these three functions be sufficient, or have we overlooked |
110 |
anything important? |
111 |
2. Are the proposed specifications sane? |
112 |
3. Some bikeshedding for the names, especially for the name of the |
113 |
version_replace_separator() function is needed. |
114 |
|
115 |
Ulrich |
116 |
|
117 |
|
118 |
[1] https://bugs.gentoo.org/show_bug.cgi?id=482170 |