That's fine, still a +1 from me On Thu, Aug 30, 2018, 8:13 PM Richard Eisenberg wrote:

Just to clarify here: all I mean is that we should include the word "Partial" in the Haddock documentation -- no deprecation or warning, just documentation.

Richard

...

On Aug 30, 2018, at 8:10 PM, Richard Eisenberg wrote:

Proposal: Mark partial functions in `base` as partial

Motivation: I'm about to teach Haskell to a classful of beginners. In my experience, they will soon reach for functions like `head` and `tail`, because pattern-matching is foreign to them. I would love just to be able to say "Don't use partial functions", but many students will not easily be able to tell partial functions from total ones.

I do expect this problem to work itself out rather quickly, and then students will be able to identify partial functions, but loudly marking partial functions as partial seems like a small service to everyone and a bigger one to newbies. I don't see any downsides.

Thoughts?

Thanks, Richard _______________________________________________ Libraries mailing list Libraries@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries

_______________________________________________ Libraries mailing list Libraries@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries

Why not? I don't think mentioning that length doesn't work with infinite lists will do any harm. I think many people make a distinction between partiality due to endless evaluation and partiality due to a call to "error". But I still think documenting either of both things can be helpful. Best, Daniel Am Fr., 31. Aug. 2018 um 04:09 Uhr schrieb David Feuer < david.feuer@gmail.com>:

Yes, I think so. What about functions like length? length (repeat ()) is bottom. repeat () is not bottom. Ergo, length is partial. But I don't think we want to say that!

On Thu, Aug 30, 2018, 10:05 PM Daniel Díaz Casanueva < dhelta.diaz@gmail.com> wrote:

...

+1 from me too. The partiality of a function seems to me like something that should be documented.

Best, Daniel

Am Fr., 31. Aug. 2018 um 02:10 Uhr schrieb Richard Eisenberg < rae@cs.brynmawr.edu>:

...

Proposal: Mark partial functions in `base` as partial

Motivation: I'm about to teach Haskell to a classful of beginners. In my experience, they will soon reach for functions like `head` and `tail`, because pattern-matching is foreign to them. I would love just to be able to say "Don't use partial functions", but many students will not easily be able to tell partial functions from total ones.

I do expect this problem to work itself out rather quickly, and then students will be able to identify partial functions, but loudly marking partial functions as partial seems like a small service to everyone and a bigger one to newbies. I don't see any downsides.

Thoughts?

Thanks, Richard _______________________________________________ Libraries mailing list Libraries@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries

_______________________________________________ Libraries mailing list Libraries@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries

Yup! Just wanted to make sure it didn't end up being the latter. On Thu, Aug 30, 2018, 10:19 PM Eric Mertens wrote:

I think this comes down to just documenting things like how strict functions are and how they behave on various classes of inputs. These are good things to document. It doesn’t just have to be about a boolean flag “partial” paste on a bunch of definitions.

On Aug 30, 2018, at 7:16 PM, Daniel Díaz Casanueva wrote:

Why not? I don't think mentioning that length doesn't work with infinite lists will do any harm.

I think many people make a distinction between partiality due to endless evaluation and partiality due to a call to "error". But I still think documenting either of both things can be helpful.

Best, Daniel

Am Fr., 31. Aug. 2018 um 04:09 Uhr schrieb David Feuer < david.feuer@gmail.com>:

...

Yes, I think so. What about functions like length? length (repeat ()) is bottom. repeat () is not bottom. Ergo, length is partial. But I don't think we want to say that!

On Thu, Aug 30, 2018, 10:05 PM Daniel Díaz Casanueva < dhelta.diaz@gmail.com> wrote:

...

+1 from me too. The partiality of a function seems to me like something that should be documented.

Best, Daniel

Am Fr., 31. Aug. 2018 um 02:10 Uhr schrieb Richard Eisenberg < rae@cs.brynmawr.edu>:

...

Proposal: Mark partial functions in `base` as partial

Motivation: I'm about to teach Haskell to a classful of beginners. In my experience, they will soon reach for functions like `head` and `tail`, because pattern-matching is foreign to them. I would love just to be able to say "Don't use partial functions", but many students will not easily be able to tell partial functions from total ones.

I do expect this problem to work itself out rather quickly, and then students will be able to identify partial functions, but loudly marking partial functions as partial seems like a small service to everyone and a bigger one to newbies. I don't see any downsides.

Thoughts?

Thanks, Richard _______________________________________________ Libraries mailing list Libraries@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries

_______________________________________________ Libraries mailing list Libraries@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries

_______________________________________________ Libraries mailing list Libraries@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries

Hi, Frerich Raabe wrote:

