path: root/names.tex

\chapter{Names and Versions}

\section{Restrictions upon Names}

No name may be empty. Package managers must not impose fixed upper boundaries upon the length of any
name. A package manager should indicate or reject any name that is invalid according to these rules.

\subsection{Category Names}
A category name may contain any of the characters [\t{A-Za-z0-9+\_.-}]. It must not begin with
a hyphen or a dot.

\note A hyphen is \i{not} required because of the \t{virtual} category. Usually, however, category
names will contain a hyphen.

\subsection{Package Names}
A package name may contain any of the characters [\t{A-Za-z0-9+\_-}]. It must not begin with a
hyphen, and must not end in a hyphen followed by one or more digits.

\note A package name does not include the category. The term \i{qualified package name} is used
where a \t{category/package} pair is meant.

\subsection{Slot Names}
\label{sec:slot-names}
A slot name may contain any of the characters [\t{A-Za-z0-9+\_.-}]. It must not begin with a
hyphen or a dot.

\subsection{USE Flag Names}
A USE flag name may contain any of the characters [\t{A-Za-z0-9+\_@-}]. It must begin with an
alphanumeric character. Underscores should be considered reserved for \t{USE\_EXPAND}, as
described in section~\ref{sec:use-iuse-handling}.

\note The at-sign is required for \t{LINGUAS}.

\subsection{Repository Names}
\label{sec:repository-names}
A repository name may contain any of the characters [\t{A-Za-z0-9\_-}]. It must not begin with a
hyphen.

\subsection{Keyword Names}
\label{sec:keyword-names}
A keyword name may contain any of the characters [\t{A-Za-z0-9\_-}]. It must not begin with a
hyphen. In contexts where it makes sense to do so, a keyword name may be prefixed by
a tilde or a hyphen. In \t{KEYWORDS}, \t{-*} is also acceptable as a keyword, to indicate that
a package will only work on listed targets.

A tilde prefixed keyword is, by convention, used to indicate a less stable package. It is generally
assumed that any user accepting keyword \t{\textasciitilde{}foo} will also accept \t{foo}.

The exact meaning of any keywords value is beyond the scope of this specification.

\section{Version Specifications}
The package manager must not impose fixed limits upon the number of version components. Package
managers should indicate or reject any version that is invalid according to these rules.

A version starts with the number part, which is in the form \t{[0-9]+($\backslash$.[0-9]+)*} (a positive
integer, followed by zero or more dot-prefixed positive integers).

This may optionally be followed by one of \t{[a-z]} (a lowercase letter).

This may be followed by zero or more of the suffixes \t{\_alpha}, \t{\_beta}, \t{\_pre},
\t{\_rc} or \t{\_p}, which themselves may be suffixed by an optional integer.

\IFKDEBUILDELSE
{
    \featurelabel{scm} \label{scm-versions} In ebuilds using EAPIs listed in
    table~\ref{tab:scm-table} as requiring support for the \t{-scm} suffix, the preceding version
    syntax may be either replaced or suffixed by a \t{scm} part. If both a ``normal'' version and a
    \t{scm} part are present, they must be separated by a hyphen.
}{
}

This may optionally be followed by the suffix \t{-r} followed immediately by an integer (the
``revision number''). If this suffix is not present, it is assumed to be \t{-r0}.

\IFKDEBUILDELSE
{
    \begin{centertable}{EAPIs requiring \t{scm} support} \label{tab:scm-table}
    \begin{tabular}{ l l }
        \toprule
        \multicolumn{1}{c}{\textbf{EAPI}} &
        \multicolumn{1}{c}{\textbf{Requires \t{scm} support?}} \\
        \midrule
    \t{0} & No \\
    \t{1} & No \\
    \t{kdebuild-1} & Yes \\
    \t{2} & No \\
    \t{3} & No \\
    \t{4} & No \\
    \bottomrule
    \end{tabular}
    \end{centertable}
}{
}

\section{Version Comparison}

Version specifications are compared component by component, moving from left to right,
as detailed in Algorithm~\ref{alg:version-comparison} and sub-algorithms.
If a sub-algorithm returns a decision, then that is the result of the whole comparison;
if it terminates without returning a decision, the process continues from the point
from which it was invoked.

