package minicaml

README.md

minicaml

minicaml is a small, dyhamically typed purely functional programming language. It is heavily inspired by the OCaml, Haskell and Scheme languages. minicaml was initially written as a midterm project for the Programming 2 course at the University of Pisa, taught by Professors Gianluigi Ferrari and Francesca Levi. Therefore, it is based on the teachers' minicaml, a simple evaluation example to show how interpreters work. Parsing and lexing are done with menhir and ocamllex (learn more). The REPL can show each reduction step that is done in evaluating an expression. An LLVM compiler is planned for the next future.

Documentation

The internal documentation is available here. Please note that the language at the current status is in an experimental phase and therefore the specification is not complete, and will be constantly updated. The documentation may not be up to date with the latest features in the master branch.

Installation

To install, you need to have opam (OCaml's package manager) and a recent OCaml distribution installed on your system. You can install minicaml by running

opam install minicaml

rlwrap is suggested for a readline-like (bash-like) keyboard interface.

Manual installation

# clone the repository
git clone https://github.com/0x0f0f0f/minicaml
# cd into it
cd minicaml
# install dependencies
opam install dune menhir ANSITerminal cmdliner alcotest bisect_ppx ocamline
# compile
make
# test
make test
# run
make run
# rlwrap is suggested
rlwrap make run
# you can install minicaml with
make install
# run again
rlwrap minicaml

Usage

The executable name is minicaml. If a file is specified as the first command line argument, then it will be ran as a program. If you are running a program you may want to use the flag -p to print the results of the expressions that are evaluated. Otherwise, if a program is not specified a REPL session will be opened.

Keep in mind that minicaml is purely functional and values are immutable by default!

Command Line Options

• --help[=FMT] (default=auto): Show this help in format FMT. The value FMT must be one of auto', pager', groff' or plain'. With auto', the format is pagerorplain' whenever the TERM env var is `dumb' or undefined.

• --internals: To print or not the language's internal stack traces

• -m MAXSTACKDEPTH, --maxstackdepth=MAXSTACKDEPTH (absent=10): The maximum level of nested expressions to print in a stack trace.

• -p, --printexprs: If set, print the result of expressions when evaluating a program from file

• -v VERBOSITY, --verbose=VERBOSITY (absent=0): If 1, Print AST to stderr after expressions are entered in the REPL. If 2, also print reduction steps

• --version Show version information.

Examples

Check the examples/ directory for some example programs.

Features

Arithmetics with full scheme-like numeric tower

Integer division returns an integer if the modulo is 0, and returns a float otherwise. Floating point numbers decimal part can be omitted if it is 0. Floating point numbers can use the power syntax using e.

1 + 2 + 3 * (4 - 1) ;;
1 + 4.0 - 1. / 2.315 ;;
1.2e-3 ;;
true && false || (1 < 2) && (1 = 1) ;;

Declarations

Local declaration statements are purely functional and straightforward:

let x = 4 and y = 1 in x + y

Global declaration statements create new, purely functional environments in both programs and the REPL. Omitting in is syntax-sugar, subsequent blocks will be evaluated in the resulting new environment.

let a = 2 ;;
x + 3 ;;

Toplevel Directives

Toplevel directives can be used in both files and the REPL. Like in OCaml, they start with a # symbol. Note that toplevel directives are not expressions and they can only be used in a file (or REPL) top level, and cannot be used inside expressions.

#include loads a file at a position relative to the current directory (if in the REPL) or the directory containing the current running file (in file mode). The declarations in the included file will be included in the current toplevel environment:

#include "examples/fibonacci.mini"

#import loads a file like #import but the declarations in the included file will be included in an object (dictionary):

#import "examples/fibonacci.mini"
(* Declarations will be available in module *) Fibonacci

#verbosity n sets verbosity level to n. There are "unit" directives: #dumpenv () and #dumppurityenv () dump the current environments. #pure (), #impure () and #uncertain () set the globally allowed purity level.

Complex numbers

The :+ and :- operators are used to create complex values, the floating point number on the left is the real part and the one on the right is the imaginary part.

12. :+ 1.12;;
0. :- 1.12;;

Strings and Lists

Here is how to concatenate strings

"hello " ++ "world"

To convert any value to a string you can use the show primitive.

:: means is the classic cons operator, while ++ is used for list and string concatenation

1 :: [2] ++ [3]

To access nth value of a list, the @ (at) operator is used. Lists are indexed from 0.

[1; 2; 3; 4] @ 0 (* => 1 *)
[1; 2; 3; 4] @ 2 (* => 3 *)

Functions and recursion

For parsing simplicity, only the OCaml anonymous function style of declaring functions is supported. The keyword fun is interchangeable with lambda.

(fun x -> x + 1) 1;;
let fib = fun n -> if n < 2 then n else (fib (n - 1)) + fib (n - 2)

Functions are abstracted into a single parameter chain of functions, and they can be partially applied:

(fun x y z -> x + y + z) = (fun x -> fun y -> fun z -> x + y + z) ;;
(* result: true - bool - This is true!! *)

let f = (fun x y z -> x + y + z) in f 1 2 3 ;;
(* result: 6 - int - Function application *)

let f = (fun x y z -> x + y + z) in f 1 2 ;;
(* result: (fun z -> ... ) - fun - Partial application *)

Printing

The impure primitives print and print_endline automatically call show on a value. The difference between them is that print_endline automatically adds a newline at the end of the line.

Haskell-like dollar syntax

Too many parens?

f (g (h (i 1 2 3)))

Is equivalent to

f $ g $ h $ i 1 2 3

Toggle between pure and impure environments in code for I/O

You can choose to enable or disable impure primitives explicitely, inside an expression by wrapping it into the pure and impure statements. They must be followed by an expression. An expression contained in an impure statement is a computation that calls primitives that have side effects, such as direct memory access or I/O access.

It is good practice to reduce the use of the pure/impure keywords as much as possible, and to avoid using it inside of function bodies. This means keeping your code as purely functional as you can.

let bad_function = fun x ->
    impure (let mystring =
        "I am a bad impure function! Also: " ++ x in
        print_endline mystring );;

let good_function = fun x ->
    print_endline ("I am a good function! Also: " ++ x) ;;

bad_function "hello!" ;;
(* The above statement is causing side effects and will error *)

good_function "hello! I should error" ;;
(* The above will error, because it is trying to execute
an impure computation in a pure environment
Here's a good way of calling it *)
impure $ good_function "hello!" ;;

(* You can specify that you DO NOT want to compute impure
expressions by using the pure statement *)
pure $ good_function "henlo world! I should error" ;;
(* The above will error because
it contains an impure computation*)
pure $ bad_function "ciao mondo! I should error" ;;
(* The above will error because a pure contest
does not allow nesting an impure contest inside *)

A good way of structuring your code is keeping pure/impure statements as external from expressions as you can (towards the top level). By default, the interpreter is in a uncertain state, it means that it will allow the execution of impure statements

Function pipes (reverse composition) and composition

You can redirect the result of a function to the first argument of another function using the >=> operator.

let sum_and_add_one = (fun x y -> x + y) >=> (fun z -> z + 1) ;;
sum_and_add_one 2 3
(* Will output 6, because 2 + 3 is piped into z + 1*)

Yields the same result as normal composition:

let my_sum = (fun x y -> x + y) ;;
let add_one = (fun z -> z + 1) ;;
(add_one <=< my_sum) 2 3 = add_one (my_sum 2 3) ;;
(* The operator <=< means compose *)
(add_one <=< my_sum) = (my_sum >=> add_one) ;;
(* This is also true! *)

Dictionaries

Dictionary (object) values are similar to Javascript objects. The difference is that the keys of an existing dictionary are treated as symbols, and they can be manipulated using strings.

let n = {hola = 1; mondo = 2} ;;
let m = insert "newkey" 123 n ;;
m = {newkey = 123; hola = 1; mondo = 2} (* => true *)
haskey "newkey" m (* => true *)
map (fun x -> x + 1) m
(* => {newkey = 124; hola = 2; mondo = 3} *)