On 2018-08-31 04:09, David Feuer wrote:

...

What about functions like length? length (repeat ()) is bottom. repeat () is not bottom. Ergo, length is partial.

This caught me by surprise - I would have never considered 'length' to be a partial function! Maybe I don't quite understand what it means for some expression to be 'bottom' (I thought that's the same as 'undefined').

We have to be a bit careful with attributing blame for failure. By David's argument, e.g. "fst" would also be "partial". Consider: (_|_, _|_) /= _|_ But fst (_|_, _|_) == _|_ But the bottom here does not originate in the computation of "fst" as such, but in the computation of the *argument* to "fst". Similarly for "length" above: "length" is not to blame for the fact that length (repeat ()) == _|_ It's simply that computation of the argument to length takes a very(!) long time. In a language with strict semantics, this is of course no surprise at all, and I suspect no one would suggest that a function like "length" is partial in a strict setting just because the overall computation fails to terminate when the computation of an argument does.

My naive understanding was that a partial function is one which has no definition for certain arguments; in particular, it has no definition which could be used while doing equational reasoning by hand, on a piece of paper (i.e. without running the program).

It appears that this is not quite correct -- instead, any function which fails to return anything (at runtime!) for certain arguments is partial? E.g. 'sort' would be partial or even 'elem' (consider 'True `elem` repeat False')?

I'd say neither "sort" nor "elem" is partial for the same reason. As to the original suggestion of marking functions as partial, I think that's fine, as long as one is careful to explain exactly what is meant. (And documenting (different forms of) strictness would be fine too.) But one should bear in mind that there are functions that are partial for other reasons that pattern matching failure, in particular numerical functions like division, square root, ... (And the full story of floating point arithmetic with infinities and NaNs etc. is of course quite complicated.) Students (well, any programmer) should of course be aware that one have to be extra careful when using partial functions, and certainly also encouraged to seek alternative formulations, but just saying "Don't use partial functions" is not the full story. Best, /Henrik This message and any attachment are intended solely for the addressee and may contain confidential information. If you have received this message in error, please contact the sender and delete the email and attachment. Any views or opinions expressed by the author of this email do not necessarily reflect the views of the University of Nottingham. Email communications with the University of Nottingham may be monitored where permitted by law.

I think it actually can be made precise, with some more knowledge than I have. Roughly speaking, a function is total if its result is fully defined (contains no bottoms) whenever its argument is fully defined. On Fri, Aug 31, 2018, 7:04 AM Wolfgang Jeltsch wrote:

Am Freitag, den 31.08.2018, 08:21 +0200 schrieb Frerich Raabe:

...

This caught me by surprise - I would have never considered 'length' to be a partial function! Maybe I don't quite understand what it means for some expression to be 'bottom' (I thought that's the same as 'undefined').

My naive understanding was that a partial function is one which has no definition for certain arguments; in particular, it has no definition which could be used while doing equational reasoning by hand, on a piece of paper (i.e. without running the program).

It appears that this is not quite correct -- instead, any function which fails to return anything (at runtime!) for certain arguments is partial? E.g. 'sort' would be partial or even 'elem' (consider 'True `elem` repeat False')?

The word “partial” might not have a precise definition in the context of Haskell. In particular, it might not necessarily be defined in terms of ⊥ (bottom). However, the notion of ⊥ itself does have a precise definition.

⊥ is a special value that every type contains. A consequence of this is that there are also values like ⊥ : ⊥.

A good way to think about ⊥ is that ⊥ marks the absence of any information. So the value of an expression is ⊥ if there is a lack of an appropriate alternative in a case distinction but also if there is a recursion that doesn’t produce any data.

For example, if zeros is defined via the equation zeroes = 0 : zeroes, you know that zeroes must be of the form 0 : _; so it cannot be ⊥. However, if unknown is defined via the equation unknown = unknown, there is nothing you can learn about any information that unknown would contain; so unknown is ⊥.

Mathematically, the values of each type form a domain such that ⊥ is the minimum and each data constructor is an order-preserving function. When defining a value recursively, Haskell will give you the *least* solution of the defining equation. The equation zeros = 0 : zeros has only one solution (0 : 0 : 0 : …). The equation unknown = unknown, on the other hand, has every value as a solution, and thus the least of them, ⊥, is picked as the value for unknown.

All the best, Wolfgang _______________________________________________ Libraries mailing list Libraries@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries

+1 from me too. How about also adding in (to the documentation) the pre-condition - i.e. an identification of the inputs for which it will terminate and produce a result (where this is possible to state, of course).

On 31 Aug 2018, at 03:05, Daniel Díaz Casanueva wrote:

+1 from me too. The partiality of a function seems to me like something that should be documented.