\begin{algorithm}
\caption{Version comparison top-level logic} \label{alg:version-comparison}
\IFKDEBUILDELSE{
  \begin{algorithmic}[1]
    \STATE let $A$ and $B$ be the versions to be compared
    \IF{$A$ and $B$ both begin with \t{scm}}
      \STATE compare revision components using Algorithm~\ref{alg:version-comparison-revision}
    \ELSIF{$A$ begins with \t{scm}}
      \RETURN $A>B$
    \ELSIF{$B$ begins with \t{scm}}
      \RETURN $A<B$
    \ELSE
      \STATE compare numeric components using Algorithm~\ref{alg:version-comparison-numeric}
      \STATE compare letter components using Algorithm~\ref{alg:version-comparison-letter}
      \STATE compare suffixes using Algorithm~\ref{alg:version-comparison-suffix}
      \STATE compare revision components using Algorithm~\ref{alg:version-comparison-revision}
    \ENDIF
    \RETURN $A=B$
  \end{algorithmic}
}{
  \begin{algorithmic}[1]
    \STATE let $A$ and $B$ be the versions to be compared
    \STATE compare numeric components using Algorithm~\ref{alg:version-comparison-numeric}
    \STATE compare letter components using Algorithm~\ref{alg:version-comparison-letter}
    \STATE compare suffixes using Algorithm~\ref{alg:version-comparison-suffix}
    \STATE compare revision components using Algorithm~\ref{alg:version-comparison-revision}
    \RETURN $A=B$
  \end{algorithmic}
}
\end{algorithm}

\begin{algorithm}
\caption{Version comparison logic for numeric components} \label{alg:version-comparison-numeric}
\begin{algorithmic}[1]
  \STATE define the notations $An_k$ and $Bn_k$ to mean the $k$\textsuperscript{th} numeric component of $A$ and $B$ respectively, using $0$-based indexing
  \IF{$An_0>Bn_0$ using integer comparison}
    \RETURN $A>B$
  \ELSIF{$An_0<Bn_0$ using integer comparison}
    \RETURN $A<B$
  \ENDIF
  \STATE let $Ann$ be the number of numeric components of $A$
  \STATE let $Bnn$ be the number of numeric components of $B$
  \FORALL{$i$ such that $i\geq1$ and $i<Ann$ and $i<Bnn$, in ascending order}
    \STATE compare $An_i$ and $Bn_i$ using Algorithm~\ref{alg:version-comparison-numeric-nonfirst}
  \ENDFOR
  \IF{$Ann>Bnn$}
    \IFKDEBUILDELSE{
      \IF{$B$ has any suffixes and no letter, and its first suffix is \t{-scm}}
        \RETURN $A<B$
      \ELSE
        \RETURN $A>B$
      \ENDIF
    }{
      \RETURN $A>B$
    }
  \ELSIF{$Ann<Bnn$}
    \IFKDEBUILDELSE{
      \IF{$A$ has any suffixes and no letter, and its first suffix is \t{-scm}}
        \RETURN $A>B$
      \ELSE
        \RETURN $A<B$
      \ENDIF
    }{
      \RETURN $A<B$
    }
  \ENDIF
\end{algorithmic}
\end{algorithm}

\begin{algorithm}
\caption{Version comparison logic for each numeric component after the first} \label{alg:version-comparison-numeric-nonfirst}
\begin{algorithmic}[1]
  \IF{either $An_i$ or $Bn_i$ has a leading \t{0}}
    \STATE let $An'_i$ be $An_i$ with any trailing \t{0}s removed
    \STATE let $Bn'_i$ be $Bn_i$ with any trailing \t{0}s removed
    \IF{$An'_i>Bn'_i$ using ASCII stringwise comparison}
      \RETURN $A>B$
    \ELSIF{$An'_i<Bn'_i$ using ASCII stringwise comparison}
      \RETURN $A<B$
    \ENDIF
  \ELSE
    \IF{$An_i>Bn_i$ using integer comparison}
      \RETURN $A>B$
    \ELSIF{$An_i<Bn_i$ using integer comparison}
      \RETURN $A<B$
    \ENDIF
  \ENDIF
\end{algorithmic}
\end{algorithm}

\begin{algorithm}
\caption{Version comparison logic for letter components} \label{alg:version-comparison-letter}
\begin{algorithmic}[1]
  \STATE let $Al$ be the letter component of $A$ if any, \IFKDEBUILDELSE{otherwise \t{zz} if $A$ has any suffixes and its first suffix is \t{-scm}, }{}otherwise the empty string
  \STATE let $Bl$ be the letter component of $B$ if any, \IFKDEBUILDELSE{otherwise \t{zz} if $B$ has any suffixes and its first suffix is \t{-scm}, }{}otherwise the empty string
  \IF{$Al>Bl$ using ASCII stringwise comparison}
    \RETURN $A>B$
  \ELSIF{$Al<Bl$ using ASCII stringwise comparison}
    \RETURN $A<B$
  \ENDIF
\end{algorithmic}
\end{algorithm}

