From d3d055b8d10a549e42d18ae4859bc902f939f534 Mon Sep 17 00:00:00 2001
From: Galen Huntington <galen@alumni.reed.edu>
Date: Thu, 14 May 2020 23:17:49 -0400
Subject: [PATCH] Clarify pitfalls of NegativeLiterals; see #18022.
---
docs/users_guide/exts/negative_literals.rst | 22 ++++++++++++++-------
1 file changed, 15 insertions(+), 7 deletions(-)
diff --git a/docs/users_guide/exts/negative_literals.rst b/docs/users_guide/exts/negative_literals.rst
index 27a31c9b61e..74fcc87a214 100644
--- a/docs/users_guide/exts/negative_literals.rst
+++ b/docs/users_guide/exts/negative_literals.rst
@@ -8,16 +8,24 @@ Negative literals
:since: 7.8.1
- Enable the use of un-parenthesized negative numeric literals.
+ Enable negative numeric literals.
The literal ``-123`` is, according to Haskell98 and Haskell 2010,
+two tokens, a unary minus (``-``) and the number 123, and is
desugared as ``negate (fromInteger 123)``. The language extension
-:extension:`NegativeLiterals` means that it is instead desugared as
-``fromInteger (-123)``.
+:extension:`NegativeLiterals` causes it to be treated as a single
+token and desugared as ``fromInteger (-123)``.
-This can make a difference when the positive and negative range of a
-numeric data type don't match up. For example, in 8-bit arithmetic -128
-is representable, but +128 is not. So ``negate (fromInteger 128)`` will
-elicit an unexpected integer-literal-overflow message.
+This can be useful when the positive and negative range of a numeric
+data type don't match up. For example, in 8-bit arithmetic -128
+is representable, but +128 is not. So ``negate (fromInteger 128)``
+will elicit an unexpected integer-literal-overflow message.
+Whitespace can be inserted, as in ``- 123``, to force interpretation
+as two tokens.
+
+One pitfall is that with :extension:`NegativeLiterals`, ``x-1`` will
+be parsed as ``x`` applied to the argument ``-1``, which is usually
+not what you want. ``x - 1`` or even ``x- 1`` can be used instead
+for subtraction.
--
GitLab