Best, Daniel

Am Fr., 31. Aug. 2018 um 02:10 Uhr schrieb Richard Eisenberg mailto:rae@cs.brynmawr.edu>: Proposal: Mark partial functions in `base` as partial

Motivation: I'm about to teach Haskell to a classful of beginners. In my experience, they will soon reach for functions like `head` and `tail`, because pattern-matching is foreign to them. I would love just to be able to say "Don't use partial functions", but many students will not easily be able to tell partial functions from total ones.

I do expect this problem to work itself out rather quickly, and then students will be able to identify partial functions, but loudly marking partial functions as partial seems like a small service to everyone and a bigger one to newbies. I don't see any downsides.

Thoughts?

Thanks, Richard _______________________________________________ Libraries mailing list Libraries@haskell.org mailto:Libraries@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries _______________________________________________ Libraries mailing list Libraries@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries

-------------------------------------------------------------------- Andrew Butterfield Tel: +353-1-896-2517 Fax: +353-1-677-2204 Lero@TCD, Head of Foundations & Methods Research Group School of Computer Science and Statistics, Room G.39, O'Reilly Institute, Trinity College, University of Dublin http://www.scss.tcd.ie/Andrew.Butterfield/ --------------------------------------------------------------------

I feel like there's a difference between partial functions in the sense of length and partial functions in the sense of head. If you have a partiality monad like the free monad over Identity: data Partial a = Done a | NotYet (Partial a) instance Monad Partial where return = Done Done a >>= f = f a NotYet m >>= f = NotYet $ m >>= f then length has a sensible and productive implementation in terms of it: partialLength :: [a] -> Partial Int partialLength = go 0 where go n ls = seq n $ case ls of [] -> Done n _:ls' -> NotYet $ go (n + 1) ls' This is similar to the mechanism that Agda and Idris use to denote a potentially non-terminating result; with it, these languages are Turing complete. head and tail aren't like that, and should be marked differently in the documentation. On Fri, Aug 31, 2018 at 7:28 AM, Andrew Martin wrote:

I'm strongly +1 on this.

On Thu, Aug 30, 2018 at 8:10 PM Richard Eisenberg wrote:

...

Proposal: Mark partial functions in `base` as partial

Motivation: I'm about to teach Haskell to a classful of beginners. In my experience, they will soon reach for functions like `head` and `tail`, because pattern-matching is foreign to them. I would love just to be able to say "Don't use partial functions", but many students will not easily be able to tell partial functions from total ones.

I do expect this problem to work itself out rather quickly, and then students will be able to identify partial functions, but loudly marking partial functions as partial seems like a small service to everyone and a bigger one to newbies. I don't see any downsides.

Thoughts?

Thanks, Richard _______________________________________________ Libraries mailing list Libraries@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries

-- -Andrew Thaddeus Martin

_______________________________________________ Libraries mailing list Libraries@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries

Why isn't the call to error in div what you mean? On Fri, Aug 31, 2018, 10:49 AM Richard Eisenberg wrote:

In a response not cc'd to the list, a contributor (not sure if they want public identification) suggests:

...

I think we want something like "partial even given input you can successfully DeepSeq"

