Add sized primitive literal syntax

Adds a new LANGUAGE pragma ExtendedLiterals, which enables defining
unboxed numeric literals such as `0xFF#Word8 :: Word8#`.

Implements GHC proposal 0451:
https://github.com/ghc-proposals/ghc-proposals/blob/b384a538b34f79d18a0201455b7b3c473bc8c936/proposals/0451-sized-literals.rst

Fixes #21422.

Bumps haddock submodule.

Co-authored-by: Krzysztof Gogolewski <krzysztof.gogolewski@tweag.io>

5 files changed, 58 insertions, 0 deletions

diff --git a/docs/users_guide/9.8.1-notes.rst b/docs/users_guide/9.8.1-notes.rst
index 9f2d51d329..e7e9acdf75 100644
--- a/docs/users_guide/9.8.1-notes.rst
+++ b/docs/users_guide/9.8.1-notes.rst
@@ -6,6 +6,10 @@ Version 9.8.1
 Language
 ~~~~~~~~
 
+- There is a new extension :extension:`ExtendedLiterals`, which enables
+  sized primitive literals, e.g. ``123#Int8`` is a literal of type ``Int8#``.
+  See the GHC proposal `#451 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0451-sized-literals.rst>`_.
+
 Compiler
 ~~~~~~~~
 
diff --git a/docs/users_guide/exts/extended_literals.rst b/docs/users_guide/exts/extended_literals.rst
new file mode 100644
index 0000000000..ac61f2d410
--- /dev/null
+++ b/docs/users_guide/exts/extended_literals.rst
@@ -0,0 +1,47 @@
+.. _extended-literals:
+
+Sized primitive literal syntax
+------------------------------
+
+.. extension:: ExtendedLiterals
+    :shortdesc: Enable numeric literal postfix syntax for unboxed integers.
+
+    :since: 9.8.1
+
+    Allows defining unboxed numeric primitive values through ``#Type`` suffixes
+    on numeric literals e.g. ``0xFF#Word8 :: Word8#``.
+
+The :extension:`MagicHash` extension enables some new literals, including ``3#
+:: Int#``, ``3## :: Word#``. This does not extend to all unboxed values. For
+example, there is no literal syntax for ``Word8#``: you must write something
+such as ``wordToWord8 (3## :: Word#) :: Word8#``.
+
+:extension:`ExtendedLiterals` enables further syntax for defining primitive
+numeric literals. Suffix any Haskell integer lexeme with a hash sign ``#``
+followed by a primitive numeric type (without its hash suffix) to obtain a value
+of that type. For example, ``0xFF#Word8 :: Word8#``. There must be no spaces
+between the parts of the literal.
+
+The primitive numeric types allowed are:
+
+- ``Int8#``
+- ``Int16#``
+- ``Int32#``
+- ``Int64#``
+- ``Int#``
+- ``Word8#``
+- ``Word16#``
+- ``Word32#``
+- ``Word64#``
+- ``Word#``
+
+All types permit any nonnegative Haskell integer lexeme, e.g. ``70``, ``0x2A``,
+``0o1276``, ``0b1010`` (with :extension:`BinaryLiterals`). The signed ``Int``
+types also permit negative integer lexemes. Defining a literal with a value that
+can't fit in its requested type will emit an overflow warning by default, the
+same as boxed numeric literals.
+
+As with :extension:`MagicHash`, this extension does not bring anything into
+scope, nor change any semantics. The syntax only applies to numeric literals.
+You may want to import ``GHC.Exts`` (see :ref:`primitives`) to refer to the
+types of the literals you define.
diff --git a/docs/users_guide/exts/literals.rst b/docs/users_guide/exts/literals.rst
index fbb613333f..6061bdfec7 100644
--- a/docs/users_guide/exts/literals.rst
+++ b/docs/users_guide/exts/literals.rst
@@ -10,6 +10,7 @@ Literals
     binary_literals
     hex_float_literals
     num_decimals
+    extended_literals
     numeric_underscores
     overloaded_strings
     overloaded_labels
diff --git a/docs/users_guide/exts/primitives.rst b/docs/users_guide/exts/primitives.rst
index 9caab6b146..ef8cb32523 100644
--- a/docs/users_guide/exts/primitives.rst
+++ b/docs/users_guide/exts/primitives.rst
@@ -19,6 +19,9 @@ your program, you must first import ``GHC.Exts`` to bring them into
 scope. Many of them have names ending in ``#``, and to mention such names
 you need the :extension:`MagicHash` extension.
 
+To enable defining literals for other primitive data types, see the
+:extension:`ExtendedLiterals` extension.
+
 The primops make extensive use of `unboxed types <#glasgow-unboxed>`__
 and `unboxed tuples <#unboxed-tuples>`__, which we briefly summarise
 here.
diff --git a/docs/users_guide/exts/stolen_syntax.rst b/docs/users_guide/exts/stolen_syntax.rst
index 746daebd7c..39747bc745 100644
--- a/docs/users_guide/exts/stolen_syntax.rst
+++ b/docs/users_guide/exts/stolen_syntax.rst
@@ -80,6 +80,9 @@ The following syntax is stolen:
 ⟨varid⟩, ``#``\ ⟨char⟩, ``#``, ⟨string⟩, ``#``, ⟨integer⟩, ``#``, ⟨float⟩, ``#``, ⟨float⟩, ``##``
     Stolen by: :extension:`MagicHash`
 
+⟨integer⟩, ``#(Int|Word)(8|16|32|64)?``
+    Stolen by: :extension:`ExtendedLiterals`
+
 ``(#``, ``#)``
     Stolen by: :extension:`UnboxedTuples`