well-typed / visualize-cbn Goto Github PK

License: BSD 3-Clause "New" or "Revised" License

Haskell 99.50% HTML 0.50%

visualize-cbn's Introduction

Call-by-name interpretation and visualization tool

Haskell and other call-by-name languages use lazy evaluation as their default evaluation strategy. For beginners and advanced programmers alike this can sometimes be confusing. The visualize-cbn tool is designed to help in such cases; it is a simple interpreter for a mini-Haskell-like language which outputs the state of the program at every step in a human readable format. It can also generate a HTML/JavaScript version with "Previous" and "Next" buttons to allow to step through a program.

Example

Consider the following example program:

fac = (\n ->
    if le n 1
      then 1
      else mul (@fac (sub n 1)) n
  )

main = @fac 1

The syntax is not quite Haskell, but hopefully it should be pretty self-explanatory. The parser is pretty finicky; look at some of the examples in examples/ to deduce what the syntax is. The only somewhat odd feature is the identifies marked with an at-sign (@); these corresponds to pointers in the heap. For programs in their initial state (i.e., as written down), the only heap pointers we expect are to CAFs (constant applicative forms; values defined at the top-level of the program).

Stepping through

We can step through the evaluation of this program using

visualize-cbn -i examples/fac.hs --show-trace --hide-prelude 0

This will result in something like

** 0

fac 1

(apply fac)

** 1

if 1 <= 1
  then 1
  else fac (1 - 1) * 1

(delta: 1 <= 1)

** 2

if True
  then 1
  else fac (1 - 1) * 1

(if True)

** 3

1

(whnf)

At every step it lists the current state of the program, as well as the reduction rules that apply. There are some options for tweaking the output; see --help.

Generating HTML/JavaScript

The tool can also generate HTML/JavaScript:

cr visualize-cbn -i examples/fac.hs --javascript foo.js

The resulting .js file can be embedded in a HTML page (such as a blog post); a minimal HTML page illustrating how this is done is given by

<html>
<body>

<a onclick="cbnPrev()">Prev</a>
<a onclick="cbnNext()">Next</a>
(step <span id="cbn_step">Step</span>, <span id="cbn_status">Status</span>)

<table width="100%" border="1" cellpadding="5" style="border-collapse: collapse;">
<tr><td><div style="font-family: monospace;" id="cbn_term">Term</div></td></tr>
<tr><td><div style="font-family: monospace;" id="cbn_heap">Heap</div></td></tr>
</table>

<script type="text/javascript" src="foo.js"></script>

</body>
</html>

(This .html file was not written to illustrate HTML best practices :-) ) See the Well-Typed blog post about the tool for an example output.

visualize-cbn's People

Contributors

Stargazers

Watchers

Forkers

racko yigitozkavci andrewbutterfield kderme silky adinapoli wataru86 andreasabel

visualize-cbn's Issues

Improving Graph

One of the issues I mentioned at #12
Function applications are indeed unevaluated thunks, however they can have their own layout, like here https://ghc.haskell.org/trac/ghc/wiki/Commentary/Rts/Storage/HeapObjects#Genericapplication

For the example above we could have two additional nodes, one for the function and one for 1.

Can it support complex expression like the following?

https://stackoverflow.com/questions/61123307/how-to-print-intermediate-result-in-functor-and-applicative-in-haskell

The option `--hide-prelude` expects an argument.

I tried Stepping through as follows:

ubuntu@vm1:~/visualize-cbn$ ~/.local/bin/visualize-cbn -i examples/fac.hs --show-trace --hide-prelude
The option --hide-prelude expects an argument.

Usage: visualize-cbn -i INPUT-FILE [--show-trace] [--gc] [--selector-thunk-opt]
                     [--inline-heap] [--collapse-beta] [--max-num-steps N]
                     [--hide-prelude STEP] [--hide-term ARG] [--hide-gc]
                     [--hide-selector-thunk-opt] [--hide-inlining]
                     [--javascript JS-FILE] [--javascript-function JS-NAME]
                     [--graph GRAPH-FILE] [--heap-graph PATH/FILES-PREFIX]
                     [--disable-ansi]

--hide-prelude STEP

What should I specify for STEP?

Add graph visualization

An option to create a graph visualization would be tremendously useful.

Show the rule/equation it will use for the next step

For example, in this example from the blog post

Prev Next (step 1, next step: apply enumFromTo)

case enumFromTo 1 3 of { 
      []    -> 0
      x:xs' -> length (1 + 0) xs'
}

It would be very neat to also see the definition of enumFromTo and a note of what the values are. Something like this:

Will apply enumFromTo, with n = 1 and m = 3:
enumFromTo = (\n -> \m ->
  if le n m then Cons n (@enumFromTo (add n 1) m)
            else Nil
)

This should probably be a separate feature request but it would also be very helpful to highlight the parts of the code where the rule will be applied. In particular when the next step is selecting a branch of a case expression. To be extra clear, we could highlight the parameters of the rule with different colours.

Confusing error message: "deref: invalid pointer"

$ cat t.hs
span = (\p -> \xs ->
  case xs of {
   Nil -> Pair xs xs ;
   Cons x xs' ->
     if p x then
      let res = @span p xs'
      in Pair (case @res of { Pair ys zs -> Cons x ys})
              (case @res of { Pair ys zs -> zs })
     else Pair Nil xs
  }
)

main = case (@span (\x -> True) (Cons 1 (Cons 2 (Cons 3 Nil)))) of {
  Pair ys zs -> case ys of {
    Cons y ys2 -> ys ;
    Nil -> ys
    }
  }

$ git log -1
commit d8a1ebc0a29d68b5dde8d8fbadd6c85bc47c6a7b
Author: Edsko de Vries <[email protected]>
Date:   Fri Sep 15 17:27:40 2017 +0200

    Add README
$ .cabal-sandbox/bin/visualize-cbn -i t.hs --show-trace --hide-prelude
...
visualize-cbn: deref: invalid pointer Ptr Nothing (Just "res")
CallStack (from HasCallStack):
  error, called at src/CBN/Heap.hs:78:26 in main:CBN.Heap

Indirections

Indirections like on the left can be eliminated. However they can also have circles like on right, so not sure what should be done.