From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id 0B8991382C5 for ; Thu, 5 Apr 2018 16:57:53 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 1F211E0848; Thu, 5 Apr 2018 16:57:52 +0000 (UTC) Received: from smtp.gentoo.org (dev.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id DA254E0848 for ; Thu, 5 Apr 2018 16:57:51 +0000 (UTC) Received: from oystercatcher.gentoo.org (oystercatcher.gentoo.org [148.251.78.52]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id 243C1335C7D for ; Thu, 5 Apr 2018 16:57:50 +0000 (UTC) Received: from localhost.localdomain (localhost [IPv6:::1]) by oystercatcher.gentoo.org (Postfix) with ESMTP id 6F79A266 for ; Thu, 5 Apr 2018 16:57:47 +0000 (UTC) From: "Ulrich Müller" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Ulrich Müller" Message-ID: <1522946897.c9c5a2f0cf7671d73a78a544d28c361ecd5a2b3c.ulm@gentoo> Subject: [gentoo-commits] proj/pms:eapi-7 commit in: / X-VCS-Repository: proj/pms X-VCS-Files: eapi-differences.tex pkg-mgr-commands.tex X-VCS-Directories: / X-VCS-Committer: ulm X-VCS-Committer-Name: Ulrich Müller X-VCS-Revision: c9c5a2f0cf7671d73a78a544d28c361ecd5a2b3c X-VCS-Branch: eapi-7 Date: Thu, 5 Apr 2018 16:57:47 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Archives-Salt: 35799611-d665-4a19-97e1-e393b1da5b60 X-Archives-Hash: 05b8379f182f2cf95aca1835b6c7a602 commit: c9c5a2f0cf7671d73a78a544d28c361ecd5a2b3c Author: Michał Górny gentoo org> AuthorDate: Wed Sep 27 21:23:22 2017 +0000 Commit: Ulrich Müller gentoo org> CommitDate: Thu Apr 5 16:48:17 2018 +0000 URL: https://gitweb.gentoo.org/proj/pms.git/commit/?id=c9c5a2f0 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 a203f89..a626b74 100644 --- a/eapi-differences.tex +++ b/eapi-differences.tex @@ -290,6 +290,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 \\ @@ -468,6 +471,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 f84f13d..09515ef 100644 --- a/pkg-mgr-commands.tex +++ b/pkg-mgr-commands.tex @@ -922,6 +922,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 an unsigned integer, optionally +followed by a hyphen (\t{-}), which in turn is optionally followed by another unsigned 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