diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9b7dbe4 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +.cabal-sandbox/ +cabal.sandbox.config diff --git a/Contributing.md b/Contributing.md new file mode 100644 index 0000000..b094331 --- /dev/null +++ b/Contributing.md @@ -0,0 +1,9 @@ +# CONTRIBUTING.md + +> Building the pdf requires pandoc. + +- Don't hyperlink anything that appears in the table-of-content. + * Reason: Those links get messed up in the final pdf. + +- After you're done with your edits, use `make` to build the pdf and + verify that everything looks nice. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..7a88e09 --- /dev/null +++ b/Makefile @@ -0,0 +1,13 @@ +PANDOC = pandoc +INPUT = README.md +OUTPUT = tutorial.pdf +TITLE = -V title=LearnHaskell +AUTHOR = -V author=bitemyapp +FONTSIZE = -V fontsize=12pt +FONTFAMILY = -V fontfamily=sans +PAGESIZE = -V pagesize=a4paper +VARIABLES = $(FONTSIZE) $(PAGESIZE) $(TITLE) $(AUTHOR) $(FONTFAMILY) +FLAGS = --normalize --smart --toc $(VARIABLES) + +pdf: README.md + $(PANDOC) -s $(INPUT) -o $(OUTPUT) $(FLAGS) --column=80 diff --git a/README.md b/README.md index de4dc5b..95e49ea 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,49 @@ +# The Guide + This is my recommended path for learning Haskell. #### Something to keep in mind: *don't sweat the stuff you don't understand immediately*. Just keep moving. -# Community +## Community Our IRC channel is `#haskell-beginners` on Freenode. IRC web client [here](http://webchat.freenode.net/). -## Community Guidelines +The haskell [mailing lists](https://wiki.haskell.org/Mailing_lists). + +### Community Guidelines [Letter to a Young Haskell Enthusiast](http://comonad.com/reader/2014/letter-to-a-young-haskell-enthusiast/) Be nice above all else! -# Primary course - -## What are Haskell, GHC, and Cabal? +# What are Haskell, GHC, and Cabal? Haskell is a programming language as laid out in the reports, most recent one -being in 2010. [onlinereport](http://www.haskell.org/onlinereport/haskell2010/) +being in 2010. The report is available as the +[onlinereport](http://www.haskell.org/onlinereport/haskell2010/). + +## GHC + +[GHC](http://www.haskell.org/ghc/) is the most popular way to work in the +Haskell language. It includes a compiler, REPL (interpreter), package +management, and other things besides. + +## Cabal -GHC is the most popular compiler for Haskell and is what you'll install along -with Cabal. Cabal is the project and dependency management tool used with -GHC. You almost definitely want both if you're going to start writing Haskell. +[Cabal](https://www.haskell.org/cabal/download.html) does project management and +dependency resolution. It's how you'll install projects, typically into their +own sandbox. Cabal is equivalent to Ruby's Bundler, Python's pip, Node's NPM, Maven, etc. GHC manages packaging itself, Cabal chooses what versions to install. -## Getting started +# Getting set-up -### Ubuntu +## Ubuntu -[This](http://launchpad.net/~hvr/+archive/ghc) PPA is excellent and is what I +[This PPA](http://launchpad.net/~hvr/+archive/ghc) is excellent and is what I use on all my Linux dev and build machines. Specifically: @@ -46,50 +57,55 @@ $ sudo apt-get update $ sudo apt-get install cabal-install-1.20 ghc-7.8.3 happy-1.19.4 alex-3.1.3 ``` -Then add -`~/.cabal/bin:/opt/cabal/1.20/bin:/opt/ghc/7.8.3/bin:/opt/happy/1.19.4/bin:/opt/alex/3.1.3/bin` to your PATH (bash_profile, zshrc, bashrc, etc) +Then add the following to your `$PATH` (bash\_profile, zshrc, bashrc, etc): + +- `~/.cabal/bin` +- `/opt/cabal/1.20/bin` +- `/opt/ghc/7.8.3/bin` +- `/opt/happy/1.19.4/bin` +- `/opt/alex/3.1.3/bin` *Optional:* You could also add `.cabal-sandbox/bin` to your path. Code that you are actively developing will be available to you from the command line. This only works when your current working directory is a cabal sandbox. -### Debian +## Debian -#### GHC Repository for debian stable +### GHC Repository for debian stable -If you use Debian stable, it is easier to use http://deb.haskell.org/. To use it: +If you use Debian stable, it is easier to use http://deb.haskell.org/. To +use it: - Add the line `deb http://deb.haskell.org/stable/ ./` to `/etc/apt/sources.list` ```bash -$ GET http://deb.haskell.org/deb.haskell.org.gpg-key | apt-key add - # Add the key to avoid warnings +## Add the key to avoid warnings +$ GET http://deb.haskell.org/deb.haskell.org.gpg-key | apt-key add - $ sudo apt-get update $ sudo apt-get install ghc-7.8.3 happy alex cabal-install ``` -#### Using Ubuntu PPA +### Using Ubuntu PPA If you're not using stable, you can follow the same steps as Ubuntu, but will have to execute an additional command. Immediately after `sudo add-apt-repository -y ppa:hvr/ghc` is executed run: ```bash -sudo sed -i s/jessie/trusty/g /etc/apt/sources.list.d/hvr-ghc-jessie.list +$ sudo sed -i s/jessie/trusty/g /etc/apt/sources.list.d/hvr-ghc-jessie.list ``` -For other Debian versions, just replace all occurences of "jessie" with your +For other Debian versions, just replace all occurences of `jessie` with your version name in the command above. If, for some reason, the file `/etc/apt/sources.list.d/hvr-ghc-jessie.list` does not exist, then `/etc/apt/sources.list` should contain a line like this: -``` -deb http://ppa.launchpad.net/hvr/ghc/ubuntu jessie main -``` + deb http://ppa.launchpad.net/hvr/ghc/ubuntu jessie main Replace `jessie` with `trusty` in this line. -#### Manual compilation +### Manual compilation You can follow [this](http://www.davesquared.net/2014/05/platformless-haskell.html) guide @@ -101,7 +117,7 @@ Notes: - Instead of grabbing the `cabal-install` binary, grab the source and then run `bootstrap.sh` script. -### Fedora 21 +## Fedora 21 To install Haskell 7.8.4 from the unofficial repo (Fedora 22+ will include it in the official one): @@ -111,9 +127,11 @@ sudo yum-config-manager --add-repo https://copr.fedoraproject.org/coprs/petersen sudo yum install ghc cabal-install ``` -As stated in [petersen/ghc-7.8.4 copr page](https://copr.fedoraproject.org/coprs/petersen/ghc-7.8.4/) this ghc cannot be parallel installed with Fedora/EPEL ghc. +As stated in +[petersen/ghc-7.8.4 copr page](https://copr.fedoraproject.org/coprs/petersen/ghc-7.8.4/) +this ghc cannot be parallel installed with Fedora/EPEL ghc. -### Arch Linux +## Arch Linux To install Haskell from the official repos on Arch Linux, run @@ -121,7 +139,7 @@ To install Haskell from the official repos on Arch Linux, run $ sudo pacman -S cabal-install ghc happy alex haddock ``` -### Gentoo +## Gentoo On Gentoo, you can install the individual components of the Haskell Platform through Portage. If you use `ACCEPT_KEYWORDS=arch` (as opposed to @@ -129,8 +147,9 @@ through Portage. If you use `ACCEPT_KEYWORDS=arch` (as opposed to Haskell things. With that in mind, iff you use `ACCEPT_KEYWORDS=arch`, add the following to `/etc/portage/package.keywords`. - dev-haskell/cabal-install - dev-lang/ghc +> dev-haskell/cabal-install + +> dev-lang/ghc Once that is done, @@ -178,19 +197,19 @@ $ cabal install alex happy Congratulations! You now have a working Haskell installation! -### Mac OS X +## Mac OS X -#### 10.9 +### 10.9 Install the [GHC for Mac OS X](http://ghcformacosx.github.io/) app, which includes GHC and Cabal. It provides instructions on how to add GHC and Cabal to your path after you've dropped the `.app` somewhere. -#### 10.6-10.8 +### 10.6-10.8 Do the binary distribution install described below with [this tarball](https://www.haskell.org/platform/download/2014.2.0.0/ghc-7.8.3-x86_64-apple-darwin-r3.tar.bz2). -### Windows +## Windows - The [windows minimal GHC installer](http://neilmitchell.blogspot.com/2014/12/beta-testing-windows-minimal-ghc.html) is able to compile `network` et al. Technically in beta but should work for @@ -199,21 +218,13 @@ Do the binary distribution install described below with [this tarball](https://w Don't forget to run the installer as administrator as it will want to install in your Program Files. -### Other Linux users +## Other Linux users Download the latest binary distributions for cabal and ghc: -#### GHC +- [GHC](http://www.haskell.org/ghc/). -[GHC](http://www.haskell.org/ghc/) is the most popular way to work in the -Haskell language. It includes a compiler, REPL (interpreter), package -management, and other things besides. - -#### Cabal - -[Cabal](https://www.haskell.org/cabal/download.html) does project management and -dependency resolution. It's how you'll install projects, typically into their -own sandbox. +- [Cabal](https://www.haskell.org/cabal/download.html). #### Detailed manual install guide for Mac OS X @@ -221,35 +232,46 @@ You don't need this if you use the .app, but if it doesn't work for you, try [this](http://www.davesquared.net/2014/05/platformless-haskell.html) with the binary distribution. ---- +# Primary Courses + +## Yorgey's cis194 course -## [Yorgey's cis194 course](http://www.seas.upenn.edu/~cis194/spring13/index.html) +> *Do this first*, this is the primary way I recommend being introduced to +> Haskell. -> *Do this first*, this is the primary way I recommend being introduced to Haskell. +Available [online](http://www.seas.upenn.edu/~cis194/spring13/index.html). -[Brent Yorgey](https://byorgey.wordpress.com)'s course is the best I've found so far. -This course is valuable as it will not only equip you to write basic Haskell but also -help you to understand parser combinators. +[Brent Yorgey](https://byorgey.wordpress.com)'s course is the best I've found so +far. This course is valuable as it will not only equip you to write basic +Haskell but also help you to understand parser combinators. The only reason you shouldn't start with cis194 is if you are not a programmer or are an inexperienced one. If that's the case, start with -[Thompson's book](http://www.haskellcraft.com/craft3e/Home.html) and transition to cis194. +[Thompson's book](http://www.haskellcraft.com/craft3e/Home.html) and transition +to cis194. --- -## [NICTA course](https://github.com/NICTA/course) +## NICTA course > This is the course I recommend doing after Yorgey's cis194 course -This will reinforce and give you experience directly implementing the abstractions introduced in cis194, this is practice which is *critical* to becoming comfortable with everyday uses of Functor/Applicative/Monad/etc. in Haskell. Doing cis194 and then the NICTA course represents the core recommendation of my guide and is how I teach -everyone Haskell. +Available on github [here](https://github.com/NICTA/course). + +This will reinforce and give you experience directly implementing the +abstractions introduced in cis194, this is practice which is *critical* to +becoming comfortable with everyday uses of Functor/Applicative/Monad/etc. in +Haskell. Doing cis194 and then the NICTA course represents the core +recommendation of my guide and is how I teach everyone Haskell. --- -## Supplementary Course [cs240h](http://www.scs.stanford.edu/14sp-cs240h/) +## Supplementary Course cs240h > Provides more material on intermediate topics +Available [online](http://www.scs.stanford.edu/14sp-cs240h/). + This is [Bryan O'Sullivan](https://github.com/bos)'s online course from the class he teaches at Stanford. If you don't know who he is, take a gander at half the libraries any Haskell application ends up needing and his name is on it. Of @@ -259,6 +281,8 @@ pipes, and lenses. --- +## Reference material for the three courses + [Learn You a Haskell for Great Good (LYAH)](http://learnyouahaskell.com) and [Real World Haskell](http://book.realworldhaskell.org) (Thanks bos!) are available online. @@ -268,6 +292,10 @@ are great for getting a sense for where monads are useful. Other people have said that they've liked it a lot. Perhaps a good follow-up for practical idioms after you've got the essentials of Haskell down? +### What does that `<-` / `do` / list comprehension syntactic sugar do? + +Excellent [article](http://www.haskellforall.com/2014/10/how-to-desugar-haskell-code.html). + ### For understanding list and fold - [Explain List Folds to Yourself](http://vimeo.com/64673035) @@ -283,9 +311,148 @@ typeclasses in general but also some Hask-specific category theory: - [Understanding basic error messages](http://ics.p.lodz.pl/~stolarek/_media/pl:research:stolarek_understanding_basic_haskell_error_messages.pdf) -## Development Environment +--- + +# Laziness, strictness, guarded recursion + +- Marlow's [book](http://chimera.labs.oreilly.com/books/1230000000929/ch02.html) + about parallelism and concurrency has one of the best introductions to + laziness and normal form I've found. Use other material too if it doesn't + stick immediately. + +- [More points for lazy evaluation](http://augustss.blogspot.hu/2011/05/more-points-for-lazy-evaluation-in.html) + +- [Oh my laziness!](http://alpmestan.com/posts/2013-10-02-oh-my-laziness.html) + +- SO question '[Does haskell have laziness?](http://stackoverflow.com/questions/13042353/does-haskell-have-tail-recursive-optimization)' + +- [Johan Tibell](https://github.com/tibbe)'s slides from a talk on + [reasoning about laziness](http://www.slideshare.net/tibbe/reasoning-about-laziness). + +## Brief demonstration + +```haskell +let a = 1 : a -- guarded recursion, (:) is lazy and can be pattern matched. +let (v : _) = a +> v +1 +> head a -- head a == v +1 + +let a = 1 * a -- not guarded, (*) is strict +> a +*** Exception: <> +``` + +# IO + +- [Evaluation order and State tokens](https://www.fpcomplete.com/user/snoyberg/general-haskell/advanced/evaluation-order-and-state-tokens) + +- [Unraveling the mystery of the IO monad](http://blog.ezyang.com/2011/05/unraveling-the-mystery-of-the-io-monad/). + +- [First class "statements"](http://blog.jle.im/entry/first-class-statements). + +- [Haddocks for System.IO.Unsafe.unsafePerformIO](http://hackage.haskell.org/package/base-4.7.0.1/docs/System-IO-Unsafe.html#v:unsafePerformIO) + Read the docs and note implementation of unsafeDupablePerformIO + +Comment from Reddit thread by `glaebhoerl` + +> Interesting side note: GHC needs to hide the state token representation behind +> an abstract IO type because the state token must always be used linearly (not +> duplicated or dropped), but the type system can't enforce this. Clean, another +> lazy Haskell-like language, has uniqueness types (which are like linear types +> and possibly different in ways I'm not aware of), and they expose the +> World-passing directly and provide a (non-abstract) IO monad only for +> convenience. + +# Monads and monad transformers + +> Do not do these until you understand typeclasses, Monoid, Functor, and +> Applicative! + +Implement the standard library monads ( List, Maybe, Cont, Error, Reader, +Writer, State ) for yourself to understand them better. Then maybe write an +monadic interpreter for a small expression language using +[Monad Transformers Step by Step](http://www.cs.virginia.edu/~wh5a/personal/Transformers.pdf) +paper (mentioned in 'monad transformers' below). + +Writing many interpreters by just changing the monad to change the semantics can +help convey what's going on. + +- [This talk](https://vimeo.com/73648150) by Tony excellently motivates monad + transformers. + +Also, reimplement `Control.Monad`. Functions like `mapM` or `sequence` are good +opportunities to practice writing generic monadic code. + +The NICTA course can be used as a guide to this process, which will also involve +writing your own Applicative as well. + +Credits: + +- Reddit comment by htmltyp and Crandom [here](http://www.reddit.com/r/haskell/comments/29eke6/basic_program_ideas_for_learning_about_monads/cik5aj6). + +- Reddit comment by jozefg [here](http://www.reddit.com/r/haskell/comments/29eke6/basic_program_ideas_for_learning_about_monads/cik5trg). + +## Monad transformers + +- [A gentle introduction to Monad Transformers](https://github.com/kqr/gists/blob/master/articles/gentle-introduction-monad-transformers.md). + +- [Monad transformers step-by-step](http://www.cs.virginia.edu/~wh5a/personal/Transformers.pdf) (warning, code out of date). + +# Testing, tests, specs, generative/property testing + +- This [tutorial](https://github.com/kazu-yamamoto/unit-test-example/blob/master/markdown/en/tutorial.md) by Kazu Yamamoto is fantastic. + +- [Simple-Conduit](https://github.com/jwiegley/simple-conduit): Good simple + library for learning how streaming IO works in general, knowledge + transferrable to libraries like Pipes and Conduit + +# Parsing in Haskell -### Emacs +- Parser combinator [tutorial](https://github.com/JakeWheat/intro_to_parsing) + for Haskell using Parsec + +- [Writing your own micro-Parsec](http://olenhad.me/articles/monadic-parsers/) + +## Parsing and generating JSON + +Aeson is the standard [JSON](https://json.org) parsing solution in +haskell. Available from [hackage](https://hackage.haskell.org/package/aeson) and +[github](https://github.com/bos/aeson). + +- [Parsing JSON using Aeson](http://blog.raynes.me/blog/2012/11/27/easy-json-parsing-in-haskell-with-aeson/) + +- [Aeson and user created types](http://bitemyapp.com/posts/2014-04-11-aeson-and-user-created-types.html) + +- [Parsing non-deterministic data with aeson and sum types](http://bitemyapp.com/posts/2014-04-17-parsing-nondeterministic-data-with-aeson-and-sum-types.html) + +- [Aeson tutorial](https://www.fpcomplete.com/school/starting-with-haskell/libraries-and-frameworks/text-manipulation/json) + +# Graph algorithms and data structures + +- The [fgl package](https://hackage.haskell.org/package/fgl) particularly the + purely functional shortest path [algos](http://hackage.haskell.org/package/fgl-5.4.2.2/docs/Data-Graph-Inductive-Query-SP.html). + +- [Inductive graphs and Functional Graph Algorithms](http://web.engr.oregonstate.edu/~erwig/papers/abstracts.html#JFP01). + +- [FGL/Haskell - A Functional Graph Library](http://web.engr.oregonstate.edu/~erwig/fgl/haskell/old/fgl0103.pdf). + +- [Data.Graph source from Containers package](http://hackage.haskell.org/package/containers-0.5.5.1/docs/Data-Graph.html). + +- The [graphs package](https://hackage.haskell.org/package/graphs). + +- [SO question about PHOAS](http://stackoverflow.com/questions/24369954/separate-positive-and-negative-occurrences-of-phoas-variables-in-presence-of-rec) + +- [PHOAS for free](https://www.fpcomplete.com/user/edwardk/phoas). + +- [Tying the Knot](http://www.haskell.org/haskellwiki/Tying_the_Knot). + +- [Hackage: dag](https://hackage.haskell.org/package/dag). + +# Development Environment + +## Emacs - [Alejandro Serras's tutorial](https://github.com/serras/emacs-haskell-tutorial/blob/master/tutorial.md) @@ -293,7 +460,7 @@ typeclasses in general but also some Hask-specific category theory: - [Chris Done's emacs config](https://github.com/chrisdone/chrisdone-emacs) -### Vim +## Vim - [Vim page on haskellwiki](http://www.haskell.org/haskellwiki/Vim) @@ -307,13 +474,13 @@ typeclasses in general but also some Hask-specific category theory: - [Hindent](https://github.com/chrisdone/hindent) -### Sublime Text +## Sublime Text - [SublimeHaskell](https://github.com/SublimeHaskell/SublimeHaskell) -## FAQ and working with Cabal +# FAQ and working with Cabal -### Fantastic FAQ +## Fantastic FAQ In addition to being an amazing guide for all kinds of things such as GADTs, this also covers some useful basics for Cabal @@ -321,7 +488,7 @@ this also covers some useful basics for Cabal - [What I wish I knew when learning Haskell](http://dev.stephendiehl.com/hask/) also on github [here](https://github.com/sdiehl/wiwinwlh). -### Cabal guidelines +## Cabal guidelines Cabal Hell was a problem for Haskell users before the introduction of sandboxes. Installing outside of a sandbox will install into your user @@ -329,7 +496,8 @@ package-db. This is *not* a good idea except for foundational packages like Cabal, alex, and happy. Nothing else should be installed in the user or global package-dbs unless you know what you're doing. -Some best practices for avoiding cabal hell are available [here](http://softwaresimply.blogspot.com/2014/07/haskell-best-practices-for-avoiding.html). +Some best practices for avoiding cabal hell are available +[here](http://softwaresimply.blogspot.com/2014/07/haskell-best-practices-for-avoiding.html). To experiment with a package or start a project, begin by doing `cabal sandbox init` in a new directory. @@ -347,20 +515,32 @@ packages. If you're still learning Haskell and don't understand how ghc-pkg and Cabal work, *avoid platform* and instead use the install instructions earlier in the guide. +## Stackage + +For any users (usually Yesod users) that have build problems, consider Stackage. + +- A good summary of Stackage is + [here](https://www.fpcomplete.com/blog/2014/05/stackage-server). + +In the author's opinion, Stackage is usually more useful than `cabal freeze`. + +# Hoogle and Haddock + ## Search code by type signature The [Hoogle search engine](http://www.haskell.org/hoogle/) can search by type. -http://www.haskell.org/hoogle/?hoogle=%28a+-%3E+b%29+-%3E+%5ba%5d+-%3E+%5bb%5d +For example, look at the search results for `(a -> b) -> [a] -> [b]` +[here](http://www.haskell.org/hoogle/?hoogle=%28a+-%3E+b%29+-%3E+%5ba%5d+-%3E+%5bb%5d). Also hosted by fpcomplete [here](https://www.fpcomplete.com/hoogle). Also [Hayoo](http://holumbus.fh-wedel.de/hayoo/hayoo.html) (which has all of hackage enabled for search by default). -### Setting up your own local instance of Hoogle +## Setting up your own local instance of Hoogle -Take a look [here](https://gist.github.com/bitemyapp/3e6a015760775e0679bf) +Take a look [here](https://gist.github.com/bitemyapp/3e6a015760775e0679bf). ## Haddock @@ -371,7 +551,7 @@ Take a look [here](https://gist.github.com/bitemyapp/3e6a015760775e0679bf) Note that these posts are *slightly out of date*: for example, now Hackage sports shiny new info with documentation info and build status. -### What you really need to know +## What you really need to know In order to have haddocks include documentation for related packages, you have to set `documentation: True` in your `~/.cabal/config`. If it was left on the @@ -385,38 +565,31 @@ shell script. They will not work in a Makefile, because it will think they are Make variables! ```bash -#!/usr/bin/env sh +#! /usr/bin/env sh -cabal haddock --hoogle --hyperlink-source --html-location='http://hackage.haskell.org/package/$pkg/docs' --contents-location='http://hackage.haskell.org/package/$pkg' +# You can write it one one line by skipping the backslashes +cabal haddock --hoogle --hyperlink-source \ + --html-location='http://hackage.haskell.org/package/$pkg/docs' \ + --contents-location='http://hackage.haskell.org/package/$pkg' ``` -## What does that <- / do / list comprehension syntactic sugar do? - -Excellent [article](http://www.haskellforall.com/2014/10/how-to-desugar-haskell-code.html). - -## TravisCI +# TravisCI If you're as big a fan of [TravisCI](https://travis-ci.org) as I am, then I *strongly* recommend you take a look at [multi-ghc-travis](https://github.com/hvr/multi-ghc-travis) by as the basis of the `travis.yml` for your Haskell projects. -## Fun Stuff - -After you're comfortable with Haskell, strongly consider learning Lenses and -Prisms, even if just as a "user". You don't need to understand the underlying -category for it to be useful. - -Look here: [Lens package on hackage](http://hackage.haskell.org/package/lens). - -## Frontend/JavaScript +# Frontend/JavaScript We have an embarrassment of riches! There are three main choices I would recommend: * [Haste](http://haste-lang.org/) a Haskell to JavaScript compiler - The [compiler](https://github.com/valderman/haste-compiler) on github. - - An excellent [demo](http://www.airpair.com/haskell/posts/haskell-tutorial-introduction-to-web-apps) of Haste with an example project + - An excellent + [demo](http://www.airpair.com/haskell/posts/haskell-tutorial-introduction-to-web-apps) + of Haste with an example project. * [GHCJS](https://github.com/ghcjs/ghcjs) - [GHCJS Introduction](http://weblog.luite.com/wordpress/?p=14) @@ -429,7 +602,7 @@ recommend: - Try purescript in you browser [here](http://try.purescript.org/) - Great guide for [getting started](http://www.christopherbiscardi.com/2014/06/22/getting-started-with-purescript/) -### Which frontend language do I use? +## Which frontend language do I use? GHCJS and Haste are both fully Haskell. GHCJS will work with more Haskell packages than Haste, but this doesn't affect a lot of frontend @@ -444,48 +617,11 @@ and Haste integrate better with Haskell's tooling (Cabal). All three are great choices and will work for most frontend projects. -## Parsing in Haskell - -- Parser combinator [tutorial](https://github.com/JakeWheat/intro_to_parsing) - for Haskell using Parsec - -- [Writing your own micro-Parsec](http://olenhad.me/articles/monadic-parsers/) - -### Parsing and generating JSON - -Aeson is the standard [JSON](https://json.org) parsing solution in -haskell. Available from [hackage](https://hackage.haskell.org/package/aeson) and -[github](https://github.com/bos/aeson). - -- [Parsing JSON using Aeson](http://blog.raynes.me/blog/2012/11/27/easy-json-parsing-in-haskell-with-aeson/) - -- [Aeson and user created types](http://bitemyapp.com/posts/2014-04-11-aeson-and-user-created-types.html) - -- [Parsing non-deterministic data with aeson and sum types](http://bitemyapp.com/posts/2014-04-17-parsing-nondeterministic-data-with-aeson-and-sum-types.html) - -- [Aeson tutorial](https://www.fpcomplete.com/school/starting-with-haskell/libraries-and-frameworks/text-manipulation/json) - -## Laziness, strictness, guarded recursion - -- Marlow's [book](http://chimera.labs.oreilly.com/books/1230000000929/ch02.html) - about parallelism and concurrency has one of the best introductions to - laziness and normal form I've found. Use other material too if it doesn't - stick immediately. - -- [More points for lazy evaluation](http://augustss.blogspot.hu/2011/05/more-points-for-lazy-evaluation-in.html) - -- [Oh my laziness!](http://alpmestan.com/posts/2013-10-02-oh-my-laziness.html) - -- SO question '[Does haskell have laziness?](http://stackoverflow.com/questions/13042353/does-haskell-have-tail-recursive-optimization)' - -- [Johan Tibell](https://github.com/tibbe)'s slides from a talk on - [reasoning about laziness](http://www.slideshare.net/tibbe/reasoning-about-laziness). - -### For a more thorough understanding of laziness, NF, WHNF +# For a more thorough understanding of laziness, NF, WHNF - [Notes on lambda calculus](https://vec.io/posts/notes-on-lambda-calculus). -#### Research papers about lazy lambda calculi +## Research papers about lazy lambda calculi - [A call by need lambda calculus](http://homepages.inf.ed.ac.uk/wadler/topics/call-by-need.html#need-journal). @@ -493,32 +629,25 @@ haskell. Available from [hackage](https://hackage.haskell.org/package/aeson) and - [The lazy lambda calculus](http://www.cs.ox.ac.uk/files/293/lazy.pdf). -### Brief demonstration - -```haskell -let a = 1 : a -- guarded recursion, (:) is lazy and can be pattern matched. -let (v : _) = a -> v -1 -> head a -- head a == v -1 - -let a = 1 * a -- not guarded, (*) is strict -> a -*** Exception: <> -``` - - [Lazy evaluation of Haskell](http://www.vex.net/~trebla/haskell/lazy.xhtlm) -## Parallelism/Concurrency +# Parallelism/Concurrency -- [Parallel and Concurrent Programming in Haskell](http://chimera.labs.oreilly.com/books/1230000000929). This book by Simon Marlow is probably the best I've ever read on the topics of Parallelism and Concurrency. +- [Parallel and Concurrent Programming in Haskell](http://chimera.labs.oreilly.com/books/1230000000929). This + book by Simon Marlow is probably the best I've ever read on the topics of + Parallelism and Concurrency. -- A thorough [walk-through](http://kukuruku.co/hub/haskell/haskell-testing-a-multithread-application) on testing & incremental development of a multi-threaded application in Haskell +- A thorough [walk-through](http://kukuruku.co/hub/haskell/haskell-testing-a-multithread-application) + on testing & incremental development of a multi-threaded application in + Haskell. - [Functional Reactive Programming](http://www.haskell.org/haskellwiki/Functional_Reactive_Programming) -## Lenses and Prisms +# Lenses and Prisms + +After you're comfortable with Haskell, strongly consider learning Lenses and +Prisms, even if just as a "user". You don't need to understand the underlying +category for it to be useful. People vastly overestimate the difficulty of using Lens. Anybody comfortable with Functor/Foldable/Traversable (or even just the first one) can leverage @@ -533,80 +662,73 @@ I recommend these two tutorials/introductions: - [Lens: Lenses, Folds and Traversals](https://github.com/ekmett/lens#lens-lenses-folds-and-traversals) -## Monads and monad transformers +Look here for more information: [Lens package on hackage](http://hackage.haskell.org/package/lens). -### Do not do these until you understand typeclasses, Monoid, Functor, and Applicative! +# Recursion Schemes -Implement the standard library monads ( List, Maybe, Cont, Error, Reader, -Writer, State ) for yourself to understand them better. Then maybe write an -monadic interpreter for a small expression language using -[Monad Transformers Step by Step](http://www.cs.virginia.edu/~wh5a/personal/Transformers.pdf) -paper (mentioned in 'monad transformers' below). +Some of the crazy \*-morphism words you've heard are actually about +recursion. NB - before tackling this material you should know how to implement +foldr for lists and at least one other data structure, such as a tree. (folds +are catamorphisms) Knowing how to implement an unfold (anamorphism) for the same +will round things out a bit. -Writing many interpreters by just changing the monad to change the semantics can -help convey what's going on. +This material dovetails with traversable and foldable. -- [This talk](https://vimeo.com/73648150) by Tony excellently motivates monad - transformers. +- [An introduction to recursion schemes](http://patrickthomson.ghost.io/an-introduction-to-recursion-schemes/) -Also, reimplement `Control.Monad`. Functions like `mapM` or `sequence` are good -opportunities to practice writing generic monadic code. +- [Don't fear the cat](http://fho.f12n.de/posts/2014-05-07-dont-fear-the-cat.html) - + Good demonstration of how hylomorphism is the composition of cata and ana. -The NICTA course can be used as a guide to this process, which will also involve -writing your own Applicative as well. +- [Recursion Schemes](http://comonad.com/reader/2009/recursion-schemes/) - This + field guide is excellent. -Credits: +- [Functional Programming with Bananas, Lenses, Envelopes and Barbed Wire](http://eprints.eemcs.utwente.nl/7281/01/db-utwente-40501F46.pdf) -- Reddit comment by htmltyp and Crandom [here](http://www.reddit.com/r/haskell/comments/29eke6/basic_program_ideas_for_learning_about_monads/cik5aj6). +- [Catamorphisms](https://www.fpcomplete.com/user/edwardk/recursion-schemes/catamorphisms) -- Reddit comment by jozefg [here](http://www.reddit.com/r/haskell/comments/29eke6/basic_program_ideas_for_learning_about_monads/cik5trg). +# GHC Core and performance tuning -### Monad transformers +- [Write Haskell as Fast as C](write_haskell_as_fast_as_c.md) -- [A gentle introduction to Monad Transformers](https://github.com/kqr/gists/blob/master/articles/gentle-introduction-monad-transformers.md). +- [GHC Wiki: CoreSyn Type](https://ghc.haskell.org/trac/ghc/wiki/Commentary/Compiler/CoreSynType). -- [Monad transformers step-by-step](http://www.cs.virginia.edu/~wh5a/personal/Transformers.pdf) (warning, code out of date). +- [Hackage: GHC Core](https://hackage.haskell.org/package/ghc-core). -## Testing, tests, specs, generative/property testing +- [SO Question: Reading GHC Core](http://stackoverflow.com/questions/6121146/reading-ghc-core). -- This [tutorial](https://github.com/kazu-yamamoto/unit-test-example/blob/master/markdown/en/tutorial.md) by Kazu Yamamoto is fantastic. +- [Haskell as fast as C](http://donsbot.wordpress.com/2008/06/04/haskell-as-fast-as-c-working-at-a-high-altitude-for-low-level-performance/). -- [Simple-Conduit](https://github.com/jwiegley/simple-conduit): Good simple - library for learning how streaming IO works in general, knowledge - transferrable to libraries like Pipes and Conduit +- [Real World Haskell, Chapter 25: Profiling and Optimizations](http://book.realworldhaskell.org/read/profiling-and-optimization.html). -## Recursion Schemes +## Graph algorithms and data structures -Some of the crazy \*-morphism words you've heard are actually about -recursion. NB - before tackling this material you should know how to implement -foldr for lists and at least one other data structure, such as a tree. (folds -are catamorphisms) Knowing how to implement an unfold (anamorphism) for the same -will round things out a bit. +- The [fgl package](https://hackage.haskell.org/package/fgl) particularly the + purely functional shortest path [algos](http://hackage.haskell.org/package/fgl-5.4.2.2/docs/Data-Graph-Inductive-Query-SP.html). -This material dovetails with traversable and foldable. +- [Inductive graphs and Functional Graph Algorithms](http://web.engr.oregonstate.edu/~erwig/papers/abstracts.html#JFP01). -- [An introduction to recursion schemes](http://patrickthomson.ghost.io/an-introduction-to-recursion-schemes/) +- [FGL/Haskell - A Functional Graph Library](http://web.engr.oregonstate.edu/~erwig/fgl/haskell/old/fgl0103.pdf). -- [Don't fear the cat](http://fho.f12n.de/posts/2014-05-07-dont-fear-the-cat.html) - - Good demonstration of how hylomorphism is the composition of cata and ana. +- [Data.Graph source from Containers package](http://hackage.haskell.org/package/containers-0.5.5.1/docs/Data-Graph.html). -- [Recursion Schemes](http://comonad.com/reader/2009/recursion-schemes/) - This - field guide is excellent. +- The [graphs package](https://hackage.haskell.org/package/graphs). -- [Functional Programming with Bananas, Lenses, Envelopes and Barbed Wire](http://eprints.eemcs.utwente.nl/7281/01/db-utwente-40501F46.pdf) +- [SO question about PHOAS](http://stackoverflow.com/questions/24369954/separate-positive-and-negative-occurrences-of-phoas-variables-in-presence-of-rec) -- [Catamorphisms](https://www.fpcomplete.com/user/edwardk/recursion-schemes/catamorphisms) +- [PHOAS for free](https://www.fpcomplete.com/user/edwardk/phoas). -## Type and Category Theory (*not* needed to actually write Haskell, just for those interested!) +- [Tying the Knot](http://www.haskell.org/haskellwiki/Tying_the_Knot). -If you want to follow up on the type and category theory: +- [Hackage: dag](https://hackage.haskell.org/package/dag). -- [Catster's Guide](http://byorgey.wordpress.com/2014/01/14/catsters-guide/) and - [Catster's Guide 2](http://byorgey.wordpress.com/catsters-guide-2/) +# Type and Category Theory -- [Harper's Practical Foundations for Programming Languages](http://www.cs.cmu.edu/~rwh/plbook/book.pdf) is the best PL focused intro to type theory I've read. +> *Not* needed to actually write Haskell, just for those interested! -- [Quora Question: What is the best textbook for category theory?](http://www.quora.com/Category-Theory/What-is-the-best-textbook-for-Category-theory?share=1) Kmett's recommendations +If you want to follow up on type and category theory: + +- [Catster's Guide](http://byorgey.wordpress.com/2014/01/14/catsters-guide/) and + [Catster's Guide 2](http://byorgey.wordpress.com/catsters-guide-2/) - The [haskell wikibook](http://en.wikibooks.org/wiki/Haskell/Category_theory) has nice diagrams @@ -616,21 +738,27 @@ If you want to follow up on the type and category theory: - [Categories from scratch](http://science.raphael.poss.name/categories-from-scratch.html), Includes some practical examples. +- Pierce's [Great Works in PL](http://www.cis.upenn.edu/~bcpierce/courses/670Fall04/GreatWorksInPL.shtml) list. + +## Books + +- [Quora Question: What is the best textbook for category theory?](http://www.quora.com/Category-Theory/What-is-the-best-textbook-for-Category-theory?share=1) Kmett's recommendations + - [Awodey](http://ukcatalogue.oup.com/product/9780199237180.do) and [MacLane](http://www.amazon.com/Categories-Working-Mathematician-Graduate-Mathematics/dp/0387984038). The standard textbooks on category theory. -- [Type theory and Functional Programming](http://www.cs.kent.ac.uk/people/staff/sjt/TTFP/). - -- Pierce's [Great Works in PL](http://www.cis.upenn.edu/~bcpierce/courses/670Fall04/GreatWorksInPL.shtml) list. +- [Harper's Practical Foundations for Programming Languages](http://www.cs.cmu.edu/~rwh/plbook/book.pdf) is the best PL focused intro to type theory I've read. -### Stephen's Nifty "How to get to monad" posts +- [Type theory and Functional Programming](http://www.cs.kent.ac.uk/people/staff/sjt/TTFP/). -Didn't know where else to put these: +## Stephen's Nifty "How to get to monad" posts - [Adjunctions](http://www.stephendiehl.com/posts/adjunctions.html). - [Monads](http://www.stephendiehl.com/posts/monads.html). +# Other theoretical topics + ## Parametricity, ad-hoc vs. parametric polymorphism, free theorems - [Parametricity](tony_parametricity.pdf). @@ -673,89 +801,29 @@ Didn't know where else to put these: * [Part 2: Yoneda](http://comonad.com/reader/2011/free-monads-for-less-2/). * [Part 3: Yielding IO](http://comonad.com/reader/2011/free-monads-for-less-3/). -## IO - -- [Evaluation order and State tokens](https://www.fpcomplete.com/user/snoyberg/general-haskell/advanced/evaluation-order-and-state-tokens) - -Comment from Reddit thread by `glaebhoerl` - -Interesting side note: GHC needs to hide the state token representation behind -an abstract IO type because the state token must always be used linearly (not -duplicated or dropped), but the type system can't enforce this. Clean, another -lazy Haskell-like language, has uniqueness types (which are like linear types -and possibly different in ways I'm not aware of), and they expose the -World-passing directly and provide a (non-abstract) IO monad only for -convenience. - -- [Unraveling the mystery of the IO monad](http://blog.ezyang.com/2011/05/unraveling-the-mystery-of-the-io-monad/). - -- [First class "statements"](http://blog.jle.im/entry/first-class-statements). - -- [Haddocks for System.IO.Unsafe.unsafePerformIO](http://hackage.haskell.org/package/base-4.7.0.1/docs/System-IO-Unsafe.html#v:unsafePerformIO) - Read the docs and note implementation of unsafeDupablePerformIO - -## GHC Core and performance tuning - -- [Write Haskell as Fast as C](write_haskell_as_fast_as_c.md) - -- [GHC Wiki: CoreSyn Type](https://ghc.haskell.org/trac/ghc/wiki/Commentary/Compiler/CoreSynType). - -- [Hackage: GHC Core](https://hackage.haskell.org/package/ghc-core). - -- [SO Question: Reading GHC Core](http://stackoverflow.com/questions/6121146/reading-ghc-core). - -- [Haskell as fast as C](http://donsbot.wordpress.com/2008/06/04/haskell-as-fast-as-c-working-at-a-high-altitude-for-low-level-performance/). - -- [Real World Haskell, Chapter 25: Profiling and Optimizations](http://book.realworldhaskell.org/read/profiling-and-optimization.html). - -## Dependent typing - -- [Grokking sum types, value constructors, and type constructors](http://bitemyapp.com/posts/2014-04-05-grokking-sums-and-constructors.html) squint hard. - -- [Lightweight Dependent-type Programming](http://okmij.org/ftp/Computation/lightweight-dependent-typing.html). - -- [Idris programming language](http://www.idris-lang.org/). - ## Propositions vs. Judgments (computation) - [StackExchange question: What is the difference between propositions and judgements](http://cstheory.stackexchange.com/questions/9826/what-is-the-difference-between-propositions-and-judgments). - [Lecture notes from a short, three lecture course](http://www.ae-info.org/attach/User/Martin-L%C3%B6f_Per/OtherInformation/article.pdf) -## Graph algorithms and data structures - -- The [fgl package](https://hackage.haskell.org/package/fgl) particularly the shortest path algos [here](http://hackage.haskell.org/package/fgl-5.4.2.2/docs/Data-Graph-Inductive-Query-SP.html) which are pure. +# Dependent typing -- [Inductive graphs and Functional Graph Algorithms](http://web.engr.oregonstate.edu/~erwig/papers/abstracts.html#JFP01). - -- [FGL/Haskell - A Functional Graph Library](http://web.engr.oregonstate.edu/~erwig/fgl/haskell/old/fgl0103.pdf). - -- [Data.Graph source from Containers package](http://hackage.haskell.org/package/containers-0.5.5.1/docs/Data-Graph.html). - -- The [graphs package](https://hackage.haskell.org/package/graphs). - -- [SO question about PHOAS](http://stackoverflow.com/questions/24369954/separate-positive-and-negative-occurrences-of-phoas-variables-in-presence-of-rec) +- [Grokking sum types, value constructors, and type constructors](http://bitemyapp.com/posts/2014-04-05-grokking-sums-and-constructors.html) squint hard. -- [PHOAS for free](https://www.fpcomplete.com/user/edwardk/phoas). +- [Lightweight Dependent-type Programming](http://okmij.org/ftp/Computation/lightweight-dependent-typing.html). -- [Tying the Knot](http://www.haskell.org/haskellwiki/Tying_the_Knot). +- [Idris programming language](http://www.idris-lang.org/). -- [Hackage: dag](https://hackage.haskell.org/package/dag). +# Extended Reading list -## Extended Reading list (some are already included here) +> Some are already included here - [Essential Haskell Reading List](http://www.stephendiehl.com/posts/essential_haskell.html) -## Stackage - -For any users (usually Yesod users) that have build problems, consider Stackage. - -- A good summary of Stackage is - [here](https://www.fpcomplete.com/blog/2014/05/stackage-server). - -In the author's opinion, Stackage is usually more useful than `cabal freeze`. - ## Dialogues -[Dialogues](dialogues.md) these are actually pretty important and helpful. Look -here for deep dives on a variety of topics. +> Hosted in this repository [here](dialogues.md). + +These are actually pretty important and helpful. Look here for deep dives on a +variety of topics. diff --git a/tutorial.pdf b/tutorial.pdf new file mode 100644 index 0000000..d8e3a4f Binary files /dev/null and b/tutorial.pdf differ