That's the specification of the feature I'm after. I think all the commentary about infinite lists, etc., would lead also to good documentation additions. (For example, it would be fantastic if every function precisely documented its strictness, preferably with some standard notation, but this is not the problem I'm trying to solve here.)

Also, it was suggested that the documentation be checked -- that is, we could imagine a {-# TOTAL ... #-} or {-# PARTIAL ... #-} pragma that GHC could check on compilation and Haddock could include in the documentation. This would also be great, but much more than I'm proposing here.

Maybe here's a concrete example:

...

-- | /Contains a call to 'error'./ Extract the first element of a list, which must be non-empty. head :: [a] -> a

In the end, it's the call to error that I want noted. Of course, having a similar note on functions like div (where the problem isn't a call to error) and length (that will loop on infinite lists) is good, but not really what I'm proposing here.

Thanks, Richard

...

On Aug 30, 2018, at 8:10 PM, Richard Eisenberg wrote:

Proposal: Mark partial functions in `base` as partial

Motivation: I'm about to teach Haskell to a classful of beginners. In my experience, they will soon reach for functions like `head` and `tail`, because pattern-matching is foreign to them. I would love just to be able to say "Don't use partial functions", but many students will not easily be able to tell partial functions from total ones.

I do expect this problem to work itself out rather quickly, and then students will be able to identify partial functions, but loudly marking partial functions as partial seems like a small service to everyone and a bigger one to newbies. I don't see any downsides.

Thoughts?

Thanks, Richard _______________________________________________ Libraries mailing list Libraries@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries

_______________________________________________ Libraries mailing list Libraries@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries

Hi, Richard Eisenberg wrote:

Maybe here's a concrete example:

...

-- | /Contains a call to 'error'./ Extract the first element of a list, which must be non-empty. head :: [a] -> a

In the end, it's the call to error that I want noted.

Yes, whether the code of a function directly or indirectly calls "error" is well-defined property that could be documented. But note that this does not coincide with the following:

...

I think we want something like "partial even given input you can successfully DeepSeq"

That's the specification of the feature I'm after

Consider e.g. apply f x = f x As e.g. apply head [] == _|_ we'd have to conclude by the above definition that "apply" is partial. But it clearly does not "call error". Just to be clear, this does not correspond to how I understand partiality. Lots of higher order functions, like "map", then would have to called partial. And I am not sure that would be so helpful for the purpose of alerting (new) programmers to functions that one might argue should be avoided. So maybe something very clear and easy to understand, such as "contains call to error" is the best approach. Best, /Henrik This message and any attachment are intended solely for the addressee and may contain confidential information. If you have received this message in error, please contact the sender and delete the email and attachment. Any views or opinions expressed by the author of this email do not necessarily reflect the views of the University of Nottingham. Email communications with the University of Nottingham may be monitored where permitted by law.

On Fri, 31 Aug 2018, Ryan Trinkle wrote:

This is probably not really for the libraries list, but in the same vein as this discussion, I think it would be extremely helpful to have a way of banning functions that does *not* require changing the upstream library.  I would be thrilled to have a machine-checked ban on use of the 'head', 'tail', etc.

So far I have HLint rules to ban them. Unfortunately, they do not work transitively. People have already proposed a TotalHaskell pragma analogously to SafeHaskell.

On Fri, Aug 31, 2018 at 5:21 PM Tikhon Jelvis wrote:

Deeper questions of partiality aside, if a function can throw exceptions, the documentation should spell this out *explicitly*, ideally also specifying what the type of the exception may be. To me, this is a *minimum* standard to expect from documentation in any language with exceptions.

Is this to be applied transitively? It has to be, to meet your criteria, but this is a fairly unrealistic expectation to put on library authors. If it's not applied transitively, then the documentation creates a false sense of security - "catch these exceptions that *I* throw and you're good!". I really think this part of exceptions is a tooling problem that we have to solve. Haddock should be responsible for figuring this out. Ollie

On 31/08/2018 18.59, Oliver Charles wrote:

On Fri, Aug 31, 2018 at 5:21 PM Tikhon Jelvis wrote:

...

Deeper questions of partiality aside, if a function can throw exceptions, the documentation should spell this out *explicitly*, ideally also specifying what the type of the exception may be. To me, this is a *minimum* standard to expect from documentation in any language with exceptions.

Is this to be applied transitively? It has to be, to meet your criteria, but this is a fairly unrealistic expectation to put on library authors. If it's not applied transitively, then the documentation creates a false sense of security - "catch these exceptions that *I* throw and you're good!". I really think this part of exceptions is a tooling problem that we have to solve. Haddock should be responsible for figuring this out.

Not to mention the issues of "may throw" declarations for higher-order functions... (Java checked exceptions are basically broken[1] because of this. Well, this + the variance issues arising from inheritance and method signatures, but obviously Haskell doesn't have inheritance, so...) Regards, [1] They even break "catch" because everybody is forced to wrap "checked" exceptions in a RuntimeException if signatures don't specify "may throw anything", so you *also* have to check for wrapped exceptions in "catch" clauses. Anyway...

On 31/08/2018 21.14, Tikhon Jelvis wrote:

This is a question of documentation, not type design. You don't have to consider what exceptions your transitive dependencies might throw—you need to understand what inputs *do* cause your function to fail. If you use head in a safe way or have a call to error in an unreachable case, you shouldn't say anything. On the other hand, if your function fails when the inputs aren't relatively prime, you should document this regardless of whether the failure is an exception you throw explicitly, a result of a partial pattern match or a division by zero four layers of indirection away.

I definitely expect the author of a function to understand what inputs cause that function to fail. If you don't understand this, you simply don't understand the code you wrote. (Luckily, QuickCheck will probably find any edge cases you missed when writing the function.)

Thinking about it a bit more, there's nothing specific to exceptions here. If your code loops forever when the lengths of the inputs sum to a multiple of seven, that's pretty handy to know from the documentation! 

I would also expect the same style of documentation even for errors expressed in the types with whatever your favorite generalization of Either happens to be.

Oh, of course, these are good points. My point was simply that it's often a little bit complicated to *document* this in a simple easy to understand way. Regards,