• Stars
    star
    99
  • Rank 343,315 (Top 7 %)
  • Language
    OCaml
  • License
    BSD 3-Clause "New...
  • Created almost 9 years ago
  • Updated about 5 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

OCaml interpreter

OCamli

OCamli is a proof-of-concept step-by-step interpreter for OCaml programs intended for teaching purposes and, eventually, as a debugger. It works by reading an OCaml program into an abstract syntax tree, then interpreting the AST one reduction at a time, optionally displaying each reduction and underlining the reducible expression. For example:

showall

With just -show instead:

show

Running the classic factorial program, using a set of options to elide parts of the output (there are too many options, and the interface will be improved):

factorial

Mutable code

Some of ocamli's output is a little low-level for now, but it's important to emulate what OCaml itself does by making the actual calls to primitives like %setfield0:

mutable

Input/Output

Sometimes the approach of printing everything gets far too much. We will need methods for hiding this internal detail by default:

printint

Standard Library Functions

You should be able to use some or most of the Standard Library functions. Presently Printf and Scanf are not loaded due to bugs.

listmap

Searching

"I want to see the last few steps before factorial (4 - 1)":

search

Examples

The directory examples contains a number of little programs written for development.

The directory OCaml from the Very Beginning contains all the examples and exercises from the beginner's OCaml textbook.

Paper

The eventual use of ocamli as a debugger is sketched in the position paper "Visualizing the Evaluation of Functional Programs for Debugging", given at SLATE'17 in June.

Selected command line options

eval <filename | -e program> [-- arg1 arg2 ...]

Loading and runnning programs:

  • -e <string> Evaluate the program text given
  • -show Print the final result of the program
  • -show-all Print steps of evaluation
  • -e-name <string> Set the module name for the next -e instance
  • -no-stdlib Don't load the standard library (for speed)

Multiple files and -e options may be given, and will be treated as zero or more modules followed by one main program.

Searching:

  • -search <search-term> Show only matching evaluation steps
  • -regexp Search terms are regular expressions rather than the built-in system
  • -invert-search Invert the search, showing non-matching steps
  • -highlight Highlight the matching part of each matched step.
  • -n <integer> Show only results
  • -until <search-term> show only until this matches a printed step
  • -after <search-term> show only after this matches a printed step
  • -until-any <search-term> show only until this matches any step
  • -after-any <search-term> show only after this matches any step
  • -invert-after invert the after condition
  • -invert-until invert the until condition
  • -stop stop computation after final search results
  • -repeat allow the after...until result to be repeated.
  • -upto <n> show n lines up to each result line
  • -times <n> Do many times

Interaction:

  • -prompt Require enter after each step but last
  • -step / Wait a number of seconds after each step but last

Elision:

  • -remove-rec <string> Do not print the given recursive function
  • -remove-rec-all Do not print any recursive functions
  • -show-pervasives Show Pervasives such as :=
  • -fast-curry Apply all curried arguments at once.
  • -show-stdlib-init Show initialisation of standard library
  • -no-arith Ellide simple arithmetic
  • -no-if-bool Don't show if false, if true stage
  • -no-var-lookup Don't show stage immediately after variable lookup
  • -side-lets Show value-lets at the side

Configuration:

  • -pp Set the prettyprinter "normal" or "simple" (default)
  • -width Set the output width
  • -top Do nothing, exit cleanly (for top level)
  • -dtiny Show Tinyocaml representation
  • -dpp Show the pretty-printed program
  • -debug Debug (for OCAMLRUNPARAM=b)
  • -no-syntax Don't use syntax highlighting
  • -no-typecheck Don't typecheck
  • -no-collect Don't collect unused lets
  • -otherlibs Location of OCaml otherlibs folder (Unix, Bigarray, Str)

Implementation

The ocamli interpreter requires no patches to the OCaml compiler; it is implemented entirely using compiler-libs.

The OCaml program is lexed and parsed by compiler-libs, typechecked, then the parse tree is converted to a simpler, more direct datatype, called Tinyocaml.

The Tinyocaml representation is then interpreted step-by-step, optionally printing each stage out. We use a custom prettyprinter, but hope to eventually contribute back to the standard one.

