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

[Jade (@Jade)]

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


Commits:
535ef0dc by Jade at 2024-01-21T11:57:48+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
=====================================
@@ -181,14 +181,26 @@ hGetChar handle =
 -- 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 other point while reading
+-- in 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/535ef0dc524e5d01784d9daa0b0df1ad8941b9a7

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/535ef0dc524e5d01784d9daa0b0df1ad8941b9a7
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/e46a8081/attachment-0001.html>