AcitveHs User’s Guide

Introduction

ActiveHs is a Haskell source code presentation tool, developed for education purposes.

The software is in prototype phase, although it already served more than 700 000 user requests at Eötvös Loránd University Budapest, Hungary.

Note that this software has many rough edges; you are welcome to work on it!

Typical Usage

  1. Installation
  2. Start the activehs server near an .lhs file
  3. Open http://localhost:8000/Modulename.xml in a browser
  4. Modify the .lhs file(s) & reload the page
  5. Interact with the page
  6. Go back to 4. if needed
  7. Present your sources as interactive xhtml slides
  8. Make your activehs server accessible from the internet

Installation

ActiveHs installation:

  1. cabal update
  2. cabal install activehs

The activehs package depends on the pandoc and snap-server packages, so they will be installed automatically.
However, I propose to install them manually with the following flags:

The following software components are optional, but should be installed separately:


I had some linker error during linking the activehs executable. It was about an undefined symbol in the Hoogle library and I have made a workaround about it.

Command-Line Options

For basic usage you don’t have to give any options; just run activehs in a directory with .lhs files inside.

See activehs --help for more help on command-line options.

Markup Overview

Only literate Haskell files are supported (with .lhs extension).

After the module name import the ActiveHs.Base module:

> module Example where
>
> import ActiveHs.Base

Note that the module header and the import list should be in the same code block (no empty lines between them)!

Markup which can be used in top level comments:

Graphviz Code Segments

Example:

~~~~~ {.dot}
A -> B -> C -> B
A -> C
~~~~~

Output:

UsersGuide_en310cbd5d242cd1372b81fb1d542282f3.png

Example:

~~~~~ {.neato}
A -> B -> C -> B
A -> C
~~~~~

Output:

UsersGuide_enfef8a2348329fed311fd887ed61c7d37.png

You can use the .dot, .neato, .twopi, .circo, .fdp, .dfdp segment names.

See the graphviz gallery for more complex examples.

LaTeX Code Segments

LaTeX code segments will be converted into .png pictures.

Example:

~~~~~~ {.latex}
\mbox{min}(x,y) = 
\left\{\begin{array}{ll}
x&\mbox{if }x\le y,
y&\mbox{otherwise}.
\end{array}\right.
~~~~~~

Output:

UsersGuide_en72ad06fe7d8059deb6cc8c49e2ca3bdd.png

Slides

Pressing key ‘a’ in the browser switch between slide and normal mode.

Markup example:

First Slide
===========

slide content

*********

remark


Second Slide
============

slide content

*********

remark

Each level one header starts a new slide.

In slide mode the remarks are not visible. Remarks are the content after the first horizontal rule after each level one header.

ActiveHs Commands Overview

Every ActiveHs command begins with a letter followed by a > character and a space.

ActiveHs commands:

E> Evaluation
F> Folded evaluation
A> Answer: show just the evaluated expression
R> Reply hidden; one should guess it
H> Hidden test case

Evaluation Command

Example:

E> [1..]

Output (interactive form):

Test>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19,
 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36,
 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53,
 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70,
 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87,
 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103,
 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116,
 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129,
 130, 131, 132, 133, 134, 135, …, ……]
:: [Integer]

Example:

E> sin . abs

Output:

Test>

Example:

E> :t [1..]

Output:

Test>
[1..] :: (Enum t, Num t) => [t]

You may use the following colon-commands, but these are applied automatically too:

For other features see these guides:

Folded Evaluation and Answer Commands

Evaluation example:

E> 1 + 1

Output:

Test>
2 :: Integer

Folded evaluation example:

F> 1 + 1

Output:

Test>

Answer example:

A> 1 + 1

Output:

2 :: Integer

Folded evaluation is the same as evaluation, but the result is not shown for the first time.

Answer is the same as evaluation, but only the result is shown.

Reply Command

Example:

Give an expression which is equal to the number of seconds in a day!

R> 60 * 60 * 24

Output:

Give an expression which is equal to the number of seconds in a day!

Solution>

If the equality cannot be checked for several reason, you get a reasonable detailed answer.
See the second half of this page.

Exercises

It is possible to give more complex exercises to the readers.

Example:

Define the function `inc` which increments a number.

> inc :: Num a => a -> a
> inc = (+1)

E> inc 3
E> inc (4+4)

Output:

Define the function inc which increments a number.

inc :: Num a => a -> a

Test>
4 :: Integer
Test>
9 :: Integer

What happens here?

  1. The definition of inc was replaced by a form in the output. ActiveHs do this if literate Haskell code is immediately followed by ActiveHs commands like E>.
  2. The user fill in the form (define inc here) and click on Check below the form.
  3. The server will check the form content. The test cases are derived from the ActiveHs commands immediately after the literate Haskell code.
    For example, if the command is E> inc 3, then the test case will be inc 3 == Original.inc 3, where inc is the function defined by the user and Original.inc is the definition given in the .lhs file.
  4. If a the test case fails, a from will appear with that test case.
    For example, if the user defines inc = (+2), then E> inc 3 fails, and 5 /= 4 will be shown because inc 3 is not equal to Original.inc 3.
  5. If all tests cases succeeds, an empty form will be shown in which the user can enter more tests.

Exercises / QuickCheck tests

It is possible to give QuickCheck tests in exercises with the H> (Hidden test) command.

Example:

Define a function `plus` which adds two numbers.

> plus :: Int -> Int -> Int
> plus a b = a + b

H> QCInt a ;; QCInt b ;; plus a b

Output:

Define a function plus which adds two numbers.

plus :: Int -> Int -> Int

(Try to define plus a b = 10 `min` a + b)


Syntax of QuickCheck tests:

pattern1 ;; pattern2 ;; … ;; patternn ;; expression

QCInt is a constructor which helps type checking. Definition of QCInt is in the ActiveHs.Base module:

newtype QCInt = QCInt Int
    deriving (Show, Arbitrary)

ActiveHs.Base defines to other constructors QCBool and QCNat.
Definition of QCNat:

newtype QCNat = QCNat Int
    deriving (Show)

instance Arbitrary QCNat where
    ....

You can define your own helper-constructors.
Just put the definitions in a separate visible module and import that module in the .lhs file.

Customization

You can customize the generated xml files with templates.
The template mechanism is the following:

  1. The actives server decides the language of the .lhs file.
    The language is guessed from the end of the filename, before the extension and after the last underline. For example, if the file name is Index_en.lhs, then the language is en.
    If the language cannot be guessed then the default language is used which is en. The default language can be changed by a command-line option.
  2. The server use the template file named language.template, like en.template. You can give the directory to search template files in with a command-line argument.
    If you do not specify a template directory, the distribution’s directory will be used which contains the en.template and hu.template template files.
  3. In the template file you give the skeleton of the generated xml files. For example, you can import any custom css files.

Currently there is no decent way to internationalize the messages of the activehs server. There is built-in support for English and Hungarian though; see the Lang.hs file in sources.

Internet Access

If your activehs server is accessible from the internet, I advise the following:

Developer’s Documentation

If you are interested, you can read the Developer’s Documentation.

Back to the main page

Main page