% ActiveHs Developer's Documentation

> module DevDoc_en where
>
> import ActiveHs.Base
> import MyPrelude
> import Prelude ()

| feltolni a githubra
| feltenni a hackagedbre
| feltenni a redditre
| írni levelet Ambrusnak, Gábornak és a srácnak

This is the developer's documentation of ActiveHs. To understand the terms used, [please
read the user's guide first](UsersGuide_en.xml).


Main Components
===============

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

~~~~~~~~~ {.dot}
Node [shape = none]
xml [label = ".xml, .png"]
exercise [label = "exercise\nfiles"]

javascript [label = <<FONT POINT-SIZE="20.0" COLOR="black">static files</FONT><BR/>.js, .css>]
server [label = <<FONT POINT-SIZE="20.0" COLOR="black">web server</FONT>>]
converter [label = <<FONT POINT-SIZE="20.0" COLOR="black">converter</FONT>>]
interpreter [label = <<FONT POINT-SIZE="20.0" COLOR="black">interpreter</FONT>>]
libraries [label = <<FONT POINT-SIZE="20.0" COLOR="black">libraries</FONT>>]
converter -> xml

converter -> exercise

Node [color = darkgreen, fontcolor = darkgreen]
lhs [label = ".lhs"]
lhs -> converter
template [label = ".template"]
template -> converter

Node [color = "#606060", fontcolor = "#606060"]
Edge [color = "#606060"]

server -> xml
server -> exercise
javascript -> server [dir = back]
template -> javascript
libraries -> lhs [dir = back]
interpreter -> exercise [dir = none]

{rank = same; libraries; template; javascript; lhs}
lhs -> template [style = invis]
{rank = same; exercise; interpreter}
~~~~~~~~~

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).

~~~~~~~~~ {.dot}
Graph [rankdir = RL]

Node [shape = box]
Simple -> Smart -> Special -> Main
Parse -> Compile -> Main

Node [shape = none]
hint -> Simple
snap -> Main
pandoc -> Parse

Node [color = "#606060", fontcolor = "#606060"]
Edge [color = "#606060"]

Node [shape = box]
Specialize -> Smart
HoogleCustom -> Smart
Result -> Special
QuickCheck -> Special
Qualify -> Special
Cache -> Main

Node [shape = none]
hoogle -> HoogleCustom
quickcheck -> QuickCheck
"data-pprint" -> Smart
"dia-functions" -> Smart

Node [color = gray, fontcolor = gray]
Edge [color = gray]

Node [shape = box]
Lang -> Smart
Html -> Result
Args -> Main
Smart -> Compile [constraint = false]

Node [shape = none]
cmdargs -> Args
xhtml -> Html
"haskell-src" -> Parse
"snap logger" -> Smart
~~~~~~~~~


Web Server Component
====================

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

Schematic handling of requests:

~~~~~~~~~ {.dot}
Graph [rankdir = LR]
Node [shape = none]
request -> get
request -> post
get -> "simple fileserve"
get -> "generate file from .lhs & serve"
post -> "interpreter action, maybe from cache"
~~~~~~~~~

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.
1.  Parsing with the lhs + markdown pandoc reader function.
1.  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.
1.  .dot and .latex code blocks are filtered out and converted into .png by external shell commands
1.  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.](Economic_en.xml)
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](Show_en.xml))
    -   Display numeric functions, based on `dia-functions` ([look at this for exaples](FunctionGraphs_en.xml))
    -   Display expressions with type `Diagram`, based on `dia-functions` ([look at this for exaples](Diagrams_en.xml))
    -   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.