[Git][ghc/ghc][wip/T14804] Improve documentation of hGetLine.

[Jade (@Jade)]

Jade pushed to branch wip/T14804 at Glasgow Haskell Compiler / GHC


Commits:
d0567d06 by Jade at 2024-01-21T12:30:41+01:00
Improve documentation of hGetLine.

- Add explanation for whether a newline is returned
- Add examples

Fixes #14804

- - - - -


1 changed file:

- libraries/base/src/GHC/IO/Handle/Text.hs


Changes:

=====================================
libraries/base/src/GHC/IO/Handle/Text.hs
=====================================
@@ -179,16 +179,28 @@ hGetChar handle =
 
 -- | Computation 'hGetLine' @hdl@ reads a line from the file or
 -- channel managed by @hdl at .
+-- 'hGetLine' does not return the newline as part of the result.
+--
+-- A line is separated by the newline
+-- set with 'System.IO.hSetNewlineMode' or 'nativeNewline' by default.
+-- The read newline character(s) are not returned as part of the result.
+--
+-- If 'hGetLine' encounters end-of-file at any point while reading
+-- in the middle of a line, it is treated as a line terminator and the (partial)
+-- line is returned.
 --
 -- This operation may fail with:
 --
 --  * 'isEOFError' if the end of file is encountered when reading
 --    the /first/ character of the line.
 --
--- If 'hGetLine' encounters end-of-file at any other point while reading
--- in a line, it is treated as a line terminator and the (partial)
--- line is returned.
-
+-- ==== __Examples__
+--
+-- >>> withFile "/home/user/foo" ReadMode hGetLine >>= putStrLn
+-- this is the first line of the file :O
+--
+-- >>> withFile "/home/user/bar" ReadMode (replicateM 3 . hGetLine)
+-- ["this is the first line","this is the second line","this is the third line"]
 hGetLine :: Handle -> IO String
 hGetLine h =
   wantReadableHandle_ "hGetLine" h $ \ handle_ ->



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/d0567d0690e5af3222efe9bd264d2fe6f3921be3

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/d0567d0690e5af3222efe9bd264d2fe6f3921be3
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20240121/78e14b6b/attachment-0001.html>