Version functions reference

-inherit eapi7-ver - MY_PN="Foo" # Replace the second period separator in PV with - MY_PV=$(ver_rs 2 '-') @@ -787,24 +784,21 @@ switches to a format like Foo-1.3-4.5.tar.bz2 (yes, this really happens).

-It is also possible to use bash substitution to achieve the same effect (this is -how eapi7-ver works internally), but this is complicated, error prone and hard -to read. +It is also possible to use bash substitution to achieve the same effect, but +this is complicated, error-prone and hard to read.

Some ebuilds use calls to sed, awk and / or cut to do this. This must not be done for any new code and should be fixed to use -built-in version manipulation commands (for EAPI 7 or later), Bash substitution, -or in older EAPIs before 7, eapi7-ver. Global scope non-Bash code is -strongly discouraged. +the built-in version manipulation commands or Bash substitution. Global scope +non-Bash code is strongly discouraged.

-The ver_ functions are used extract particular components -from a version string. See man eapi7-ver.eclass and the eclass source code -for further documentation and examples. A brief summary of the functions -follows. +The ver_ functions are used extract particular components from a version +string. See for further +documentation and examples. A brief summary of the functions follows.

diff --git a/function-reference/text.xml b/function-reference/text.xml index d8e844f..efabc3d 100644 --- a/function-reference/text.xml +++ b/function-reference/text.xml @@ -23,5 +23,6 @@ The following functions are available for use in ebuilds: + diff --git a/function-reference/version-functions/text.xml b/function-reference/version-functions/text.xml new file mode 100644 index 0000000..bf05ccc --- /dev/null +++ b/function-reference/version-functions/text.xml @@ -0,0 +1,219 @@ + + + +Version functions reference + + +

+EAPI 7 introduced three commands for common version number operations: +

+ +

ver_cut obtains substrings of a version string
ver_rs replaces separators in a version string
ver_test compares two versions

+ + +

+Version strings + + +

+The functions support arbitrary version strings consisting of version +components interspersed with (possibly empty) version separators. +

+ +

+A version component can either consist purely of digits ([0-9]+) or +purely of uppercase and lowercase letters ([A-Za-z]+). A version +separator is either a string of any other characters ([^A-Za-z0-9]+), +or it occurs at the transition between a sequence of letters and a sequence +of digits, or vice versa. In the latter case, the version separator is an +empty string. +

+ +

+The version is processed left-to-right, and each successive component is +assigned numbers starting with 1. The components are either split on version +separators or on boundaries between digits and letters (in which case the +separator between the components is empty). Version separators are assigned +numbers starting with 1 for the separator between 1st and 2nd components. +As a special case, if the version string starts with a separator, it is +assigned index 0. +

+ +

+Examples: +

+ +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + 1.2.3 + + 1 + . + 2 + . + 3 + + + + + + + 1.2b_alpha4 + + 1 + . + 2 + + b + _ + alpha + + 4 + + + .11. + . + 11 + . + + + + + + + + +

Type	s	c	s	c	s	c	s	c	s	c
Index	0	1	1	2	2	3	3	4	4	5

+ + + + +

+Ranges + + +

+A range can be specified as m for the mth version component, +m- for all components starting with mth, or m-n +for components starting at mth and ending at nth (inclusive). +If the range spans outside the version string, it is silently truncated. +

+ + +

+ +

+Functions + + + + + + + + + + + ver_cut + + + range [version] + + +

+ Print the substring of the version string containing components defined + by the range and the version separators between them. Processes + version if specified, ${PV} otherwise. +

+ See the introductory section for the syntax of versions and ranges. +

+ + + + + ver_rs + + + range repl [range repl...] [version] + + +

+ Print the version string after substituting the specified version + separators at range with repl (string). Multiple + range repl pairs can be specified. Processes version + if specified, ${PV} otherwise. +

+ See the introductory section for the syntax of versions and ranges. +

+ + + + + ver_test + + + [v1] op v2 + + +

+ Check if the relation v1 op v2 is true. If v1 is not + specified, default to ${PVR}. op can be -gt, + -ge, -eq, -ne, -le, or -lt. + The operators have their usual meaning as in test(1), i.e. the comparison + is true if v1 is greater-than, greater-than-or-equal, equal, + not-equal, less-than-or-equal, or less-than v2. +

+ Both versions v1 and v2 must conform to the + + PMS version syntax (with optional revision parts), and the + comparison is performed according to the + + algorithm specified in the PMS. +

+ + +

+ Function +	+ Usage +	+ Description +

+ + +

+ + diff --git a/general-concepts/portage-cache/text.xml b/general-concepts/portage-cache/text.xml index 2b40d26..ad2b391 100644 --- a/general-concepts/portage-cache/text.xml +++ b/general-concepts/portage-cache/text.xml @@ -30,13 +30,11 @@ fi

-However, the following is legal, since eapi7-ver.eclass works upon -PV, PV, and PN are both static: +However, the following is legal, since the ver_test function works upon +PV, and the PV and PN variables are both static: