Fix the documentation for Data.Oldlist.{lines,unlines}
Issues
While assisting @kozross on documentation for his text-ascii package, he reported several inaccuracies of the documentation for the lines
and unlines
functions:
-
unlines
claims to be the inverse operation tolines
, but unfortunately this is not true with the current implementation. For example:
λ❯ string = "catboy goes nyan"
λ❯ string == (unlines $ lines string)
False
- The
lines
documentation starts with the following sentence:
'lines' breaks a string up into a list of strings at newline characters.
This is a rather unfortunate wording, with respect to the nature of character and sequences in Unicode. We call newline
a character whilst it is a sequence (that happens to be comprised of one character, but Windows users will tell you that \r\n
is anything but one character).
- We do not disclose that we do not use any kind of platform-specific newline sequence (despite having users running GHC on multiple platforms encoding the newline sequence differently). We use and match on the
LF
character, whose hex representation is0x0a
. I do not see any reason to lie to our users like that, this is certainly something that will come to bite us someday.
Proposed changes
- Remove the "inverse" word, as it is misleading, since
unlines . lines /= id
. Explain the real behaviour - Change the usage of
newline character
with something that better reflects the reality of the Unicode world. - Explicitly say that we split and join the strings on the
\n
character regardless of the platform and their newline convention. - Maybe think about changing the behaviour at a next major release? If we care about
unlines
being the inverse oflines
, we should make it so.