Keeping ocamli in sync with OCaml will involve updating it to reflect any changes in the compiler-libs API and adding any new features added to the OCaml languages. So, we will have ocamli 4.05 for OCaml 4.05 and so on.

The ocamli facilities for conversing with C code (such as OCaml %external declarations) are based on reading and writing OCaml heap values. The interpreter and the interpreted program and the compiled parts live in the same process with the same OCaml runtime.

Use at runtime

The interpreter can be used at runtime, and the resulting value bought back into the caller:

# let x : int list * int list =
  Tinyocaml.to_ocaml_value
    (Runeval.eval_string "List.split [(1, 2); (3, 4)]");;
val x : int list * int list = ([1; 3], [2; 4])

Support for this is very rudimentary at the moment.

PPX_eval

Writing

let compiler_command = [%compiletimestr "Sys.argv.(0)"])

in a normal compiled OCaml program with PPX_eval generates

let compiler_command = "ocamlopt"

Status

The ocamli interpreter is a proof-of-concept. Do not expect it to run your larger programs!

It supports just enough of the language to load (and run the module initialisation of) most of the OCaml Standard Library. This is quite a large number of constructs, though, including functors, first class modules and so on.

The ocamli interpreter can run almost all the programs in the OCaml from the Very Beginning textbook. The examples are included in the download.

The ocamli interpreter currently makes no guarantee of computational complexity, even when the steps of evaluation are not shown. The extent to which such a guarantee can be given is an open research question.

Future

In short, make it more than a proof-of-concept:

  • Extend it to the full language
  • Better pretty-printing
  • Make it fast enough for general use
  • Easy invocation as a debugger regardless of build system or source structure
  • Better tools for searching and eliding
  • Allow interpretation of just one module -- other modules run at full speed
  • An interactive interface

Building

Make sure to download from tag "OCaml17". Should work on all platforms with OCaml 4.05. To build, run the build script. You will need ocamlfind and ppx_tools installed, both of which are available on OPAM.

More Repositories

1

cpdf-source

PDF Command Line Tools Source
OCaml
222
star
2

camlpdf

OCaml library for reading, writing and modifying PDF files
OCaml
200
star
3

ppx_blob

OCaml ppx to include binary data from a file as a string
OCaml
77
star
4

more-ocaml-exercises

Examples and Exercises for the book "More OCaml"
OCaml
60
star
5

mlbook

OCaml from the Very Beginning
HTML
50
star
6

ocaml-from-very-beginning-exercises

Examples and exercises for the OCaml Book "OCaml from the Very Beginning"
OCaml
34
star
7

python-from-the-very-beginning-examples-and-exercises

Examples and exercises for the book "Python from the Very Beginning"
Python
28
star
8

cpdfsqueeze

Lossless PDF squeezer
OCaml
22
star
9

ocaml-main-program-in-c

Example build system for making mixed C/Ocaml binaries where the main program is in C
Shell
16
star
10

cpdflib-source

C
9
star
11

haskell-from-the-very-beginning-exercises

Exercises for the book "Haskell from the Very Beginning"
Haskell
8
star
12

graphicspdf

Version of OCaml's Graphics module which outputs PDF.
OCaml
7
star
13

exn-source

Exception backtrace for OCaml with source code printing
Prolog
5
star
14

ocaml-nursery

Examples for OCaml libraries, prior to upstreaming
OCaml
4
star
15

what-ocaml-compiles

What OCaml compiles when it compiles
3
star
16

coherence-renderer

coherence-renderer
OCaml
3
star
17

roman

Roman numerals for OCaml
OCaml
3
star
18

cpdflin

qpdf-based linearizer for use with cpdf
Shell
3
star
19

more-ocaml

Support code for the book "More OCaml"
OCaml
2
star
20

camlgpc

OCaml interface to Alan Murta's General Polygon Clipper
C
2
star
21

tppx_showtype

Example typed PPX
OCaml
2
star
22

rfork

Automatic decorators for OCaml types
OCaml
1
star
23

tppx_test

Testing the documentation for tppx in Tast_mapper
OCaml
1
star
24

5443

Mantis Bug 5443 Experiments
OCaml
1
star