[gentoo-commits] proj/pms:eapi-7 commit in: /

[Ulrich Müller]

commit:     c93d358570ce434f444c0ee59999add7bc9d9a58
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Wed Sep 27 21:23:22 2017 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Feb 24 12:55:24 2018 +0000
URL:        https://gitweb.gentoo.org/proj/pms.git/commit/?id=c93d3585

EAPI 7 has version manipulation and comparison functions

Bug: https://bugs.gentoo.org/482170

 eapi-differences.tex |  4 +++
 pkg-mgr-commands.tex | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+)

diff --git a/eapi-differences.tex b/eapi-differences.tex
index 6a2cab7..8deba55 100644
--- a/eapi-differences.tex
+++ b/eapi-differences.tex
@@ -302,6 +302,9 @@ Controllable stripping & \compactfeatureref{dostrip} &
 \t{in_iuse} & \compactfeatureref{in-iuse} &
     No & No & No & Yes & Yes \\
 
+\t{ver_*} commands & \compactfeatureref{ver-commands} &
+    No & No & No & No & Yes \\
+
 \t{unpack} absolute paths & \compactfeatureref{unpack-absolute} &
     No & No & No & Yes & Yes \\
 
@@ -484,6 +487,7 @@ EAPI 7 is EAPI 6 with the following changes:
 \item \t{die} is guaranteed to work in a subshell, \featureref{subshell-die}.
 \item \t{domo} installs to \t{/usr}, \featureref{domo-path}.
 \item Controllable stripping and \t{dostrip}, \featureref{dostrip}.
+\item Version manipulation and comparison commands, \featureref{ver-commands}.
 \end{compactitem}
 
 \ChangeWhenAddingAnEAPI{7}

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index ed3af1b..b49e9b3 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -952,6 +952,86 @@ These functions check whitespace-separated lists for a particular value.
 \item[hasq] Deprecated synonym for \t{has}.
 \end{description}
 
+\subsection{Version manipulation and comparison commands}
+\featurelabel{ver-commands}
+These commands provide utilities for working with version strings. Their availability per EAPI is
+listed in table~\ref{tab:version-commands}.
+
+For the purpose of version manipulation commands, the specification provides a method for splitting
+an arbitrary version string (not necessarily conforming to section~\ref{sec:version-spec}) into
+a series of version components and version separators.
+
+A version component consists either purely of digits (\t{[0-9]+}) or purely of uppercase and
+lowercase ASCII letters (\t{[A-Za-z]+}). A version separator is either a string of any other
+characters (\t{[\textasciicircum A-Za-z0-9]}) or it occurs at the transition between a sequence
+of digits and a sequence of letters, or vice versa. In the latter case, the version separator is
+an empty string.
+
+The version string is processed left-to-right, with the successive version components being assigned
+successive indices starting with 1. The separator following a version component is assigned
+the index of the preceding version component. If the first version component is preceded by
+a non-empty string of version separator characters, this separator is assigned the index 0.
+
+The version components are presumed present if not empty. The version separators between version
+components are always presumed present, even if they are empty. The version separators preceding
+the first version component and following the last are only presumed present if they are not empty.
+
+Whenever the commands support ranges, the range is specified as a non-negative integer, optionally
+followed by a hyphen (\t{-}), which in turn is optionally followed by another non-negative integer.
+
+A single integer specifies a single component or separator index. An integer followed by a hyphen
+specifies all components or separators starting with the one at the specified index. Two integers
+separated by a hyphen specify a range of versions starting at the index specified by the first
+and ending at the second, inclusively.
+
+\begin{description}
+\item[ver_cut] Takes a range as the first argument, and optionally a version string as the second.
+    Prints a substring of the version string starting at the version component specified as start
+    of the range and ending at the version component specified as end of the range. If the version
+    string is not specified, \t{\$\{PVR\}} is used.
+
+    If the range spans outside the present version components, the missing components and separators
+    are presumed empty. In particular, the range starting at zero includes the zeroth version
+    separator if present, and the range spanning past the last version component includes the suffix
+    following it if present. A range that does not intersect with any present version components
+    yields an empty string.
+
+\item[ver_rs] Takes one or more pairs of arguments, optionally followed by a version string.
+    Every argument pair specifies a range and a replacement string. Prints a version string after
+    performing the specified separator substitutions. If the version string is not specified,
+    \t{\$\{PVR\}} is used.
+
+    For every argument pair specified, each of the version separators present at indices specified
+    by the range is replaced with the replacement string, in order. If the range spans outside
+    the range of present version separators, it is silently truncated.
+
+\item[ver_test] Takes two or three arguments. In the 3-argument form, takes an LHS version string,
+    followed by an operator, followed by an RHS version string. In the 2-argument form, the first
+    version string is omitted and \t{\$\{PVR\}} is used as LHS version string. The operator can be
+    \t{-eq} (equal to), \t{-ne} (not equal to), \t{-gt} (greater than), \t{-ge} (greater than or
+    equal to), \t{-lt} (less than) or \t{-le} (less than or equal to). Returns shell true (0) if
+    the specified relation between the LHS and RHS version strings is fulfilled.
+
+    Both version strings must conform to the version specification in
+    section~\ref{sec:version-spec}. Comparison is done using algorithm~\ref{alg:version-comparison}.
+\end{description}
+
+\ChangeWhenAddingAnEAPI{7}
+\begin{centertable}{EAPIs supporting version manipulation commands}
+    \label{tab:version-commands}
+    \begin{tabular}{llll}
+      \toprule
+      \multicolumn{1}{c}{\textbf{EAPI}} &
+      \multicolumn{1}{c}{\textbf{\t{ver_cut}?}} &
+      \multicolumn{1}{c}{\textbf{\t{ver_rs}?}} &
+      \multicolumn{1}{c}{\textbf{\t{ver_test}?}} \\
+      \midrule
+      0, 1, 2, 3, 4, 5, 6 & No  & No  & No  \\
+      7                   & Yes & Yes & Yes \\
+      \bottomrule
+    \end{tabular}
+\end{centertable}
+
 \subsection{Misc commands}
 The following commands are always available in the ebuild environment, but don't really fit in any
 of the above categories. Ebuilds must not run any of these commands once the current phase function