`
47 |
48 | ## 3. Code blocks
49 |
50 | Very similar to ``, but use the `
` tag. Call this function `code_`.
51 |
52 |
53 | ## Solutions
54 |
55 |
56 | Unordered lists
57 |
58 | ```hs
59 | ul_ :: [Structure] -> Structure
60 | ul_ =
61 | Structure . el "ul" . concat . map (el "li" . getStructureString)
62 | ```
63 |
64 |
65 |
66 |
67 |
68 | Ordered lists
69 |
70 | ```hs
71 | ol_ :: [Structure] -> Structure
72 | ol_ =
73 | Structure . el "ol" . concat . map (el "li" . getStructureString)
74 | ```
75 |
76 | Note: the two functions above could be unified.
77 |
78 |
79 |
80 |
81 |
82 | Code blocks
83 |
84 | ```hs
85 | code_ :: String -> Structure
86 | code_ = Structure . el "pre" . escape
87 | ```
88 |
89 |
90 |
91 |
--------------------------------------------------------------------------------
/src/SUMMARY.md:
--------------------------------------------------------------------------------
1 | # Summary
2 |
3 | - [About this book](./01-about.md)
4 | - [Hello world](./02-hello.md)
5 | - [Building an HTML printer library](./03-html_printer.md)
6 | - [Flexible HTML content (functions)](./03-html/01-html_content.md)
7 | - [Adding type signatures](./03-html/02-type_signatures.md)
8 | - [Embedded Domain Specific Languages](./03-html/03-edsls.md)
9 | - [Safer HTML construction with types](./03-html/04-safer_construction.md)
10 | - [Preventing incorrect use with modules](./03-html/05-modules.md)
11 | - [Escaping characters](./03-html/06-escaping_characters.md)
12 | - [Exposing internal functionality (Internal modules)](./03-html/07-internal_modules.md)
13 | - [Exercises](./03-html/08-exercises.md)
14 | - [Summary](./03-html/09-summary.md)
15 | - [Custom markup language](./04-markup.md)
16 | - [Representing the markup language as a Haskell data type](./04-markup/01-data_type.md)
17 | - [Parsing markup part 01 (Recursion)](./04-markup/02-parsing_01.md)
18 | - [Displaying the parsing results (type classes)](./04-markup/03-displaying_results.md)
19 | - [Parsing markup part 02 (Pattern matching)](./04-markup/04-parsing_02.md)
20 | - [Gluing things together](./05-glue.md)
21 | - [Converting Markup to HTML](./05-glue/01-markup_to_html.md)
22 | - [Working with IO](./05-glue/02-io.md)
23 | - [Defining a project description](./05-glue/03-project.md)
24 | - [Fancy options parsing](./05-glue/04-optparse.md)
25 | - [Handling errors and multiple files](./06-errors_and_files.md)
26 | - [Handling errors with Either](./06-errors_and_files/01-either.md)
27 | - [Either with IO?](./06-errors_and_files/02-except.md)
28 | - [Exceptions](./06-errors_and_files/03-exceptions.md)
29 | - [Let's code already!](./06-errors_and_files/04-implementation.md)
30 | - [Summary](./06-errors_and_files/05-summary.md)
31 | - [Passing an environment](./07-environment.md)
32 | - [Writing tests](./08-testing.md)
33 | - [Generating documentation](./09-documentation.md)
34 |
35 | - [Recap](./10-recap.md)
36 |
37 | ---
38 |
39 | [Where to go next](./11-next.md)
40 |
41 | [Frequently asked questions](./12-faq.md)
42 |
--------------------------------------------------------------------------------
/src/10-recap.md:
--------------------------------------------------------------------------------
1 | # Recap
2 |
3 | In this book, we've implemented a very simple static blog generator while learning Haskell as we go.
4 |
5 | - We've learned about basic Haskell building blocks, such as definitions, functions,
6 | types, modules, recursion, pattern matching, type classes, IO, and exceptions.
7 | - We've learned about [EDSLs](./03-html/03-edsls.html) and used the *combinator pattern* to implement
8 | a composable html generation library.
9 | - We've learned how to leverage types, modules, and smart constructors
10 | to [make invalid states unrepresentable](./03-html/04-safer_construction.html).
11 | - We've learned how to represent complex data using [ADTs](./04-markup/01-data_type.html).
12 | - We've learned how to use [pattern matching](./04-markup/04-parsing_02.html#pattern-matching) to transform ADTs,
13 | and how to use [recursion](./04-markup/02-parsing_01.html#recursion-and-accumulating-information) to solve problems.
14 | - We've used the *functional core, imperative shell* approach to build a program that handles IO and applies
15 | our domain logic to user inputs.
16 | - We've learned about abstractions such as [monoids](./05-glue/01-markup_to_html.html#monoids),
17 | [functors](./05-glue/04-optparse.html#functor) and [monads](./06-errors_and_files/01-either.html#monadic-interface),
18 | and how they can help us reuse code and convey information about shared interfaces.
19 | - We've learned how to create fancy [command-line interfaces](./05-glue/04-optparse.html), [write tests](./08-testing.html),
20 | and [generate documentation](./09-documentation.html).
21 |
22 | While Haskell is a very big and complex language, and there's always more to be learned,
23 | I think we've reached an important milestone where
24 | you can start building your own Haskell projects and be productive with Haskell!
25 |
26 | This is a good time to celebrate and pat yourself on the back for getting this far! Great job, you!
27 |
28 | If you'd like to learn even more about Haskell and continue your Haskell journey
29 | beyond this book, check out the appendix sections [Where to go next](./11-next.md) and the [FAQ](./12-faq.md).
30 |
31 | ## Thank you!
32 |
33 | Thank you for reading this book. I hope you enjoyed it and found Haskell interesting.
34 |
35 | I would very much like to hear your feedback. If you'd like, you could leave your
36 | feedback on this book's
37 | [discussion board](https://github.com/soupi/learn-haskell-blog-generator/discussions),
38 | or you could reach me via email.
39 | You can find my contact information [on my website](https://gilmi.me).
40 |
41 | If you liked this book, do let me know - your kind words mean a lot.
42 |
43 | > Finally, if you *really* liked this book and would like to support future passion projects
44 | > like it, you can [support me directly via Ko-fi](https://ko-fi.com/gilmi).
45 |
46 | Thank you, and good luck with your next Haskell project!
47 |
--------------------------------------------------------------------------------
/src/04-markup.md:
--------------------------------------------------------------------------------
1 | # Custom markup language
2 |
3 | In this chapter, we will define our own simple markup language
4 | and parse documents written in this language into Haskell data structures.
5 |
6 | Our markup language will contain the following features:
7 |
8 | - Headings: prefix by a number of `*` characters
9 | - Paragraphs: a group of lines without empty lines in between
10 | - Unordered lists: a group of lines, each prefixed with `- `
11 | - Ordered lists: a group of lines, each prefixed with `# `
12 | - Code blocks: a group of lines, each prefixed with `> `
13 |
14 | Here's a sample document:
15 |
16 | ```org
17 | * Compiling programs with ghc
18 |
19 | Running ghc invokes the Glasgow Haskell Compiler (GHC),
20 | and can be used to compile Haskell modules and programs into native
21 | executables and libraries.
22 |
23 | Create a new Haskell source file named hello.hs, and write
24 | the following code in it:
25 |
26 | > main = putStrLn "Hello, Haskell!"
27 |
28 | Now, we can compile the program by invoking ghc with the file name:
29 |
30 | > ➜ ghc hello.hs
31 | > [1 of 1] Compiling Main ( hello.hs, hello.o )
32 | > Linking hello ...
33 |
34 | GHC created the following files:
35 |
36 | - hello.hi - Haskell interface file
37 | - hello.o - Object file, the output of the compiler before linking
38 | - hello (or hello.exe on Microsoft Windows) - A native runnable executable.
39 |
40 | GHC will produce an executable when the source file satisfies both conditions:
41 |
42 | # Defines the main function in the source file
43 | # Defines the module name to be Main or does not have a module declaration
44 |
45 | Otherwise, it will only produce the .o and .hi files.
46 | ```
47 |
48 | which we will eventually convert into this (modulo formatting) HTML:
49 |
50 | ```html
51 | Compiling programs with ghc
52 |
53 | Running ghc invokes the Glasgow Haskell Compiler (GHC),
54 | and can be used to compile Haskell modules and programs into native
55 | executables and libraries.
56 |
57 |
58 | Create a new Haskell source file named hello.hs, and write
59 | the following code in it:
60 |
61 |
62 | main = putStrLn "Hello, Haskell!"
63 |
64 |
65 | Now, we can compile the program by invoking ghc with the file name:
66 |
67 |
68 | ➜ ghc hello.hs
69 | [1 of 1] Compiling Main ( hello.hs, hello.o )
70 | Linking hello ...
71 |
72 |
73 | GHC created the following files:
74 |
75 |
76 |
77 | - hello.hi - Haskell interface file
78 | - hello.o - Object file, the output of the compiler before linking
79 | - hello (or hello.exe on Microsoft Windows) - A native runnable executable.
80 |
81 |
82 | GHC will produce an executable when the source file satisfies both conditions:
83 |
84 |
85 |
86 | - Defines the main function in the source file
87 | - Defines the module name to be Main, or does not have a module declaration
88 |
89 |
90 | Otherwise, it will only produce the .o and .hi files.
91 |
92 | ```
93 |
--------------------------------------------------------------------------------
/src/03-html/03-edsls.md:
--------------------------------------------------------------------------------
1 | # Embedded Domain-Specific Languages
2 |
3 | Right off the bat, we run into a common pattern in Haskell: creating
4 | Embedded Domain-Specific Languages (EDSLs for short).
5 |
6 | Domain-specific languages (DSLs) are specialized programming languages that are
7 | tailored to specific domains, in contrast to general-purpose languages,
8 | which try to work well in many domains.
9 |
10 | A few examples of DSLs are:
11 |
12 | - make - for defining build systems
13 | - DOT - for defining graphs
14 | - Sed - for defining text transformations
15 | - CSS - for defining styling
16 | - HTML - for defining web pages
17 |
18 | An *embedded* domain-specific language is a little language that is
19 | embedded inside another programming language, making a program written in
20 | the EDSL a valid program in the language it was written in.
21 |
22 | The little HTML library we've been writing can be considered an EDSL.
23 | It is used specifically for building web pages (by returning HTML strings),
24 | and is valid Haskell code!
25 |
26 | In Haskell, we frequently create and use EDSLs to express domain-specific
27 | logic. We have EDSLs for concurrency, command-line options parsing, JSON and HTML,
28 | creating build systems, writing tests, and many more.
29 |
30 | Specialized languages are useful because they can solve specific problems in
31 | a concise (and often safe) way, and by embedding, we get to use the full power of
32 | the host language for our domain logic, including syntax highlighting and
33 | various tools available for the language.
34 |
35 | The drawback of embedding domain-specific languages is that we have to adhere to
36 | the rules of the programming language we embed in, such as syntactic and semantic rules.
37 |
38 | Some languages alleviate this drawback by providing meta-programming capabilities
39 | in the form of macros or other features to extend the language.
40 | And while Haskell does provide such capabilities as well, it is also expressive and concise
41 | enough that many EDSLs do not need them.
42 |
43 | Instead, many Haskell EDSLs use a pattern called _the combinator pattern_:
44 | They define *primitives* and *combinators* -
45 | primitives are basic building blocks of the language,
46 | and combinators are functions that combine primitives into more complex structures.
47 |
48 | In our HTML EDSL, our primitives are functions such as `html_` and `title_`
49 | that can be used to create a single HTML node, and we pass other
50 | constructed nodes as input to these functions, and combine them into a more complex
51 | structure with the append function `<>`.
52 |
53 | There are still a few tricks we can use to make our HTML EDSL better:
54 |
55 | 1. We can use Haskell's type system to make sure we only construct *valid*
56 | HTML, so for example, we don't create a `` node
57 | without a `<head>` node or have user content that
58 | can include unescaped special characters,
59 | and throw a type error when the user tries to do something invalid.
60 |
61 | 2. Our HTML EDSL can move to its own module so it can be reused in multiple modules.
62 |
63 | In the next few sections, we'll take a look at how to define our own types and
64 | how to work with modules to make it harder to make errors, and a little bit
65 | about linked lists in Haskell.
66 |
--------------------------------------------------------------------------------
/src/03-html/09-summary.md:
--------------------------------------------------------------------------------
1 | # Summary
2 |
3 | In this chapter, we built a very minimal HTML EDSL.
4 | We will later use this library to convert our custom markup formatted text to HTML.
5 |
6 | We've also learned about:
7 |
8 | - Defining and using functions
9 | - Types and type signatures
10 | - Embedded domain-specific languages
11 | - Chaining functions using the `.` operator
12 | - Preventing incorrect use with `newtype`s
13 | - Defining modules and the `Internal` module pattern
14 | - Encapsulation using `newtype`s and modules
15 |
16 | Here's our complete program up to this point:
17 |
18 | ```hs
19 | -- hello.hs
20 |
21 | import Html
22 |
23 | main :: IO ()
24 | main = putStrLn (render myhtml)
25 |
26 | myhtml :: Html
27 | myhtml =
28 | html_
29 | "My title"
30 | ( append_
31 | (h1_ "Heading")
32 | ( append_
33 | (p_ "Paragraph #1")
34 | (p_ "Paragraph #2")
35 | )
36 | )
37 | ```
38 |
39 | ```hs
40 | -- Html.hs
41 |
42 | module Html
43 | ( Html
44 | , Title
45 | , Structure
46 | , html_
47 | , h1_
48 | , p_
49 | , ul_
50 | , ol_
51 | , code_
52 | , append_
53 | , render
54 | )
55 | where
56 |
57 | import Html.Internal
58 | ```
59 |
60 | ```hs
61 | -- Html/Internal.hs
62 |
63 | module Html.Internal where
64 |
65 | -- * Types
66 |
67 | newtype Html
68 | = Html String
69 |
70 | newtype Structure
71 | = Structure String
72 |
73 | type Title
74 | = String
75 |
76 | -- * EDSL
77 |
78 | html_ :: Title -> Structure -> Html
79 | html_ title content =
80 | Html
81 | ( el "html"
82 | ( el "head" (el "title" (escape title))
83 | <> el "body" (getStructureString content)
84 | )
85 | )
86 |
87 | p_ :: String -> Structure
88 | p_ = Structure . el "p" . escape
89 |
90 | h1_ :: String -> Structure
91 | h1_ = Structure . el "h1" . escape
92 |
93 | ul_ :: [Structure] -> Structure
94 | ul_ =
95 | Structure . el "ul" . concat . map (el "li" . getStructureString)
96 |
97 | ol_ :: [Structure] -> Structure
98 | ol_ =
99 | Structure . el "ol" . concat . map (el "li" . getStructureString)
100 |
101 | code_ :: String -> Structure
102 | code_ = Structure . el "pre" . escape
103 |
104 | append_ :: Structure -> Structure -> Structure
105 | append_ c1 c2 =
106 | Structure (getStructureString c1 <> getStructureString c2)
107 |
108 | -- * Render
109 |
110 | render :: Html -> String
111 | render html =
112 | case html of
113 | Html str -> str
114 |
115 | -- * Utilities
116 |
117 | el :: String -> String -> String
118 | el tag content =
119 | "<" <> tag <> ">" <> content <> "</" <> tag <> ">"
120 |
121 | getStructureString :: Structure -> String
122 | getStructureString content =
123 | case content of
124 | Structure str -> str
125 |
126 | escape :: String -> String
127 | escape =
128 | let
129 | escapeChar c =
130 | case c of
131 | '<' -> "<"
132 | '>' -> ">"
133 | '&' -> "&"
134 | '"' -> """
135 | '\'' -> "'"
136 | _ -> [c]
137 | in
138 | concat . map escapeChar
139 | ```
140 |
141 | > You can also [browse the code as a tree](https://github.com/soupi/learn-haskell-blog-generator/tree/2a4691de627bcb280e92f3d02a88d5404179dc86).
142 |
--------------------------------------------------------------------------------
/src/11-next.md:
--------------------------------------------------------------------------------
1 | # Where to go next
2 |
3 | Haskell is an incredibly rich and deep programming language.
4 | New cutting-edge techniques, concepts, and features are still being discovered
5 | and sometimes integrated into GHC. This sometimes makes it seemingly impossible
6 | to catch up to.
7 |
8 | This phenomena is sometimes dubbed
9 | [The Haskell pyramid](https://patrickmn.com/software/the-haskell-pyramid/).
10 | I hope that by reading this book and following the exercises,
11 | you readers have reached the bar of productivity, and you can now go and start
12 | working on your own projects with Haskell. I highly encourage you to do so.
13 | In my opinion, writing useful Haskell projects is the best method to solidify
14 | what you currently know and identify what you still need to learn.
15 |
16 | ## Extending this project
17 |
18 | If you'd like to extend this project, here are a few ideas for you:
19 |
20 | 1. **Serve over HTTP** - You can use a web library such as
21 | [wai](https://www.youtube.com/watch?v=mz5_HmLGRXc) or
22 | [twain](https://gilmi.me/blog/post/2022/04/24/learn-twain-bulletin-app)
23 | to serve this blog over HTTP instead of generating it statically
24 | 2. **Rewrite it with libraries** - you could rewrite it and use a real-world
25 | [HTML package](https://hackage.haskell.org/package/lucid)
26 | and [markdown parser](https://hackage.haskell.org/package/cmark-gfm)
27 | 3. **Add features**
28 | 1. You could add a metadata block at the top of each article
29 | which would include the title, publish date, and tags of a blog post,
30 | and use them when generating HTML, index page, and even tags pages
31 | 2. You could add HTML pages templating using
32 | [mustache](https://hackage.haskell.org/package/mustache) or similar,
33 | and use that to generate a nice and customizable structure to the page
34 | 3. You could add support for links and images in our markup language parser
35 | 4. You could add support for configuration files which would include things like
36 | the blog title, description, or other meta information for things like
37 | [twitter cards](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards)
38 |
39 | Or anything else you can think of, consider this project your playground and
40 | do whatever you like with it!
41 |
42 | ## Other resources
43 |
44 | At some point, you are likely to run into new concepts, techniques,
45 | or even just a feeling of "I feel like this could be done better".
46 | I'd like to point you in the right direction so you can find additional information
47 | and learn new Haskell things when you need to or want to.
48 |
49 | I've compiled a list of resources for learning Haskell called
50 | [Haskell study plan](https://github.com/soupi/haskell-study-plan),
51 | which includes links to very useful articles, community hubs, and news aggregators,
52 | project suggestions, and even cool open-source Haskell projects.
53 | You will also find alternative explanations for things we've covered
54 | and even links to other Haskell tutorials, guides, and books in case you need
55 | a different view on things.
56 |
57 | Also, the [GHC User Guide](https://downloads.haskell.org/ghc/latest/docs/users_guide/index.html)
58 | is a fantastic resource with loads of articles and information about the language and GHC tooling around it.
59 | It is often the best place to learn about the Haskell language.
60 |
61 | However, don't feel pressured to learn everything Haskell
62 | has to offer right away. Mastering Haskell is a journey that can take a lot of time.
63 | Most of us are definitely not there yet, but we can still be very productive with Haskell,
64 | build real-world projects, and even discover new techniques and concepts ourselves.
65 |
66 | Remember that in a lazy language, we evaluate things only when needed.
67 | Maybe we can do that too, with Haskell concepts!
68 |
--------------------------------------------------------------------------------
/readme.md:
--------------------------------------------------------------------------------
1 | # learn-haskell-blog-generator
2 |
3 | This is the source repository for
4 | "Learn Haskell by building a blog generator",
5 | a project-oriented book about Haskell.
6 |
7 | To view the book, visit the [website](https://learn-haskell.blog).
8 |
9 | To report issues and ask questions,
10 | visit the [issue tracker](https://github.com/soupi/learn-haskell-blog-generator/issues).
11 |
12 | ## Code reference
13 |
14 | <table>
15 | <thead>
16 | <tr>
17 | <th>Chapter</th>
18 | <th>Code</th>
19 | <th>Commit</th>
20 | </tr>
21 | </thead>
22 | <tbody>
23 | <tr>
24 | <td>3.9 - HTML EDSL</td>
25 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/tree/2a4691de627bcb280e92f3d02a88d5404179dc86">Tree</a></td>
26 | <td></td>
27 | </tr>
28 | <tr>
29 | <td>4.4 - Markup parsing</td>
30 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/tree/9f951a05d4f78cf59190ee4f3cd8de85e1c33bd1">Tree</a></td>
31 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/commit/9f951a05d4f78cf59190ee4f3cd8de85e1c33bd1">Diff</a></td>
32 | </tr>
33 | <tr>
34 | <td>5.1 - Markup to HTML conversion</td>
35 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/tree/ad34f2264e9114f2d7436ff472c78da47055fcfe">Tree</a></td>
36 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/commit/ad34f2264e9114f2d7436ff472c78da47055fcfe">Diff</a></td>
37 | </tr>
38 | <tr>
39 | <td>5.2 - IO</td>
40 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/tree/908e7173cf32de5ce8507e43a1fb9124fc5d63f4">Tree</a></td>
41 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/commit/908e7173cf32de5ce8507e43a1fb9124fc5d63f4">Diff</a></td>
42 | </tr>
43 | <tr>
44 | <td>5.3 - Package format</td>
45 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/tree/8ca58aef80930db82cd20e85f44f5e34e1d74214">Tree</a></td>
46 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/commit/8ca58aef80930db82cd20e85f44f5e34e1d74214">Diff</a></td>
47 | </tr>
48 | <tr>
49 | <td>5.4 - CLI options parsing</td>
50 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/tree/d0d76aad632fe3abd8701e44db5ba687e0c7ac96">Tree</a></td>
51 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/commit/d0d76aad632fe3abd8701e44db5ba687e0c7ac96">Diff</a></td>
52 | </tr>
53 | <tr>
54 | <td>6 - Richer HTML content</td>
55 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/tree/110a19029f0be42eb2ac656f5d38356dbf9c5746">Tree</a></td>
56 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/commit/110a19029f0be42eb2ac656f5d38356dbf9c5746">Diff</a></td>
57 | </tr>
58 | <tr>
59 | <td>6.5 - Handling multiple files</td>
60 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/tree/a08d148d981fa00cb7025f1b651d7b75084dd1ae">Tree</a></td>
61 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/commit/a08d148d981fa00cb7025f1b651d7b75084dd1ae">Diff</a></td>
62 | </tr>
63 | <tr>
64 | <td>7 - Environment</td>
65 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/tree/f9fe7179fcf0e6c818f6caa860b52e991432dab2">Tree</a></td>
66 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/commit/f9fe7179fcf0e6c818f6caa860b52e991432dab2">Diff</a></td>
67 | </tr>
68 | <tr>
69 | <td>8 - Testing</td>
70 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/tree/da1615b6e0a2a4ff2728528240d790754853bf02">Tree</a></td>
71 | <td><a href="https://github.com/soupi/learn-haskell-blog-generator/commit/da1615b6e0a2a4ff2728528240d790754853bf02">Diff</a></td>
72 | </tr>
73 | </tbody>
74 | </table>
75 |
--------------------------------------------------------------------------------
/src/02-hello.md:
--------------------------------------------------------------------------------
1 | # Hello, world!
2 |
3 | In this chapter, we will create a simple HTML "hello world" program and use the Haskell toolchain
4 | to compile and run it.
5 |
6 | > If you haven't installed a Haskell toolchain yet, visit
7 | > [haskell.org/downloads](https://haskell.org/downloads) for instructions on how to download
8 | > and install a Haskell toolchain.
9 |
10 | ## A Haskell source file
11 |
12 | A Haskell source file is composed of definitions.
13 |
14 | The most common type of definition has the following form:
15 |
16 | ```hs
17 | <name> = <expression>
18 | ```
19 |
20 | Note that:
21 |
22 | 1. Names must start with a lowercase letter
23 | 2. We cannot use the same name more than once in a file
24 |
25 | A source file containing a definition of the name `main` can be treated as an executable,
26 | and the expression `main` is bound to is the entry point to the program.
27 |
28 | Let's create a new Haskell source file called `hello.hs` and write the following line there:
29 |
30 | ```hs
31 | main = putStrLn "<html><body>Hello, world!</body></html>"
32 | ```
33 |
34 | We've defined a new name, `main`, and bound it to the expression `putStrLn "<html><body>Hello, world!</body></html>"`.
35 |
36 | the body of `main` means calling the function `putStrLn` with the string `"<html><body>Hello, world!</body></html>"`
37 | as input. `putStrLn` takes a single string as input and prints that string to the standard output.
38 |
39 | __Note__: we don't need parenthesis to pass arguments to functions in Haskell.
40 |
41 | Running this program will result in the following text printed on the screen:
42 |
43 | ```
44 | <html><body>Hello, world!</body></html>
45 | ```
46 |
47 | Note that we cannot just write `putStrLn "<html><body>Hello, world!</body></html>"`
48 | without the `main =` part, because it is not a definition. This is something that is allowed
49 | in languages such as Python and OCaml, but not in Haskell or, for example, C.
50 |
51 | ## Compiling programs
52 |
53 | To run this little program, we can compile it using the command line program `ghc`:
54 |
55 | ```sh
56 | > ghc hello.hs
57 | [1 of 1] Compiling Main ( hello.hs, hello.o )
58 | Linking hello ...
59 | ```
60 |
61 | Invoking `ghc` with `hello.hs` will create the following artifact files:
62 |
63 | 1. `hello.o` - Object file
64 | 2. `hello.hi` - Haskell interface file
65 | 3. `hello` - A native executable file
66 |
67 | And after the compilation, we can run the `hello` executable:
68 |
69 | ```sh
70 | > ./hello
71 | <html><body>Hello, world!</body></html>
72 | ```
73 |
74 | ## Interpreting programs
75 |
76 | Alternatively, we can skip the compilation and creation of artifact files phase and run the source file directly
77 | using the command line program `runghc`:
78 |
79 | ```sh
80 | > runghc hello.hs
81 | <html><body>Hello, world!</body></html>
82 | ```
83 |
84 | We can also redirect the output of the program to a file and then open it in Firefox.
85 |
86 | ```sh
87 | > runghc hello.hs > hello.html
88 | > firefox hello.html
89 | ```
90 |
91 | This command should open Firefox and display a web page with `Hello, world!` written in it.
92 |
93 | I recommend using `runghc` with this tutorial. While compiling produces significantly faster programs,
94 | interpreting programs provides us with faster feedback while we are developing and making frequent changes.
95 |
96 | > If you want to learn more about the core Haskell tools, you can read
97 | > [this article](https://gilmi.me/blog/post/2021/08/14/hs-core-tools),
98 | > but what's described above is enough for our usage at the moment.
99 |
100 | ## More bindings
101 |
102 | We can define the HTML string passed to `putStrLn` in a new name instead of passing
103 | it directly to `putStrLn`. Change the content of the `hello.hs` file we defined above to:
104 |
105 | ```hs
106 | main = putStrLn myhtml
107 |
108 | myhtml = "<html><body>Hello, world!</body></html>"
109 | ```
110 |
111 | __Note__: the order in which we declare the bindings does not matter.
112 |
--------------------------------------------------------------------------------
/src/01-about.md:
--------------------------------------------------------------------------------
1 | # About this book
2 |
3 | > <p style="text-align: center;"> Looking for reviews and mentions? <a href="https://github.com/soupi/learn-haskell-blog-generator/discussions/67">Click here</a>.</p>
4 |
5 | <!--
6 |
7 | > <p style="text-align: center;"><img src="book-logo-transparent.png" alt="book logo" style="max-height: 1.5em; vertical-align: top"> This book is actively maintained. If you find errors, <a href="https://github.com/soupi/learn-haskell-blog-generator/issues">please let me know</a>.</p>
8 |
9 | -->
10 |
11 | <!--
12 | <div style="text-align: center">
13 | <img src="book-logo-transparent.png" alt="book logo" style="max-width: 40%">
14 | </div>
15 | -->
16 |
17 | In this book, we will implement a simple static blog generator in Haskell,
18 | converting documents written in our own custom markup language to HTML.
19 |
20 | We will:
21 |
22 | 1. Implement a tiny HTML printer library
23 | 2. Define and parse our own custom markup language
24 | 3. Read files and glue things together
25 | 4. Add command line arguments parsing
26 | 5. Write tests and documentation
27 |
28 | In each chapter of the book, we will focus on a particular task we wish to achieve,
29 | and throughout the chapter, learn just enough Haskell to complete the task.
30 |
31 | ## Other ways to read this book
32 |
33 | <div style="display: flex; flex-wrap: wrap; align-items: center; justify-content: center;">
34 |
35 | <div style="text-align: center; margin: 5px">
36 | <a href="https://www.youtube.com/watch?v=ZL0qExCnO8g&list=PLxn_Aq3QlOQcXoHWdzxnnuGlGWNXJg43R&index=1" title="Learn Haskell by building a blog video series by Impure Pics">
37 | <img style="max-height: 140px;" src="https://i.ytimg.com/vi/ZL0qExCnO8g/hqdefault.jpg?sqp=-oaymwEXCNACELwBSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLDQbKeP3DE3OL0JN1oL8FYWyQ85JA" border=1>
38 | </a>
39 | <p style="width: 260px; margin: 0px;">Do you prefer watching videos?<br>
40 | <a href="https://impurepics.com">Impure Pics</a> made a video series based on this book!
41 | </p>
42 | </div>
43 |
44 | <div style="text-align: center; margin: 5px">
45 | <a href="lhbg-v0.pdf" title="Experimental v0 PDF version of this book">
46 | <img style="max-height: 140px;" src="pdf.png" border=1>
47 | </a>
48 | <p style="width: 260px; margin: 0px;">Do you prefer reading PDFs?<br>
49 | An experimental PDF version is now available.</p>
50 | </div>
51 |
52 | </div>
53 |
54 | ## Why should you read this book?
55 |
56 | There are many Haskell tutorials, guides, and books out there. Why read this one?
57 |
58 | ### Pros
59 |
60 | There are probably more, but here are a few possible pros:
61 |
62 | - It is **relatively short** - most Haskell books are hundreds of pages long.
63 | This book (when exported to PDF) is roughly 150 pages long.
64 | - It is **project oriented**. Many Haskell books teach Haskell by teaching the underlying
65 | concepts and features in a neat progression. In this book, we **build a Haskell program**
66 | and learn Haskell on the way. This will be a pro to some and a con to others.<br>
67 | There are other tutorials like this. The most notable ones are
68 | [Beginning Haskell](https://www.apress.com/gp/book/9781430262510#otherversion=9781430262503)
69 | and [Haskell via Sokoban](https://haskell-via-sokoban.nomeata.de/).
70 | - It touches on **important topics** such as design patterns, testing, and documentation.
71 | - It has **many exercises** as well as **solutions** to those exercises.
72 | - It's **online**, which means corrections are easy to make.
73 | - It's **free**.
74 |
75 | ### Cons
76 |
77 | There are probably more, but here are a few possible cons:
78 |
79 | - It **may lack depth** - many, much longer Haskell tutorials are long because they go
80 | deeper into the nuts and bolts of each feature, and I tried to keep this book relatively short.
81 | - It **may not cover as many features or techniques** as other tutorials -
82 | we try to cover features as they pop up in our implementation, but we will
83 | probably miss features that aren't as important for our tasks,
84 | while other resources may try to cover many different use cases.
85 | - It **does not have a technical editor**, though it has seen quite a bit of editing.
86 |
87 | ### Other learning resources
88 |
89 | The [haskell.org/documentation](https://www.haskell.org/documentation/) page lists
90 | many tutorials, books, guides, and courses. You can find a few alternatives that I can
91 | recommend [in this list](https://github.com/soupi/haskell-study-plan#about-this-guide).
92 |
93 | <!--
94 |
95 | ### Who am I?
96 |
97 | I'm
98 | [<img src="https://avatars.githubusercontent.com/u/8547573" alt="🐨" style="border-radius: 100px; max-height: 1.5em; vertical-align: top">
99 | gilmi](https://gilmi.me).
100 |
101 | -->
102 |
103 | ## Discussions
104 |
105 | Do you want to discuss the book? Maybe ask a question?
106 | Try the [discussion board](https://github.com/soupi/learn-haskell-blog-generator/discussions)!
107 |
108 |
--------------------------------------------------------------------------------
/src/03-html/05-modules.md:
--------------------------------------------------------------------------------
1 | # Preventing incorrect use with modules
2 |
3 | In this section, we will move the HTML generation library to its own module.
4 |
5 | ## Modules
6 |
7 | Each Haskell source file is a module. The module name should have the
8 | same name as the source file and start with a capital
9 | letter. Sub-directories should also be part of the name, and we use `.`
10 | to denote a sub-directory. We'll see that in the next section.
11 |
12 | The only exception to the rule are entry points to the program -
13 | modules with the name 'Main' that define `main` in them. Their source
14 | file names could have any name they want.
15 |
16 | A module declaration looks like this:
17 |
18 | ```hs
19 | module <module-name>
20 | ( <export-list>
21 | )
22 | where
23 | ```
24 |
25 | The export list can be omitted if you want to export everything
26 | defined in the module, but we don't. We will list exactly the
27 | functions and types we want to export. This will give us control
28 | over how people can use our tiny library.
29 |
30 | We will create a new source file named `Html.hs` and add the following
31 | module declaration code at the top of the file:
32 |
33 | ```hs
34 | module Html
35 | ( Html
36 | , Title
37 | , Structure
38 | , html_
39 | , p_
40 | , h1_
41 | , append_
42 | , render
43 | )
44 | where
45 | ```
46 |
47 | Note that we do not export:
48 |
49 | 1. The constructors for our new types, only the types themselves.
50 | If we wanted to export the constructors as well, we would've written
51 | `Html(Html)` or `Html(..)`. This way the user cannot create their own
52 | `Structure` by writing `Structure "Hello"`.
53 |
54 | 2. Internal functions used by the library, such as `el` and `getStructureString`.
55 |
56 | And we will also move the HTML related functions from our `hello.hs` file
57 | to this new `Html.hs` file:
58 |
59 | ```hs
60 | newtype Html
61 | = Html String
62 |
63 | newtype Structure
64 | = Structure String
65 |
66 | type Title
67 | = String
68 |
69 | html_ :: Title -> Structure -> Html
70 | html_ title content =
71 | Html
72 | ( el "html"
73 | ( el "head" (el "title" title)
74 | <> el "body" (getStructureString content)
75 | )
76 | )
77 |
78 | p_ :: String -> Structure
79 | p_ = Structure . el "p"
80 |
81 | h1_ :: String -> Structure
82 | h1_ = Structure . el "h1"
83 |
84 | el :: String -> String -> String
85 | el tag content =
86 | "<" <> tag <> ">" <> content <> "</" <> tag <> ">"
87 |
88 | append_ :: Structure -> Structure -> Structure
89 | append_ c1 c2 =
90 | Structure (getStructureString c1 <> getStructureString c2)
91 |
92 | getStructureString :: Structure -> String
93 | getStructureString content =
94 | case content of
95 | Structure str -> str
96 |
97 | render :: Html -> String
98 | render html =
99 | case html of
100 | Html str -> str
101 | ```
102 |
103 | Now, anyone importing our module (using the `import` statement
104 | below module declarations but above any other
105 | declaration), will only be able to import what we export.
106 |
107 | Add the following code at the top of the `hello.hs` file:
108 |
109 | ```hs
110 | import Html
111 | ```
112 |
113 | The `hello.hs` file should now look like this:
114 |
115 | ```hs
116 | -- hello.hs
117 |
118 | import Html
119 |
120 | main :: IO ()
121 | main = putStrLn (render myhtml)
122 |
123 | myhtml :: Html
124 | myhtml =
125 | html_
126 | "My title"
127 | ( append_
128 | (h1_ "Heading")
129 | ( append_
130 | (p_ "Paragraph #1")
131 | (p_ "Paragraph #2")
132 | )
133 | )
134 | ```
135 |
136 | And the `Html.hs` file should look like this:
137 |
138 | ```hs
139 | -- Html.hs
140 |
141 | module Html
142 | ( Html
143 | , Title
144 | , Structure
145 | , html_
146 | , p_
147 | , h1_
148 | , append_
149 | , render
150 | )
151 | where
152 |
153 | newtype Html
154 | = Html String
155 |
156 | newtype Structure
157 | = Structure String
158 |
159 | type Title
160 | = String
161 |
162 | html_ :: Title -> Structure -> Html
163 | html_ title content =
164 | Html
165 | ( el "html"
166 | ( el "head" (el "title" title)
167 | <> el "body" (getStructureString content)
168 | )
169 | )
170 |
171 | p_ :: String -> Structure
172 | p_ = Structure . el "p"
173 |
174 | h1_ :: String -> Structure
175 | h1_ = Structure . el "h1"
176 |
177 | el :: String -> String -> String
178 | el tag content =
179 | "<" <> tag <> ">" <> content <> "</" <> tag <> ">"
180 |
181 | append_ :: Structure -> Structure -> Structure
182 | append_ c1 c2 =
183 | Structure (getStructureString c1 <> getStructureString c2)
184 |
185 | getStructureString :: Structure -> String
186 | getStructureString content =
187 | case content of
188 | Structure str -> str
189 |
190 | render :: Html -> String
191 | render html =
192 | case html of
193 | Html str -> str
194 | ```
195 |
196 | > As an aside, you might have noticed that I've decided to suffix the functions used to
197 | > construct HTML values with an underscore (`_`). This is mostly an aesthetic decision which,
198 | > in my opinion, makes the EDSL easier to recognize,
199 | > but it is also useful to avoid name clashes with
200 | > functions defined in the Haskell standard library, such as `head`.
201 | > I took this idea from a Haskell HTML library named `lucid`!
202 |
--------------------------------------------------------------------------------
/src/12-faq.md:
--------------------------------------------------------------------------------
1 | # Frequently asked questions
2 |
3 | > Got a question? You can ask in the [discussion board](https://github.com/soupi/learn-haskell-blog-generator/discussions) or the [issue tracker](https://github.com/soupi/learn-haskell-blog-generator/issues)!
4 |
5 | ## General questions
6 |
7 | ### Why should I learn Haskell
8 |
9 | I've written a couple of articles on the topic:
10 |
11 | - [Consider Haskell](https://gilmi.me/blog/post/2020/04/28/consider-haskell) (Alternative title, 'What can I do with Haskell?')
12 | - [7 things I learned from Haskell](https://gilmi.me/blog/post/2022/12/13/learned-from-haskell)
13 |
14 | ### How to install editor tools
15 |
16 | As far as I know, the most recommended setup today for Haskell development is using
17 | VSCode or [VSCodium](https://vscodium.com/) together with the
18 | marketplace [Haskell extension](https://marketplace.visualstudio.com/items?itemName=haskell.haskell).
19 |
20 | The Haskell extension uses [haskell-language-server](https://github.com/haskell/haskell-language-server)
21 | which can be installed via [GHCup](https://www.haskell.org/ghcup/) or even via the Haskell extension itself.
22 |
23 | If you already have a preferred editor,
24 | [see if HLS supports it](https://haskell-language-server.readthedocs.io/en/latest/configuration.html#configuring-your-editor),
25 | or alternatively use [GHCid](https://github.com/ndmitchell/ghcid#readme)
26 | which provides rapid feedback independently from an editor.
27 |
28 | ### How to learn new things
29 |
30 | The Haskell community keeps marching forward, developing new libraries, tools, and techniques
31 | as well as creating new material for older concepts.
32 | The [Haskell planetarium](https://haskell.pl-a.net) aggregates feeds from several communities into
33 | one page, as well as a [Haskell Weekly newsletter](https://haskellweekly.news/).
34 | You might also find quite a bit of Haskell presence on the
35 | [Fediverse](https://fosstodon.org/tags/haskell)!
36 |
37 | ## Debugging
38 |
39 | ### How to debug Haskell code
40 |
41 | Most imperative languages provide a step debugger. While the
42 | [GHCi debugger](https://downloads.haskell.org/ghc/latest/docs/users_guide/ghci.html#the-ghci-debugger),
43 | exists, it is not particularly easy to use, especially because of Haskell's lazy evaluation, where things
44 | might not be evaluated in the order we might intuitively expect. Because of that,
45 | Haskellers tend to use
46 | [trace debugging](https://hackage.haskell.org/package/base-4.16.4.0/docs/Debug-Trace.html#g:1) and
47 | equational reasoning. With trace debugging, we try to *verify our assumptions* about the code -
48 | we use the various `trace` functions as a "hack" to print variables, functions inputs, functions output
49 | or even just say "got here" from anywhere in the code.
50 |
51 | After finding something that does not match our assumptions, such as unexpected input or output
52 | of a function, we try to think what piece of code could be responsible for the discrepancy or even use
53 | trace debugging again to pinpoint the exact location, and try to use "equational reasoning" to
54 | evaluate the offending code that betrayed our expectations. If it's easy to do, we try running
55 | the function in `ghci` with different inputs to check our assumptions as well.
56 |
57 | Because Haskell focuses on immutability, composability, and using types to eliminate many
58 | classes of possible errors, "local reasoning" becomes possible, and trace debugging
59 | becomes a viable strategy for debugging Haskell programs.
60 |
61 | ### How to understand type errors
62 |
63 | GHC type errors are often not the most friendly error messages, but they mean well! They are just
64 | trying to help us find inconsistencies in our code - often with regard to type usage, they help us
65 | avoid making errors.
66 |
67 | When you run into error messages, start by reading them carefully
68 | until you get used to them, and then the offending code hinted at by the error message.
69 | As you gain experience, it is likely that the most important part of an error will be the location
70 | of the offending code, and by reading the code, we can find the error without the actual error message.
71 |
72 | Adding type signatures and annotations to test your understanding of the types also helps greatly.
73 | We can even ask GHC for the expected type in a certain place by using
74 | [typed holes](https://downloads.haskell.org/ghc/latest/docs/users_guide/exts/typed_holes.html).
75 |
76 | ### My program is slow. Why?
77 |
78 | There could be various reasons. From inefficient algorithms or
79 | [unsuited data structures](https://github.com/soupi/haskell-study-plan#data-structures) for the task
80 | in terms of time complexity of the common operations, to less efficient memory representations
81 | (this is another reminder to use `Text` over `String` in most cases),
82 | and laziness issues (again, the evaluation strategy!).
83 |
84 | The [performance section](https://github.com/soupi/haskell-study-plan#performance) in my Haskell
85 | study plan links to various resources on Haskell evaluation, profiling, and case studies.
86 |
87 | ## Design
88 |
89 | ### How to structure programs
90 |
91 | Start with the imperative shell functional core approach, define EDSLs with the combinator
92 | pattern for logic if needed, use capabilities such as `State` locally if needed,
93 | maybe add an environment configuration with `ReaderT`, and see how it goes.
94 |
95 | If that approach fails you, look at why it fails and examine other solutions according to your needs.
96 |
97 | ### How to model data
98 |
99 | Modeling data using ADTs are usually the way to go. Often programmers coming from object-oriented
100 | background tend to look at type classes as a way to define methods similar to inheritance,
101 | but this often isn't the right approach, and ADTs with different constructors for different alternatives
102 | go a long way. Remember that even OOP people often preach for composition over inheritance.
103 |
104 | Use functions to define behavior on data rather than trying to couple the two together.
105 |
--------------------------------------------------------------------------------
/src/03-html/07-internal_modules.md:
--------------------------------------------------------------------------------
1 | # Exposing internal functionality (Internal modules)
2 |
3 | We have now built a very small but convenient and safe way to write
4 | HTML code in Haskell. This is something that we could (potentially)
5 | publish as a *library* and share with the world by uploading it
6 | to a package repository such as [Hackage](https://hackage.haskell.org/).
7 | Users interested in our library could use a package manager
8 | to include it in their project and build their own HTML pages.
9 |
10 | It is important to note that users are building their projects against
11 | the API that we expose to them, and the package manager doesn't generally
12 | provide access to the source code, so they can't, for example,
13 | modify the `Html` module (that we expose) in their project directly
14 | without jumping through some hoops.
15 |
16 | Because we wanted our `Html` EDSL to be safe, we **hid the internal
17 | implementation from the user**, and the only way to interact with the
18 | library is via the API we provide.
19 |
20 | This provides the safety we wanted to provide, but in this case, it also
21 | *blocks* the user from extending our library *in their own project* with
22 | things we haven't implemented yet, such as lists or code blocks.
23 |
24 | When a user runs into trouble with a library (such as missing features)
25 | the best course of action usually is to open an issue in the repository or
26 | submit a pull request, but sometimes the user needs things to work *now*.
27 |
28 | We admit that we are not perfect and can't think of all use cases for our
29 | library. Sometimes the restrictions we add are too great and may limit
30 | the usage of advanced users who know how things work under the hood and
31 | need certain functionality to use our library.
32 |
33 | ### Internal modules
34 |
35 | For that, we can expose internal modules to provide some flexibility for
36 | advanced users. Internal modules are not a language concept but
37 | rather a (fairly common) design pattern (or idiom) in Haskell.
38 |
39 | Internal modules are simply modules named `<something>.Internal`,
40 | which export all of the functionality and implementation details in that module.
41 |
42 | Instead of writing the implementation in (for example) the `Html` module,
43 | we write it in the `Html.Internal` module, which will export everything.
44 | Then we will import that module in the `Html` module and write an explicit export list
45 | to only export the API we'd like to export (as before).
46 |
47 | `Internal` modules are considered unstable and risky to use by convention.
48 | If you end up using one yourself when using an external Haskell library,
49 | make sure to open a ticket in the library's repository after the storm has passed!
50 |
51 | ### Let's make the changes
52 |
53 | We will create a new directory named `Html` and inside it a new file
54 | named `Internal.hs`. The name of this module should be `Html.Internal`.
55 |
56 | This module will contain all of the code we previously had in the `Html`
57 | module, but **we will change the module declaration in `Html.Internal`
58 | and _omit_ the export list**:
59 |
60 | ```hs
61 | -- Html/Internal.hs
62 |
63 | module Html.Internal where
64 |
65 | ...
66 | ```
67 |
68 | And now in `Html.hs`, we will remove the code that we moved to `Html/Internal.hs`
69 | and in its stead we'll import the internal module:
70 |
71 | ```hs
72 | -- Html.hs
73 |
74 | module Html
75 | ( Html
76 | , Title
77 | , Structure
78 | , html_
79 | , p_
80 | , h1_
81 | , append_
82 | , render
83 | )
84 | where
85 |
86 | import Html.Internal
87 | ```
88 |
89 | Now, users of our library can still import `Html` and safely use our library,
90 | but if they run into trouble and have a dire need to implement unordered lists
91 | to work with our library, they could always work with `Html.Internal` instead.
92 |
93 | <details>
94 | <summary><b>Our revised Html.hs and Html/Internal.hs</b></summary>
95 |
96 | ```hs
97 | -- Html.hs
98 |
99 | module Html
100 | ( Html
101 | , Title
102 | , Structure
103 | , html_
104 | , p_
105 | , h1_
106 | , append_
107 | , render
108 | )
109 | where
110 |
111 | import Html.Internal
112 | ```
113 |
114 | ```hs
115 | -- Html/Internal.hs
116 |
117 | module Html.Internal where
118 |
119 | -- * Types
120 |
121 | newtype Html
122 | = Html String
123 |
124 | newtype Structure
125 | = Structure String
126 |
127 | type Title
128 | = String
129 |
130 | -- * EDSL
131 |
132 | html_ :: Title -> Structure -> Html
133 | html_ title content =
134 | Html
135 | ( el "html"
136 | ( el "head" (el "title" (escape title))
137 | <> el "body" (getStructureString content)
138 | )
139 | )
140 |
141 | p_ :: String -> Structure
142 | p_ = Structure . el "p" . escape
143 |
144 | h1_ :: String -> Structure
145 | h1_ = Structure . el "h1" . escape
146 |
147 | append_ :: Structure -> Structure -> Structure
148 | append_ c1 c2 =
149 | Structure (getStructureString c1 <> getStructureString c2)
150 |
151 | -- * Render
152 |
153 | render :: Html -> String
154 | render html =
155 | case html of
156 | Html str -> str
157 |
158 | -- * Utilities
159 |
160 | el :: String -> String -> String
161 | el tag content =
162 | "<" <> tag <> ">" <> content <> "</" <> tag <> ">"
163 |
164 | getStructureString :: Structure -> String
165 | getStructureString content =
166 | case content of
167 | Structure str -> str
168 |
169 | escape :: String -> String
170 | escape =
171 | let
172 | escapeChar c =
173 | case c of
174 | '<' -> "<"
175 | '>' -> ">"
176 | '&' -> "&"
177 | '"' -> """
178 | '\'' -> "'"
179 | _ -> [c]
180 | in
181 | concat . map escapeChar
182 | ```
183 |
184 | </details>
185 |
186 |
187 | ## Summary
188 |
189 | For our particular project, `Internal` modules aren't necessary.
190 | Because our project and the source code for the HTML EDSL are
191 | part of the same project, and we have access to the `Html`
192 | module directly, we can always go and edit it if we want
193 | (and we are going to do that throughout the book).
194 |
195 | However, if we were planning to release our HTML EDSL as a *library*
196 | for other developers to use, it would be nice
197 | to also expose the internal implementation as an `Internal`
198 | module. Just so we can save some trouble for potential users!
199 |
200 | In a later chapter, we will see how to create a package from our source code.
201 |
--------------------------------------------------------------------------------
/src/04-markup/03-displaying_results.md:
--------------------------------------------------------------------------------
1 | # Displaying the parsing results (type classes)
2 |
3 | We want to be able to print a textual representation of values
4 | of our `Document` type. There are a few ways to do that:
5 |
6 | 1. Write our own function of type `Document -> String`, which we could then print, or
7 | 2. Have Haskell write one for us
8 |
9 | Haskell provides us with a mechanism that can automatically generate the implementation of a
10 | *type class* function called `show`, that will convert our type to `String`.
11 |
12 | The type of the function `show` looks like this:
13 |
14 | ```hs
15 | show :: Show a => a -> String
16 | ```
17 |
18 | This is something new we haven't seen before. Between `::` and `=>`
19 | you see what is called a __type class constraint__ on the type `a`. What
20 | we say in this signature is that the function `show` can work on any
21 | type that is a member of the type class `Show`.
22 |
23 | Type classes is a feature in Haskell that allows us to declare a common
24 | interface for different types. In our case, Haskell's standard library
25 | defines the type class `Show` in the following way (this is a simplified
26 | version but good enough for our purposes):
27 |
28 | ```hs
29 | class Show a where
30 | show :: a -> String
31 | ```
32 |
33 | A type class declaration describes a common interface for Haskell types.
34 | `show` is an overloaded function that will work for any type that is an *instance*
35 | of the type class `Show`.
36 | We can define an instance of a type class manually like this:
37 |
38 | ```hs
39 | instance Show Bool where
40 | show x =
41 | case x of
42 | True -> "True"
43 | False -> "False"
44 | ```
45 |
46 | Defining an instance means providing an implementation for the interface of a specific type.
47 | When we call the function `show` on a data type, the compiler will search the type's `Show` instance,
48 | and use the implementation provided in the instance declaration.
49 |
50 | ```hs
51 | ghci> show True
52 | "True"
53 | ghci> show 187
54 | "187"
55 | ghci> show "Hello"
56 | "\"Hello\""
57 | ```
58 |
59 | As seen above, the `show` function converts a value to its textual representation.
60 | That is why `"Hello"` includes the quotes as well. The `Show` type class is usually
61 | used for debugging purposes.
62 |
63 | ## Deriving instances
64 |
65 | It is also possible to automatically generate implementations of a few selected
66 | type classes. Fortunately, `Show` is one of them.
67 |
68 | If all the types in the definition of our data type already implement
69 | an instance of `Show`, we can *automatically derive* it by adding `deriving Show` at the
70 | end of the data definition.
71 |
72 | ```hs
73 | data Structure
74 | = Heading Natural String
75 | | Paragraph String
76 | | UnorderedList [String]
77 | | OrderedList [String]
78 | | CodeBlock [String]
79 | deriving Show
80 | ```
81 |
82 | Now we can use the function `show :: Show a => a -> String` for any
83 | type that implements an instance of the `Show` type class. For example, with `print`:
84 |
85 | ```hs
86 | print :: Show a => a -> IO ()
87 | print = putStrLn . show
88 | ```
89 |
90 | We can first convert our type to `String` and then write it to the
91 | standard output.
92 |
93 | And because lists also implement `Show` for any element type that has
94 | a `Show` instance, we can now print `Document`s, because they are just
95 | aliases for `[Structure]`. Try it!
96 |
97 | There are many type classes Haskellers use everyday. A couple more are
98 | `Eq` for equality and `Ord` for ordering. These are also special type classes
99 | that can be derived automatically.
100 |
101 | ## Laws
102 |
103 | Type classes often come with "rules" or "laws" that instances should satisfy,
104 | the purpose of these laws is to provide *predictable behaviour* across
105 | instances, so that when we run into a new instance we can be confident
106 | that it will behave in an expected way, and we can write code
107 | that works generically for all instances of a type class while expecting
108 | them to adhere to these rules.
109 |
110 | As an example, let's look at the `Semigroup` type class:
111 |
112 | ```hs
113 | class Semigroup a where
114 | (<>) :: a -> a -> a
115 | ```
116 |
117 | This type class provides a common interface for types with an operation `<>`
118 | that can combine two values into one in some way.
119 |
120 | This type class also mentions that this `<>` operation should be associative,
121 | meaning that these two sides should evaluate to the same result:
122 |
123 | ```
124 | x <> (y <> z) = (x <> y) <> z
125 | ```
126 |
127 | An example of a lawful instance of `Semigroup` is lists with the append operation (`++`):
128 |
129 | ```hs
130 | instance Semigroup [a] where
131 | (<>) = (++)
132 | ```
133 |
134 | Unfortunately, the Haskell type system cannot "prove" that instances
135 | satisfy these laws, but as a community, we often shun unlawful instances.
136 |
137 | Many data types (together with their respective operations) can
138 | form a `Semigroup`, and instances
139 | don't even have to look similar or have a common analogy/metaphor
140 | (and this is true for many other type classes as well).
141 |
142 | **Type classes are often just _interfaces_ with _laws_** (or expected behaviours if you will).
143 | Approaching them with this mindset can be very liberating!
144 |
145 | To put it differently, **type classes can be used to create abstractions** -
146 | interfaces with laws/expected behaviours where we don't actually care about the
147 | concrete details of the underlying type, just that it *implements a certain
148 | API and behaves in a certain way*.
149 |
150 | Regarding `Semigroup`, we have [previously](../03-html/04-safer_construction.html#appending-htmlstructure)
151 | created a function that looks like `<>` for our `Html` EDSL!
152 | We can add a `Semigroup` instance for our `Structure` data type
153 | and have a nicer API!
154 |
155 | ---
156 |
157 | Exercise: Please do this and remove the `append_` function from the API.
158 |
159 | <details>
160 | <summary>Solution</summary>
161 |
162 | Replace this:
163 |
164 | ```hs
165 | append_ :: Structure -> Structure -> Structure
166 | append_ c1 c2 =
167 | Structure (getStructureString c1 <> getStructureString c2)
168 | ```
169 |
170 | With this:
171 |
172 | ```hs
173 | instance Semigroup Structure where
174 | (<>) c1 c2 =
175 | Structure (getStructureString c1 <> getStructureString c2)
176 | ```
177 |
178 | And remove the export of `append_` in `Html.hs`. You won't need to further export anything
179 | as type class instances are exported automatically.
180 |
181 | You will also need to replace the usage of `append_` with `<>` in `hello.hs`.
182 |
183 | </details>
184 |
185 | ---
186 |
--------------------------------------------------------------------------------
/src/06-errors_and_files/02-except.md:
--------------------------------------------------------------------------------
1 | # Either with IO?
2 |
3 | When we create `IO` actions that may require I/O, we risk running into all kinds of errors.
4 | For example, when we use `writeFile`, we could run out of disk space in the middle of writing,
5 | or the file might be write-protected. While these scenarios aren't super common, they are definitely
6 | possible.
7 |
8 | We could've potentially encoded Haskell functions like `readFile` and `writeFile` as `IO` operations
9 | that return `Either`, for example:
10 |
11 | ```hs
12 | readFile :: FilePath -> IO (Either ReadFileError String)
13 | writeFile :: FilePath -> String -> IO (Either WriteFileError ())
14 | ```
15 |
16 | However, there are a couple of issues here; the first is that composing `IO` actions
17 | becomes more difficult. Previously we could write:
18 |
19 | ```hs
20 | readFile "input.txt" >>= writeFile "output.html"
21 | ```
22 |
23 | But now the types no longer match - `readFile` will return an `Either ReadFileError String` when executed,
24 | but `writeFile` wants to take a `String` as input. We are forced to handle the error
25 | before calling `writeFile`.
26 |
27 | ## Composing IO + Either using ExceptT
28 |
29 | One way to handle this is by using **monad transformers**. Monad transformers provide a way
30 | to stack monad capabilities on top of one another. They are called transformers because
31 | **they take a type that has an instance of monad as input and return a new type that
32 | implements the monad interface, stacking a new capability on top of it**.
33 |
34 | For example, if we want to compose values of a type that is equivalent to `IO (Either Error a)`,
35 | using the monadic interface (the function `>>=`), we can use a monad transformer
36 | called [`ExceptT`](https://hackage.haskell.org/package/mtl-2.3.1/docs/Control-Monad-Except.html#g:2)
37 | and stack it over `IO`.
38 | Let's see how `ExceptT` is defined:
39 |
40 | ```hs
41 | newtype ExceptT e m a = ExceptT (m (Either e a))
42 | ```
43 |
44 | Remember, a `newtype` is a new name for an existing type. And if we substitute
45 | `e` with `Error` and `m` with `IO`, we get exactly `IO (Either Error a)` as we wanted.
46 | And we can convert an `ExceptT Error IO a` into `IO (Either Error a)` using
47 | the function `runExceptT`:
48 |
49 | ```hs
50 | runExceptT :: ExceptT e m a -> m (Either e a)
51 | ```
52 |
53 | `ExceptT` implements the monadic interface in a way that combines the capabilities of
54 | `Either`, and whatever `m` it takes. Because `ExceptT e m` has a `Monad` instance,
55 | a specialized version of `>>=` would look like this:
56 |
57 | ```hs
58 | -- Generalized version
59 | (>>=) :: Monad m => m a -> (a -> m b) -> m b
60 |
61 | -- Specialized version, replace the `m` above with `ExceptT e m`.
62 | (>>=) :: Monad m => ExceptT e m a -> (a -> ExceptT e m b) -> ExceptT e m b
63 | ```
64 |
65 | Note that the `m` in the specialized version still needs to be an instance of `Monad`.
66 |
67 | ---
68 |
69 | Unsure how this works? Try to implement `>>=` for `IO (Either Error a)`:
70 |
71 | ```hs
72 | bindExceptT :: IO (Either Error a) -> (a -> IO (Either Error b)) -> IO (Either Error b)
73 | ```
74 |
75 | <details><summary>Solution</summary>
76 |
77 | ```hs
78 | bindExceptT :: IO (Either Error a) -> (a -> IO (Either Error b)) -> IO (Either Error b)
79 | bindExceptT mx f = do
80 | x <- mx -- `x` has the type `Either Error a`
81 | case x of
82 | Left err -> pure (Left err)
83 | Right y -> f y
84 | ```
85 |
86 | Note that we didn't actually use the implementation details of `Error` or `IO`,
87 | `Error` isn't mentioned at all, and for `IO`, we only used the monadic interface with
88 | the do notation. We could write the same function with a more generalized type signature:
89 |
90 | ```hs
91 | bindExceptT :: Monad m => m (Either e a) -> (a -> m (Either e b)) -> m (Either e b)
92 | bindExceptT mx f = do
93 | x <- mx -- `x` has the type `Either e a`
94 | case x of
95 | Left err -> pure (Left err)
96 | Right y -> f y
97 | ```
98 |
99 | And because `newtype ExceptT e m a = ExceptT (m (Either e a))`, we can just
100 | pack and unpack that `ExceptT` constructor and get:
101 |
102 |
103 | ```hs
104 | bindExceptT :: Monad m => ExceptT e m a -> (a -> ExceptT e m b) -> ExceptT e m b
105 | bindExceptT mx f = ExceptT $ do
106 | -- `runExceptT mx` has the type `m (Either e a)`
107 | -- `x` has the type `Either e a`
108 | x <- runExceptT mx
109 | case x of
110 | Left err -> pure (Left err)
111 | Right y -> runExceptT (f y)
112 | ```
113 |
114 | </details>
115 |
116 | ---
117 |
118 | > Note that when stacking monad transformers, the order in which we stack them matters.
119 | > With `ExceptT Error IO a`, we have an `IO` operation that, when run will return `Either`
120 | > an error or a value.
121 |
122 | `ExceptT` can enjoy both worlds - we can return error values using the function `throwError`:
123 |
124 | ```hs
125 | throwError :: e -> ExceptT e m a
126 | ```
127 |
128 | and we can "lift" functions that return a value of the underlying monadic type `m` to return
129 | a value of `ExceptT e m a` instead:
130 |
131 | ```hs
132 | lift :: m a -> ExceptT e m a
133 | ```
134 |
135 | for example:
136 |
137 | ```hs
138 | getLine :: IO String
139 |
140 | lift getLine :: ExceptT e IO String
141 | ```
142 |
143 | > Actually, `lift` is also a type class function from `MonadTrans`, the type class
144 | > of monad transformers. So technically, `lift getLine :: MonadTrans t => t IO String`,
145 | > but we are specializing for concreteness.
146 |
147 |
148 | Now, if we had:
149 |
150 | ```hs
151 | readFile :: FilePath -> ExceptT IOError IO String
152 |
153 | writeFile :: FilePath -> String -> ExceptT IOError IO ()
154 | ```
155 |
156 | We could compose them again without issue:
157 |
158 | ```hs
159 | readFile "input.txt" >>= writeFile "output.html"
160 | ```
161 |
162 | But remember - the error type `e` (in both the case `Either` and `Except`)
163 | must be the same between composed functions! This means that the type representing
164 | errors for both `readFile` and `writeFile` must be the same - that would also
165 | force anyone using these functions to handle these errors - should a user who
166 | called `writeFile` be required to handle a "file not found" error? Should a user
167 | who called `readFile` be required to handle an "out of disk space" error?
168 | There are many, many more possible IO errors! "network unreachable", "out of memory",
169 | "cancelled thread", we cannot require a user to handle all these errors, or
170 | even cover them all in a data type.
171 |
172 | So what do we do?
173 |
174 | We give up on this approach **for IO code**, and use a different one: Exceptions,
175 | as we'll see in the next chapter.
176 |
177 | > Note - when we stack `ExceptT` on top of a different type called
178 | > [`Identity`](https://hackage.haskell.org/package/base-4.16.4.0/docs/Data-Functor-Identity.html)
179 | > that also implements the `Monad` interface, we get a type that is exactly like `Either`
180 | > called [`Except`](https://hackage.haskell.org/package/transformers-0.6.0.2/docs/Control-Monad-Trans-Except.html#t:Except)
181 | > (without the `T` at the end). You might sometimes want to use `Except` instead of `Either`
182 | > because it has a more appropriate name and better API for error handling than `Either`.
183 |
--------------------------------------------------------------------------------
/src/03-html/01-html_content.md:
--------------------------------------------------------------------------------
1 | # Flexible HTML content (functions)
2 |
3 | We'd like to be able to write different HTML pages without having to write the whole
4 | structure of HTML and body tags over and over again. We can do that with functions.
5 |
6 | To define a function, we create a definition as we saw previously and add the argument
7 | names after the name and before the equals sign (`=`).
8 | So a function definition has the following form:
9 |
10 | ```hs
11 | <name> <arg1> <arg2> ... <argN> = <expression>
12 | ```
13 |
14 | The argument names will be available in scope on the right side of the equals sign
15 | (in the `<expression>`), and the function name will be `<name>`.
16 |
17 | We'll define a function that takes a string, which is the content of the page, and wraps it in
18 | the relevant `html` and `body` tags by concatenating them before and after the content.
19 | We use the operator `<>` to concatenate two strings.
20 |
21 | ```hs
22 | wrapHtml content = "<html><body>" <> content <> "</body></html>"
23 | ```
24 |
25 | This function, `wrapHtml`, takes one argument named `content` and returns a string
26 | that prefixes `<html><body>` before the content and appends `</body></html>` after it.
27 | Note that it is common to use camelCase in Haskell for names.
28 |
29 | Now we can adjust our `myhtml` definition from the previous chapter:
30 |
31 | ```hs
32 | myhtml = wrapHtml "Hello, world!"
33 | ```
34 |
35 | Again, notice that we don't need parenthesis when calling functions. Function calls have the form:
36 |
37 | ```hs
38 | <name> <arg1> <arg2> ... <argN>
39 | ```
40 |
41 | However, if we wanted to substitute `myhtml` with the expression `myhtml` is bound
42 | to in `main = putStrLn myhtml`, we would have to wrap the expression in parenthesis:
43 |
44 | ```hs
45 | main = putStrLn (wrapHtml "Hello, world!")
46 | ```
47 |
48 | If we accidentally write this instead:
49 |
50 | ```hs
51 | main = putStrLn wrapHtml "Hello, world!"
52 | ```
53 |
54 |
55 | we'll get an error from GHC stating that `putStrLn` is applied to two arguments,
56 | but it only takes one. This is because the above is of the form `<name> <arg1> <arg2>`
57 | in which, as we defined earlier, `<arg1>` and `<arg2>` are arguments to `<name>`.
58 |
59 | Using parenthesis, we can group the expressions together in the correct order.
60 |
61 | > #### An aside about operator precedence and fixity
62 | >
63 | > operators (like `<>`) are infix functions that take two arguments - one from each side.
64 | >
65 | > When there are multiple operators in the same expression without parenthesis, the operator
66 | > *fixity* (left or right) and *precedence* (a number between 0 and 10) determine which
67 | > operator binds more tightly.
68 | >
69 | > In our case, `<>` has *right* fixity, so Haskell adds an invisible parenthesis on the right side
70 | > of `<>`. So, for example:
71 | >
72 | > ```hs
73 | > "<html><body>" <> content <> "</body></html>"
74 | > ```
75 | >
76 | > is viewed by Haskell as:
77 | >
78 | > ```hs
79 | > "<html><body>" <> (content <> "</body></html>")
80 | > ```
81 | >
82 | > For an example of precedence, in the expression `1 + 2 * 3`,
83 | > the operator `+` has precedence 6, and the operator `*` has precedence 7,
84 | > so we give precedence to `*` over `+`. Haskell will view this expression as:
85 | >
86 | > ```hs
87 | > 1 + (2 * 3)
88 | > ```
89 | >
90 | > You might run into errors when mixing different operators with the *same precedence*
91 | > but *different fixity*, because Haskell won't understand how to group these expressions.
92 | > In that case, we can solve the problem by adding parenthesis explicitly.
93 |
94 | ---
95 |
96 | Exercises:
97 |
98 | 1. Separate the functionality of `wrapHtml` into two functions:
99 | 1. One that wraps content in `html` tag
100 | 2. one that wraps content in a `body` tag
101 |
102 | Name the new functions `html_` and `body_`.
103 | 2. Change `myhtml` to use these two functions.
104 | 3. Add another two similar functions for the tags `<head>` and `<title>`
105 | and name them `head_` and `title_`.
106 | 4. Create a new function, `makeHtml`, which takes two strings as input:
107 | 1. One string for the title
108 | 2. One string for the body content
109 |
110 | And construct an HTML string using the functions implemented in the previous exercises.
111 |
112 | The output for:
113 |
114 | ```hs
115 | makeHtml "My page title" "My page content"
116 | ```
117 |
118 | should be:
119 |
120 | ```html
121 | <html><head><title>My page titleMy page content