Proposal: Add readMaybe (and possibly readEither) to Prelude, make Haddocks for read more cautionary

[Andrew Martin]

1. +1
2. ambivalent, I've never actually seen anyone use readEither, but it
doesn't really hurt for it to be there since it isn't stealing anything
valuable from the namespace.
3. +1

In my mind, the single most important part of this is part (3), improving
the docs. All partial functions defined in base should come with warnings
about this in the docs, along with hyperlinks to total functions for
accomplishing the same thing.

-Andrew Martin

On Tue, Dec 27, 2016 at 10:58 PM, Simon Jakobi via Libraries <
libraries at haskell.org> wrote:

> read [1] is an easy way to introduce runtime exceptions into programs,
> but its documentation doesn't sufficiently warn of this danger. read's
> safe alternatives, Text.Read.readMaybe [2] and Text.Read.readEither
> [3], are relatively unknown and too hard to find.
>
> To guide users (particularly newcomers) away from read and towards
> readMaybe and readEither, I propose to
>
> 1. Add readMaybe to the Prelude
> 2. Add readEither to the Prelude
> 3. Change the documentation for read to point out the partiality and
> to recommend the above alternatives:
>
>     The haddocks for read currently read:
>
>     > The read function reads input from a string, which must be
> completely consumed by the input process.
>
>     I propose to add a paragraph roughly like this:
>
>     > Note: read will throw an error if the parse fails. If there's
> any uncertainty w.r.t. the shape of the input, readMaybe or readEither
> should be used instead.
>
>
> Name clashes:
>
> A cursory code search on Github for readMaybe [4] reveals many
> existing definitions, mostly with the same type (Read a => String ->
> Maybe a) and definition. The same search for readEither [5] shows
> mostly GHC forks.
>
> Design issues:
>
> I am somewhat doubtful about the benefit of readEither over readMaybe:
> While readEither does give additional info on the kind of parse
> failures, that information is encoded in a String error message, from
> which it must be parsed if it is needed in the program.
>
>
> As the different parts of the proposal can be implemented
> independently of each other, please vote separately on each part of
> the proposal.
>
> Discussion period: 4 weeks.
>
> Cheers,
> Simon
>
> [1] http://hackage.haskell.org/package/base-4.9.0.0/docs/
> Prelude.html#v:read
> [2] http://hackage.haskell.org/package/base-4.9.0.0/docs/
> Text-Read.html#v:readMaybe
> [3] http://hackage.haskell.org/package/base-4.9.0.0/docs/
> Text-Read.html#v:readEither
> [4] https://github.com/search?l=Haskell&q=readMaybe&type=Code
> [5] https://github.com/search?l=Haskell&q=readEither&type=Code
> _______________________________________________
> Libraries mailing list
> Libraries at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries
>



-- 
-Andrew Thaddeus Martin
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/libraries/attachments/20161228/0f686d43/attachment.html>