Skip to content

Commit

Permalink
Fix #9507 Describe accurately acceptable package names
Browse files Browse the repository at this point in the history
  • Loading branch information
mpilgrem committed Dec 10, 2023
1 parent eeb99c9 commit d2d7027
Showing 1 changed file with 23 additions and 10 deletions.
33 changes: 23 additions & 10 deletions doc/cabal-package-description-file.rst
Original file line number Diff line number Diff line change
Expand Up @@ -318,20 +318,33 @@ 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/minus character (``-``). A word cannot be
comprised only of the characters ``0`` to ``9``.

Or, expressed in ABNF_:
An alphanumeric character is one in 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::

Expand Down Expand Up @@ -1480,13 +1493,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
Expand Down

0 comments on commit d2d7027

Please sign in to comment.