Add function to read UTF-8 files

[ulidtko]

Following up to #372 and #407, consider a snippet

 […] do
      mRssPages <- readMay @Int . (!! 1) . T.split (== ' ') <$> readFileText "/proc/self/statm"
      […]

Produces deprecation warning:

In the use of ‘readFileText’
"'readFileText' depends on the system's locale settings and can throw unexpected exceptions.
 Use 'readFileBS' instead."

I've read the documented deprecations, and I fully understand the motivating blog post of Mr. Snoyberg.

However, those locale concerns simply don't apply here. Because I'm writing code to read a guaranteed small file that's nearly guaranteed to never exceed the 12-character alphabet 0123456789 \n.

So then, can I silence the deprecation warning on this specific use-site? No — all deprecations over the entire module only.

Sigh... 😔 Sure, writing yet another little helper once more is far from hard:

readFileUtf8 :: MonadIO m => FilePath -> m Text
readFileUtf8 = fmap decodeUtf8Lenient . readFileBS

And everybody is doing that already anyway. Yet by this same reasoning, the entire Relude.File module is redundant.

---

Constructively: I'm proposing a function:

readFileUtf8 :: (MonadIO m, ConvertUtf8 r ByteString) => FilePath -> m r

which:

• reads text from files, strictly;
• interacts nicely with Relude's String.Conversions module,
• thus avoids the whole clunky series readFileUtf8Text, readFileUtf8LText, readFileUtf8String elegantly.

I'll add lazy version on demand.

Checklist:

HLint

• I've changed the exposed interface (add new reexports, remove reexports, rename reexported things, etc.).
  — new API, no need for hlint changes.

General

• I've updated the CHANGELOG with the short description of my latest changes.
• All new and existing tests pass.
• I keep the code style used in the files I've changed (see style-guide for more details).
• I've used the stylish-haskell file.
• My change requires the documentation updates.
  • I've updated the documentation accordingly.
• I've added the [ci skip] text to the docs-only related commit's name.

[tomjaguarpaw]

Hi @ulidtko, I'm a volunteer who helps keep Relude building. API decisions are taken by @vrom911.

[ulidtko]

Hi @tomjaguarpaw, sure; I understand. Could you perhaps approve another PR of mine, #451 ? That one doesn't touch the API. пт, 30 серп. 2024, 08:39 користувач tomjaguarpaw ***@***.***> пише:

…

Hi @ulidtko <https://github.com/ulidtko>, I'm a volunteer who helps keep Relude building. API decisions are taken by @vrom911 <https://github.com/vrom911>. — Reply to this email directly, view it on GitHub <#459 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACZGGXZD4Y7EX7DQA7F7WLZUAHR7AVCNFSM6AAAAABNLGTXCSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGMRQGIZDQNRQGM> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[ulidtko]

... BTW, it wasn't my conscious choice to set you as reviewer @tomjaguarpaw; GitHub did it itself. I believe it auto-assigns reviewers based on the CODEOWNERS file.

[tomjaguarpaw]

I see, that's good to know, thanks.

[fishtreesugar]

By the way, since text-2.1, it provides Data.Text.IO.Utf8 for working directly with UTF-8 without locale.