ActiveHs Developer’s Documentation

This is the developer’s documentation of ActiveHs. To understand the terms used, please read the user’s guide first.

Main Components

ActiveHs has five main components, static files, web server, converter, interpreter and libraries:

DevDoc_enc45727a0abe3448fa3584fed761f0961.png

Green files are the user’s input.

libraries
The ActiveHs base libraries contain SVG graphics support and some auxiliary declarations. The base libraries should be imported in the .lhs files.
converter
The converter converts literate Haskell files with pandoc comments to xhtml files with the help of the pandoc library. The template files are used during this process. The template files may refer to the static files but these files are not needed during the conversion.
Inline latex and graphviz content in the comments will be converted to png files.
Exercises in the comments will be converted to exercise files.
static files
Static files are javascript and css files served statically.
These files are responsible for the slideshow mode and the AJAX input fields for the exercises in the xml files.
web server
The web server serves static files and .xml and .png files generated by the converter.
The web server also handles Haskell expression evaluation requests with the help of the interpreter and with the help of the exercise files generated by the converter.
interpreter
The interpreter is a specialized Haskell interpreter which can evaluate expressions, compare expressions, test definitions and check definitions (with quickcheck). The exercise files contain the information needed to perform these tasks.

Module Hierarchy

The following diagram contains the Haskell source files of ActiveHs (boxed nodes), the main dependencies between them (edges between boxes) and the main external dependencies (unboxed nodes).

The converter component consists of two modules: Parse and Compile (top part).
The web server component consists of the Main module and some auxiliary modules (Cache and Args; middle part).
The interpreter component consists of the remaining modules (bottom part).

DevDoc_eneac0e6acf6e333b3aa5ae0cc9f1a5255.png

Web Server Component

The web server component consists of the Main module and the Cache and Args auxiliary modules.

Schematic handling of requests:

DevDoc_en2d2f1d24663ba0ee7f66e51431599dbe.png

If a requested .xml file does not exists, but there is a corresponding .lhs file, or the .xml file exists but the corresponding .lhs file is newer, then first the converter will be invoked on the .lhs file, then the .xml file will be served.

There are four different post request corresponding to the four different interpreter actions (see below). In any case, the web server tries to serve a cached answer. If there is no cached answer, the interpreter will be invoked, and the answer will be cached and served.

The Cache module implements a very simple cache.

The Args module is responsible for the command-line arguments.

Converter Component

Conversion is done in two main phases which are implemented in the Parse and Compile modules.

Parse phase:

  1. Comments are filtered out.
  2. Parsing with the lhs + markdown pandoc reader function.
  3. Find and parse ActiveHs commands in pandoc’s inner document format.

Compile phase:

  1. ActiveHs commands are converted into the pandoc’s inner document format.
    During this process the interpreter component may be invoked.
  2. .dot and .latex code blocks are filtered out and converted into .png by external shell commands
  3. The xhtml file is produced by the corresponding padoc writer function.

Interpreter Component

The interpreter is built bottom-up as follows:

  1. hint package

    The hint package provides a simplified interface to the GHC API.

  2. Simple module

    This module provides an even more simplified and somewhat managed interface to hint.
    The main ideas are described here.

  3. Smart module

    This module adds more functionality to the interface of Simple.
    Main features added:

    • Type inference with the :t command
    • Kind inference with the :k command
    • Hoogle search with the :? command, based on HoogleCustom
    • Hoogle information search with the :i command, based on HoogleCustom
    • Automatic command selection (in most cases you don’t need :t, :k, :? or :i)
    • Type specialization, based on Specialize (needed for the next two features)
    • Prettyprint values, based on data-pprint (look at this for exaples)
    • Display numeric functions, based on dia-functions (look at this for exaples)
    • Display expressions with type Diagram, based on dia-functions (look at this for exaples)
    • Error logging, based on snap logger
    • Basic internationalization support

  4. Special module

    This module provides 4 special modes on top of Smart:

    • Expression evaluation
    • Expression comparison: Decide whether an expression is equal to a reference implementation.
    • Testing definitions: Decide whether the value of an expression is the same with the given and with the reference implementation.
    • Checking definitions: Decide whether a definition is equal functionally to a reference implementation.
      This mode is built on quickcheck and the definition testing mode.

Back to the main page

Main page