From 4aa738e08a7ad81aaddc004c10d42a79c0cd0557 Mon Sep 17 00:00:00 2001 From: Mike Pilgrem Date: Sun, 10 Dec 2023 01:02:48 +0000 Subject: [PATCH] Fix #9507 Describe accurately acceptable package names --- doc/buildinfo-fields-reference.rst | 4 +-- doc/cabal-package-description-file.rst | 37 ++++++++++++++++++-------- doc/package-concepts.rst | 2 +- 3 files changed, 29 insertions(+), 14 deletions(-) diff --git a/doc/buildinfo-fields-reference.rst b/doc/buildinfo-fields-reference.rst index 9deea2ba4d3..492ca0163e7 100644 --- a/doc/buildinfo-fields-reference.rst +++ b/doc/buildinfo-fields-reference.rst @@ -134,10 +134,10 @@ hs-string \mathop{\mathord{``}\mathtt{\text{"}}\mathord{"}}{\left\{ {[\mathop{\mathord{``}\mathtt{\text{"}}\mathord{"}}\mathop{\mathord{``}\mathtt{\text{\\}}\mathord{"}}]^c}\mid\left\{ \begin{gathered}\mathop{\mathord{``}\mathtt{\text{\\}\text{&}}\mathord{"}}\\\mathop{\mathord{``}\mathtt{\text{\\}\text{\\}}\mathord{"}}\\\left\{ \mathop{\mathord{``}\mathtt{\text{\\}n}\mathord{"}}\mid\mathop{\mathit{escapes}} \right\}\\\mathop{\mathord{``}\mathtt{\text{\\}}\mathord{"}}[\mathop{\mathord{``}\mathtt{0}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{9}\mathord{"}}]\\\mathop{\mathord{``}\mathtt{\text{\\}o}\mathord{"}}[\mathop{\mathord{``}\mathtt{0}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{7}\mathord{"}}]\\\mathop{\mathord{``}\mathtt{\text{\\}x}\mathord{"}}[\mathop{\mathord{``}\mathtt{0}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{9}\mathord{"}}\mathop{\mathord{``}\mathtt{A}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{F}\mathord{"}}\mathop{\mathord{``}\mathtt{a}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{f}\mathord{"}}]\\\left\{ \mathop{\mathord{``}\mathtt{\text{\\}\text{^}\text{@}}\mathord{"}}\mid\mathop{\mathit{control}} \right\}\\\left\{ \mathop{\mathord{``}\mathtt{\text{\\}NUL}\mathord{"}}\mid\mathop{\mathit{ascii}} \right\}\end{gathered} \right\} \right\}}^\ast_{}\mathop{\mathord{``}\mathtt{\text{"}}\mathord{"}} unqual-name - Unqualified component names are used for package names, component names etc. but not flag names. Unqualified component name consist of components separated by dash, each component is non-empty alphanumeric string, with at least one alphabetic character. In other words, component may not look like a number. + Unqualified component names are used for package names, component names etc. but not flag names. An unqualified component name consists of components separated by a hyphen, each component is a non-empty alphanumeric string, with at least one character that is not the digits ``0`` to ``9``. In other words, a component may not look like a number. .. math:: - {\left({\mathop{\mathit{alpha\text{-}num}}}^\ast_{}\mathop{\mathit{alpha}}{\mathop{\mathit{alpha\text{-}num}}}^\ast_{}\right)}^+_{\mathop{\mathord{``}\mathtt{\text{-}}\mathord{"}}} + {\left({\mathop{\mathit{alpha\text{-}num}}}^\ast_{}{\mathop{\mathit{alpha\text{-}num}}}^{\in {[ \mathord{"}\mathtt{1}\mathord{"} \cdots \mathord{"}\mathtt{9}\mathord{"} ]^c}}_{}{\mathop{\mathit{alpha\text{-}num}}}^\ast_{}\right)}^+_{\mathop{\mathord{``}\mathtt{\text{-}}\mathord{"}}} module-name Haskell module name as recognized by Cabal parser. diff --git a/doc/cabal-package-description-file.rst b/doc/cabal-package-description-file.rst index ae07f3ff3bc..42657b1b7d4 100644 --- a/doc/cabal-package-description-file.rst +++ b/doc/cabal-package-description-file.rst @@ -318,24 +318,39 @@ describe the package as a whole: tools require the package-name specified for this field to match the package description's file-name :file:`{package-name}.cabal`. - Package names are case-sensitive and must match the regular expression - (i.e. alphanumeric "words" separated by dashes; each alphanumeric - word must contain at least one letter): - ``[[:digit:]]*[[:alpha:]][[:alnum:]]*(-[[:digit:]]*[[:alpha:]][[:alnum:]]*)*``. + A valid package name comprises an alphanumeric 'word'; or two or more + such words separated by a hyphen character (``-``). A word cannot be + comprised only of the digits ``0`` to ``9``. - Or, expressed in ABNF_: + An alphanumeric character belongs to one of the Unicode Letter categories + (Lu (uppercase), Ll (lowercase), Lt (titlecase), Lm (modifier), or + Lo (other)) or Number categories (Nd (decimal), Nl (letter), or No (other)). + + Package names are case-sensitive. + + Expressed as a regular expression: + + ``[0-9]*[\p{L}\p{N}-[0-9]][\p{L}\p{N}]*(-[0-9]*[\p{L}\p{N}-[0-9]][\p{L}\p{N}]*)*`` + + Expressed in ABNF_: .. code-block:: abnf package-name = package-name-part *("-" package-name-part) - package-name-part = *DIGIT UALPHA *UALNUM + package-name-part = *DIGIT UALPHANUM-NOT-DIGIT *UALNUM - UALNUM = UALPHA / DIGIT - UALPHA = ... ; set of alphabetic Unicode code-points + DIGIT = %x30-39 ; 0-9 + + UALNUM = UALPHANUM-NOT-DIGIT / DIGIT + UALPHANUM-NOT-DIGIT = ... ; set of Unicode code-points in Letter or + ; Number categories, other than the DIGIT + ; code-points .. note:: - Hackage restricts package names to the ASCII subset. + Hackage will not accept package names that use alphanumeric characters + other than ``A`` to ``Z``, ``a`` to ``z``, and ``0`` to ``9`` + (the ASCII subset). .. pkg-field:: version: numbers (required) @@ -1480,13 +1495,13 @@ system-dependent values for these fields. Version constraints use the operators ``==, >=, >, <, <=`` and a version number. Multiple constraints can be combined using ``&&`` or ``||``. - + .. Note:: Even though there is no ``/=`` operator, by combining operators we can skip over one or more versions, to skip a deprecated version or to skip versions that narrow the constraint solving more than we'd like. - + For example, the ``time =1.12.*`` series depends on ``base >=4.13 && <5`` but ``time-1.12.3`` bumps the lower bound on base to ``>=4.14``. If we still want to compile with a ``ghc-8.8.*`` version of GHC that ships with diff --git a/doc/package-concepts.rst b/doc/package-concepts.rst index 25cfeb13fba..d0586b8ec93 100644 --- a/doc/package-concepts.rst +++ b/doc/package-concepts.rst @@ -43,7 +43,7 @@ Package names and versions All packages have a name, e.g. "HUnit". Package names are assumed to be unique. Cabal package names may contain letters, numbers and hyphens, but not spaces and may also not contain a hyphened section consisting of -only numbers. The namespace for Cabal packages is flat, not +only of the digits ``0`` to ``9``. The namespace for Cabal packages is flat, not hierarchical. Packages also have a version, e.g "1.1". This matches the typical way in