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:

Type	s	c	s	c	s	c	s	c	s	c
Index	0	1	1	2	2	3	3	4	4	5
`1.2.3`		`1`	`.`	`2`	`.`	`3`
`1.2b_alpha4`		`1`	`.`	`2`		`b`	`_`	`alpha`		`4`
`.11.`	`.`	`11`	`.`

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

Function Usage Description

Function	Usage	Description
`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.

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.