\begin{algorithm}
\caption{Version comparison logic for suffixes} \label{alg:version-comparison-suffix}
\begin{algorithmic}[1]
  \STATE define the notations $As_k$ and $Bs_k$ to mean the $k$\textsuperscript{th} suffix of $A$ and $B$ respectively, using $0$-based indexing
  \STATE let $Asn$ be the number of suffixes of $A$
  \STATE let $Bsn$ be the number of suffixes of $B$
  \FORALL{$i$ such that $i\geq0$ and $i<Asn$ and $i<Bsn$, in ascending order}
    \STATE compare $As_i$ and $Bs_i$ using Algorithm~\ref{alg:version-comparison-suffix-each}
  \ENDFOR
  \IF{$Asn>Bsn$}
    \IF{$As_{Bsn}$ is of type \t{\_p} \IFKDEBUILDELSE{or \t{-scm}}{}}
      \RETURN $A>B$
    \ELSE
      \RETURN $A<B$
    \ENDIF
  \ELSIF{$Asn<Bsn$}
    \IF{$Bs_{Asn}$ is of type \t{\_p} \IFKDEBUILDELSE{or \t{-scm}}{}}
      \RETURN $A<B$
    \ELSE
      \RETURN $A>B$
    \ENDIF
  \ENDIF
\end{algorithmic}
\end{algorithm}

\begin{algorithm}
\caption{Version comparison logic for each suffix} \label{alg:version-comparison-suffix-each}
\begin{algorithmic}[1]
  \IF{$As_i$ and $Bs_i$ are of the same type (\t{\_alpha} vs \t{\_beta} etc)}
    \STATE let $As'_i$ be the integer part of $As_i$ if any, otherwise \IFKDEBUILDELSE{as specified by Algorithm~\ref{alg:version-comparison-suffix-missingint}}{\t{0}}
    \STATE let $Bs'_i$ be the integer part of $Bs_i$ if any, otherwise \IFKDEBUILDELSE{as specified by Algorithm~\ref{alg:version-comparison-suffix-missingint}}{\t{0}}
    \IF{$As'_i>Bs'_i$, using integer comparison \IFKDEBUILDELSE{and with $\infty$ greater than any integer}{}}
      \RETURN $A>B$
    \ELSIF{$As'_i<Bs'_i$, using integer comparison \IFKDEBUILDELSE{and with $\infty$ greater than any integer}{}}
      \RETURN $A<B$
    \ENDIF
  \ELSIF{the type of $As_i$ is greater than the type of $Bs_i$ using the ordering $\mbox{\t{\_alpha}}<\mbox{\t{\_beta}}<\mbox{\t{\_pre}}<\mbox{\t{\_rc}}<\mbox{\t{\_p}}\IFKDEBUILDELSE{<\mbox{\t{-scm}}}{}$}
    \RETURN $A>B$
  \ELSE
    \RETURN $A<B$
  \ENDIF
\end{algorithmic}
\end{algorithm}

\IFKDEBUILDELSE
{
  \begin{algorithm}
  \caption{Deciding an unspecified integer part of a suffix component, for comparison purposes} \label{alg:version-comparison-suffix-missingint}
  \begin{algorithmic}[1]
    \STATE let $X$ refer to either $A$ or $B$, whichever version contains the suffix under question
    \IF{$i+1<Xsn$ and $Xs_{i+1}$ is of type \t{-scm}}
      \STATE let $Xs'_i$ be $\infty$
    \ELSE
      \STATE let $Xs'_i$ be \t{0}
    \ENDIF
  \end{algorithmic}
  \end{algorithm}
}{
}

\begin{algorithm}
\caption{Version comparison logic for revision components} \label{alg:version-comparison-revision}
\begin{algorithmic}[1]
  \STATE let $Ar$ be the integer part of the revision component of $A$ if any, otherwise $\t{0}$
  \STATE let $Br$ be the integer part of the revision component of $B$ if any, otherwise $\t{0}$
  \IF{$Ar>Br$ using integer comparison}
    \RETURN $A>B$
  \ELSIF{$Ar<Br$ using integer comparison}
    \RETURN $A<B$
  \ENDIF
\end{algorithmic}
\end{algorithm}

\section{Uniqueness of versions}

No two packages in a given repository may have the same qualified package name and equal versions.
For example, a repository may not contain more than one of \t{foo-bar/baz-1.0.2},
\t{foo-bar/baz-1.0.2-r0} and \t{foo-bar/baz-1.000.2}.

% vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en :

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pms"
%%% LaTeX-indent-level: 4
%%% LaTeX-item-indent: 0
%%% TeX-brace-indent-level: 4
%%% End: