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 938D41396D0 for ; Mon, 9 Oct 2017 17:31:18 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id F0199E0DD3; Mon, 9 Oct 2017 17:31:14 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) (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 BBD90E0DD3 for ; Mon, 9 Oct 2017 17:31:14 +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 7AB3A33BEC7 for ; Mon, 9 Oct 2017 17:31:11 +0000 (UTC) Received: from localhost.localdomain (localhost [IPv6:::1]) by oystercatcher.gentoo.org (Postfix) with ESMTP id D85AF90A0 for ; Mon, 9 Oct 2017 17:31:09 +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: <1507569001.ef92bc885bcd57c6c129aeb65242d5f295d5f7bf.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: ef92bc885bcd57c6c129aeb65242d5f295d5f7bf X-VCS-Branch: eapi-7 Date: Mon, 9 Oct 2017 17:31:09 +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: b06d9660-ce35-48bb-82b8-3fcebcb6093a X-Archives-Hash: a9a8b01fc6f6b2efb53fd4b502df6392 commit: ef92bc885bcd57c6c129aeb65242d5f295d5f7bf Author: Michał Górny gentoo org> AuthorDate: Wed Sep 27 21:23:22 2017 +0000 Commit: Ulrich Müller gentoo org> CommitDate: Mon Oct 9 17:10:01 2017 +0000 URL: https://gitweb.gentoo.org/proj/pms.git/commit/?id=ef92bc88 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 c68fffa..9f3f8be 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 495a4ce..5b65477 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} +\subsection{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} + \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