[gentoo-pms] [PATCH 06/28] EAPI 7 has version manipulation and comparison functions

[Michał Górny]

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 44869c0..a56f1ff 100644
--- a/eapi-differences.tex
+++ b/eapi-differences.tex
@@ -41,6 +41,9 @@ of this document for a complete table of previous EAPIs.
 \bottomrule
 \endlastfoot
 
+\t{ver_*} functions & \compactfeatureref{ver-functions} &
+    No & No & No & No & Yes \\
+
 \t{package.mask} directory & \compactfeatureref{package-mask-dir} &
     No & No & No & No & Yes \\
 
@@ -383,6 +386,7 @@ EAPI 7 is EAPI 6 with the following changes:
 \item \t{package.mask}, \t{package.use}, \t{use.*} and \t{package.use.*} in a profile can be
     directories, \featureref{profile-file-dirs}.
 \item \t{dohtml} banned, \featureref{banned-commands}.
+\item Version manipulation and comparison functions added, \featureref{ver-functions}.
 \end{compactitem}
 
 \ChangeWhenAddingAnEAPI{7}
diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index e8a6555..15bfcde 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -817,6 +817,86 @@ These functions check whitespace-separated lists for a particular value.
 \item[hasq] Deprecated synonym for \t{has}.
 \end{description}
 
+\subsubsection{Version manipulation and comparison commands}
+\featurelabel{ver-functions}
+Those functions provide routines to work with version strings. Their availability per EAPI is listed
+in table~\ref{tab:version-functions}.
+
+For the purpose of version manipulation functions, the specification provides a method for splitting
+an arbitrary version string (not necessarily conforming to \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 a combination of
+uppercase and lowercase letters (\t{[a-zA-Z]+}). A version separator is either a string of any other
+characters (\t{[\textasciicircum 0-9a-zA-Z]}) 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-null 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 functions 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 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 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 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, it takes a LHS version string,
+    followed by an operator, followed by RHS version string. In the 2-argument form, the first
+    version string is omitted and \t{\$\{PVR\}} is used as LHS version string. Returns 0
+    if the specified relation between LHS and RHS version strings is true.
+
+    The operator can be \t{-lt}, \t{-le}, \t{-eq}, \t{-ne}, \t{-ge} and \t{-gt} to test whether
+    LHS is respectively older than, older or equal, equal, not equal, newer or equal, and newer
+    than RHS. Both version strings must conform to the version specification
+    at~\ref{sec:version-spec}, the comparison is done using algorithm~\ref{alg:version-comparison}.
+\end{description}
+
+\ChangeWhenAddingAnEAPI{7}
+\begin{centertable}{EAPIs supporting version manipulation commands}
+    \label{tab:version-functions}
+    \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}
+
 \subsubsection{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
-- 
2.14.2