Example that does not compile and uses several new, unexplained concepts

[fuxoft]

Is your content edit request related to a problem? Please describe.
In the syntax-in-function chapter, there is an example that does not compile "out of the box" and uses several new concepts without explaining them. It's the densityTell function that uses readMaybe.

Additional context
This example uses Just, Nothing and readMaybe which were not yet mentioned at this point in the book and are not explained here. As a beginner, I am also unsure how <- is supposed to work here, as I've only seen used it in list comprehensions in previous chapters. Additionally, on my fresh installation of GHCi 9.6.7, this example does not compile because readMaybe is undefined. This example should contain more detailed explanation of how it works or be moved to later chapter where those concepts are explained.

Link to the page in question
https://learnyouahaskell.github.io/syntax-in-functions.html

[ulysses4ever]

Indeed. This is a recent addition (#59) contributed by @kephas. There are two issues here.

1. The left arrow is the very pattern guards that the paragraph above introduces. It should be easy to fix by adding the mention of <- in the text.

2. Maybe-related stuff. This is the hard one: we're in chapter 4, and Maybe isn't mentioned until chapter 7 (modules), and properly introduced in chapter 8 (making-our-own-types-and-typeclasses). I'm not sure what to do about it. It looks like maybe pattern guards should only be mentioned in chapter 4 and properly introduced somewhere in chapter 8, because it's hard to talk about pattern guards without introducing types and constructors. Or maybe a pattern guard with a function that returns a basic type (like integer) would work in chapter 4, but I'm not sure how meaningful that would be.

[fuxoft]

Also don't forget that readMaybe is undefined and I as a beginner have no idea how to import it.

[ulysses4ever]

Quite right. I meant it under my p. 2 "Maybe-related stuff" but you're right using a function not from Prelude (i. e. one requiring an explicit import) is a separate issue. Easy to fix though.

[ellyxir]

i noticed this too when i was going through the book. either just a mention of it with the note that it'll be covered in ch 7,8 , and/or give a working example but say that it's just a peak, don't expect to understand all the details.
im happy to take a pass at something if it's still pending and if you want, let me know.

[kephas]

I realize that the syntax and meaning of the pattern guard is not explained enough in this version. Maybe like in chapter 7, it would be fine saying here that what Maybe is exactly and how to use functions not in Prelude will both be explained later.

But the syntax itself needs expanding.

[MatthijsBlom]

See also: #81

---

Here are issues I see, not all unique to this example:

• Maybe has not yet been introduced.
• readMaybe needs importing, which has not yet been discussed.
• RealFloat is discussed nowhere in the book.
• Using Read is perhaps not a great example to set.
• The code is needlessly and inconveniently polymorphic – why not just use Double?
• Cognitive load. Learning about guards takes up a certain amount of effort and capacity. Pattern guards are at least as complex as boolean guards, so learning about both more than doubles the load. Rather than introducing concepts as soon as possible, I'd suggest introducing them as soon as convenient to the student.
• Pattern guards aren't used again (i.e. reinforced) anywhere else in the book.
• Nowhere does the book explain (in depth) what guards are, syntactically. Where can guards appear? Where can they not? How can several guards be combined into one? Can they be de-sugared into more 'basic' syntax? The book even appears a bit confused itself: it says "[guards] play really nicely with patterns", which suggests that guards can appear separately from patterns, which they can not.

---

Pattern guards are nice to know about, and not hard to explain to a sufficiently experienced student. But I don't think this chapter is the right place. As the book hasn't needed them before, and also because more realistic examples (i.e. stronger motivation) become available as one progressed through the book, I think it may be preferable to move the introduction to pattern guards all the way to the end.

See also: #145

[kephas]

I agree, I added pattern guards here to cover all the syntax of functions, but it is not the right place. At that point, their existence should be mentioned, possibly with a link to where they are eventually covered, way later.