How To Write A Program In Haskell

Posted on  by

  1. How To Write A Program In Haskell Nj
  2. How To Write A Program In Haskell Ok
  3. How To Write A Haskell Program
  4. How To Write A Program In Haskell Ct
  5. How To Write A Program In Haskell Word

A developers' guide to creating a new Haskell project or program, and working in the Haskell developer ecosystem.

Most Haskell tutorials on the web use a style of teaching akin to language reference manuals. They show you the syntax of the language, a few language constructs, then tell you to create a few simple functions at the interactive prompt. The 'hard stuff' of how to write a functioning, useful program is left to the end, or omitted entirely.

  1. Writing a program to process csv data. One thing to note before we begin is that you can fire up a project-aware Haskell REPL using Stack’s GHCi command. The benefit of doing so is that you can write and type-check code interactively as you explore new and unfamiliar libraries or just to refresh your memory about existing code.
  2. Haskell/Getting set up. From Wikibooks, open books for an open world. Using the cooking analogy, you write a recipe (your Haskell program) and a cook. Every expression in Haskell has a type which is. You don't have to explicitly write out every type in a Haskell program. Write a haskell program. Expert's Help, Write a haskell program.
  3. Haskell is a widely used purely functional language. Functional programming is based on mathematical functions. Besides Haskell, some of the other popular languages that follow Functional Programming paradigm include: Lisp, Python, Erlang, Racket, F#, Clojure, etc. Haskell is more intelligent than other popular programming languages such as Java, C, C, PHP, etc.

Note: for learning the Haskell language itself we recommend these resources.

  • 1Recommended tools
  • 2Structure of a simple project
    • 2.9Add some tests
    • 2.10Tag the stable version, create a tarball, and sell it!
      • 2.10.1Create a tarball
  • 3Libraries
  • 8The user experience
  • 10Publicity

Recommended tools

Almost all new Haskell projects use the following tools. Each isintrinsically useful, but using a set of common tools also helpseveryone by increasing productivity, and you're more likely to getpatches.

Revision control

Use git or darcs unless you have a specific reason not to. Both are lightweight distributed revision control system. Darcs is written in Haskell. They are the two most popular DVCSes in the Haskell world. If you want to encourage contributions from other Haskell hackers then git is best. For git, GitHub is very popular. Darcs hosting is available on hub.darcs.net.

Build system

Use Cabal.You should read at least the start of section 2 of the Cabal User's Guide.

You should use cabal-install as a front-end for installing your Cabal library. Cabal-install provides commands not only for building libraries but also for installing them from, and uploading them to, Hackage. As a bonus, for almost all programs, it's faster than using Setup.hs scripts directly, since no time is wasted compiling the scripts. (This does not apply for programs that use custom Setup.hs scripts, since those need to be compiled even when using cabal-install.)

cabal-install is widely available, as a binary distribution or as part of the Haskell Platform, so you can probably assume your users will have it too.

Documentation

For libraries, use Haddock. Haddock generates nice markup, with links to source.

Testing

Typical unit/spec based testing, particularly with impure code, can be done with HSpec and HUnit.

You can use QuickCheck or SmallCheck to test pure code. These libraries work best when you have known invariants in your code's behavior. See this Cabal file for an example of how to include tests in your Cabal package.

To get started, try Introduction to QuickCheck. For a slightly more advanced introduction, Simple Unit Testing in Haskell is a blog article about creating a testing framework for QuickCheck using some Template Haskell. For HUnit, see HUnit 1.0 User's Guide

doctest is another testing method similar to python Doctest

Distribution

The standard mechanism for distributing Haskell libraries andapplications is Hackage. Hackage canhost your cabalised tarball releases, and link to any librarydependencies your code has. Users will find and install your packages via 'cabal install', and your package will be integrated into Haskell search engines, like hoogle

Target Environment

If possible, depend on libraries that are provided by the current stable Stackage package versions or the Haskell Platform. Ideally your package should be able to build with users that keep current with Stackage or users of the Platform.

Structure of a simple project

The basic structure of a new Haskell project can be adopted fromHNop, the minimal Haskell project. Itconsists of the following files, for the mythical project 'haq'.

  • Haq.hs -- the main haskell source file
  • haq.cabal -- the cabal build description
  • Setup.hs -- build script itself
  • .git -- revision control
  • README -- info
  • LICENSE -- license

Of course, you can elaborate on this, with subdirectories and multiplemodules. See Structure of a Haskell project for an example of a larger project's directory structure.

Here is a transcript that shows how you'd create a minimal git and cabalisedHaskell project for the cool new Haskell program 'haq', build it,install it and release.

Note: The new tool 'cabal init' automates all this for you, but you shouldunderstand all the parts even so.

We will now walk through the creation of the infrastructure for a simpleHaskell executable. Advice for libraries follows after.

Create a directory

How To Write A Program In Haskell Nj

Create somewhere for the source:

Write some Haskell source

Write your program:

How To Write A Program In Haskell Ok

Stick it in version control

Place the source under revision control (you may need to enter your e-mail address first, to identify you as maintainer of this source):

Add a build system

Create a .cabal file describing how to build your project:

that will ask a few questions about your project and generate a file similar to the example:

(If your package uses other packages, e.g. text, you'll need to add them to the build-depends: field as a comma separated list.)

Cabal will also generate a Setup.hs file that will do the actual building. You will rarely need to modify it.

If you specifed a known license, it will also add a LICENSE file.

You might like to add a README file to tell what your project is about.

Record your changes:

Build your project

Now build it! There are two methods of accessing Cabal functionality: through your Setup.hs script or through cabal-install. cabal-install is now the preferred method.

Building using cabal-install and sandboxes, always use sandboxes in your projects unless you are an expert and know what you are doing! Demonstrated here:

This will install your newly minted haq program in $PROJECT_DIR/.cabal-sandbox/bin.

Run it

And now you can run your cool project:

Since our program doesn't rely on any other assets we can just copy it to a directory in our path if we want to be able to use it from anywhere without referencing the sandbox directory. Like so:

Build some haddock documentation

Generate some API documentation into dist/doc/*

Using cabal install:

Using cabal install if you planned to upload your haq package to Hackage:
$ cabal haddock --hyperlink-source --html-location='http://hackage.haskell.org/package/haq/docs' --contents-location='http://hackage.haskell.org/package/haq'

which generates files in dist/doc/ including:

No output? Make sure you have actually installed haddock. It is a separate program, not something that comes with Cabal. Note that the stylized comment in the source gets picked up by Haddock.

(Optional) Improve your code: HLint

HLint can be a valuable tool for improving your coding style, particularly if you're new to Haskell. Let's run it now.

The existing code will work, but let's follow that suggestion. Open Haq.hs in your favourite editor and change the line:

to:

Add some tests

HSpec

If you'd like to use HSpec:

To your cabal, add:

To enable tests and install HSpec (and any other needed dependencies):

$ cabal install --enable-tests

Then for your actual file containing the test code:

Execute the tests with:

$ cabal test

QuickCheck

If you're using QuickCheck:

To run the test:

Success!

Tag the stable version, create a tarball, and sell it!

Tag the stable version:

Create a tarball

You can do this using either Cabal or an explicit tar command.

Using Cabal

How To Write A Haskell Program

Since the code is cabalised, we can create a tarball with cabal-installdirectly (you can also use runhaskell Setup.hs sdist, but you need tar on your system [1]):

This has the advantage that Cabal will do a bit more checking, andensure that the tarball has the structure that HackageDB expects. Note that it does require the LICENSE file to exist.It packages up the files needed to build the project; to include other files (such as Test.hs in the above example, and our README), we need to add:

extra-source-files: Tests.hs README

to the .cabal file to have everything included.

Check that your source package is complete

Just to make sure everything works, try building the source package in some temporary directory:

and for packages containing libraries,

Upload your package to Hackage

Whichever of the above methods you've used to create your package, you can upload it to the Hackage package collection via a web interface.You may wish to use the package checking interface there first, and fix things it warns about, before uploading your package.

Upload your package documentation to Hackage

Assuming you built your documentation like this:

$ cabal haddock --hyperlink-source --html-location='http://hackage.haskell.org/package/haq/docs' --contents-location='http://hackage.haskell.org/package/haq'

You can force upload (so you don't have to wait on the server to build it for you) your documentation for your package like so:

$ cp -R ./dist/doc/html/haq/ haq-0.0-docs$ tar cvzf --format=ustar -f haq-0.0-docs.tar.gz haq-0.0-docs$ curl -X PUT -H 'Content-Type: application/x-tar' -H 'Content-Encoding: gzip' --data-binary '@haq-0.0-docs.tar.gz' 'https://$USERNAME:$PASSWORD@hackage.haskell.org/package/haq-0.0/docs'

Summary

The following files were created:

Libraries

The process for creating a Haskell library is almost identical. The differencesare as follows, for the hypothetical 'ltree' library:

Hierarchical source

The source should live under a directory path that fits into theexisting module layout guide.So we would create the following directory structure, for the moduleData.LTree:

So our Data.LTree module lives in Data/LTree.hs

The Cabal file

Cabal files for libraries list the publically visible modules, and haveno executable section:

We can thus build our library:

and our library has been created as a object archive. Now install it:

And we're done!To try it out, first make sure that your working directory is anything but the source directory of your library:

And then use your new library from, for example, ghci:

The new library is in scope, and ready to go.

More complex build systems

For larger projects, you may want to store source trees in subdirectories. This can be done simply by creating a directory -- for example, 'src' -- into which you will put your src tree.

To have Cabal find this code, you add the following line to your Cabalfile:

You can also set up Cabal to run configure scripts, among other features. For more information consult theCabal user guide.

Licenses

Code for the common base library package must be BSD licensed. Otherwise, itis entirely up to you as the author.Choose a licence (inspired by this).Check the licences of things you use (both other Haskell packages and Clibraries), since these may impose conditions you must follow.Use the same licence as related projects, where possible. The Haskell community issplit into 2 camps, roughly: those who release everything under BSD, and(L)GPLers. Some Haskellers recommend avoiding LGPL, due to cross-module optimisationissues. Like many licensing questions, this advice is controversial. Several Haskell projects(wxHaskell, HaXml, etc) use the LGPL with an extra permissive clause which gets round thecross-module optimisation problem.

Releases

It's important to release your code as stable, tagged tarballs. Don't just rely on your commit hashes for tracking history, tag your released versions and milestones!

  • git archive generates tarballs directly from a git repository based on the provided tag.

For example:

You can now just post your fps-0.8.tar.gz


  • Tag each release using git tag. For example:

Hosting

Hosting for repos is available from Github and the Haskell community server

There is also a (minimal) Github equivalent for Darcs at hub.darcs.net.

Web page

Create a web page documenting your project! An easy way to do this is toadd a project specific page to the Haskell wiki

The user experience

When developing a new Haskell library, it is important to remember how the user expects to be able to build and use a library.

Introductory information and build guide

A typical library user expects to:

  1. Visit Haskell.org
  2. Find the library/program they are looking for:
    1. if not found, try mailing list;
    2. if it is hidden, try improving the documentation on haskell.org;
    3. if it does not exist, try contributing code and documentation)
  3. Download
  4. Build and install
  5. Enjoy

Each of these steps can pose potential road blocks, and code authors cando a lot to help code users avoid such blocks. Steps 1..2 may be easy enough, and many coders and users are mainly concerned with step 5. Steps 3..4 are the ones that often get in the way. In particular, thefollowing questions should have clear answers:

  • Which is the latest version?
  • What state is it in?
  • What are its aims?
  • Where is the documentation?
  • Which is the right version for given OS and Haskell implementation?
  • How is it packaged, and what tools are needed to get and unpack it?
  • How is it installed, and what tools are needed to install it?
  • How do we handle dependencies?
  • How do we provide/acquire the knowledge and tool-chains needed?

The best place to answer these questions is a README file,distributed with the library or application, and often accompanied withsimilar text on a more extensive web page.

Tutorials

Generated haddock documentation is usually not enough to help newprogrammers learn how to use a library. You must also provide accompanying examples, and even tutorials about the library.

Please consider providing example code for your library or application. The code should be type-correct and well-commented.

Program structure

Monad transformers are very useful for programming in the large,encapsulating state, and controlling side effects. To learn more about this approach, try Monad Transformers Step by Step.

Publicity

The best code in the world is meaningless if nobody knows about it. Theprocess to follow once you've tagged and released your code is:

Join the community

If you haven't already, join the community. The best way to do this is to subscribe to at least haskell-cafe@ and haskell@ mailing lists. Joining the #haskell IRC channel is also an excellent idea.

Announce your project on haskell@

Write

Most important: announce your project releases to the haskell@haskell.org mailing list. Tag your email subject line with 'ANNOUNCE: ...'. This ensure it will then make it into the Haskell Weekly News. To be doubly sure, you can email the release text to the HWN editor.

Add your code to the public collections

  • Add your library or application to the Libraries and tools page, under the relevant category, so people can find it.
  • If your release is a Cabal package, add it to the Hackage database
  • If your library stays up to date with its dependencies, add it to the vetted packages on Stackage.

Blog about it

How To Write A Program In Haskell Ct

Blog about it! Blog about your new code on Planet Haskell.Write about your project in your blog, then email the Planet Haskell maintainer (ibid on #haskell) the RSS feed url for your blog

How To Write A Program In Haskell Word

Retrieved from 'https://wiki.haskell.org/index.php?title=How_to_write_a_Haskell_program&oldid=62587'