# Chapter 4  The Why3 API

This chapter is a tutorial for the users who want to link their own OCaml code with the Why3 library. We progressively introduce the way one can use the library to build terms, formulas, theories, proof tasks, call external provers on tasks, and apply transformations on tasks. The complete documentation for API calls is given at this URL.

We assume the reader has a fair knowledge of the OCaml language. Notice that the Why3 library must be installed, see Section 5.3. The OCaml code given below is available in the source distribution in directory `examples/use_api/` together with a few other examples.

## 4.1  Building Propositional Formulas

The first step is to know how to build propositional formulas. The module Term gives a few functions for building these. Here is a piece of OCaml code for building the formula truefalse.

 (* opening the Why3 library *) open Why3 (* a ground propositional goal: true or false *) let fmla_true : Term.term = Term.t_true let fmla_false : Term.term = Term.t_false let fmla1 : Term.term = Term.t_or fmla_true fmla_false

The library uses the common type term both for terms (i.e. expressions that produce a value of some particular type) and formulas (i.e. boolean-valued expressions).

Such a formula can be printed using the module Pretty providing pretty-printers.

 (* printing it *) open Format let () = printf "@[formula 1 is:@ %a@]@." Pretty.print_term fmla1

Assuming the lines above are written in a file f.ml, it can be compiled using

```ocamlc str.cma unix.cma nums.cma dynlink.cma \
-I +ocamlgraph -I +why3 graph.cma why.cma f.ml -o f
```

Running the generated executable f results in the following output.

```formula 1 is: true \/ false
```

Let us now build a formula with propositional variables: ABA. Propositional variables must be declared first before using them in formulas. This is done as follows.

 let prop_var_A : Term.lsymbol = Term.create_psymbol (Ident.id_fresh "A") [] let prop_var_B : Term.lsymbol = Term.create_psymbol (Ident.id_fresh "B") []

The type lsymbol is the type of function and predicate symbols (which we call logic symbols for brevity). Then the atoms A and B must be built by the general function for applying a predicate symbol to a list of terms. Here we just need the empty list of arguments.

 let atom_A : Term.term = Term.ps_app prop_var_A [] let atom_B : Term.term = Term.ps_app prop_var_B [] let fmla2 : Term.term = Term.t_implies (Term.t_and atom_A atom_B) atom_A let () = printf "@[formula 2 is:@ %a@]@." Pretty.print_term fmla2

As expected, the output is as follows.

```formula 2 is: A /\ B -> A
```

Notice that the concrete syntax of Why3 forbids function and predicate names to start with a capital letter (except for the algebraic type constructors which must start with one). This constraint is not enforced when building those directly using library calls.

Let us see how we can call a prover to prove a formula. As said in previous chapters, a prover must be given a task, so we need to build tasks from our formulas. Task can be build incrementally from an empty task by adding declaration to it, using the functions add_*_decl of module Task. For the formula truefalse above, this is done as follows.

To make the formula a goal, we must give a name to it, here “goal1”. A goal name has type prsymbol, for identifiers denoting propositions in a theory or a task. Notice again that the concrete syntax of Why3 requires these symbols to be capitalized, but it is not mandatory when using the library. The second argument of add_prop_decl is the kind of the proposition: Paxiom, Plemma or Pgoal. Notice that lemmas are not allowed in tasks and can only be used in theories.

Once a task is built, it can be printed.

The task for our second formula is a bit more complex to build, because the variables A and B must be added as abstract (i.e. not defined) propositional symbols in the task.

Execution of our OCaml program now outputs:

```task 1 is:
goal Goal1 : true \/ false
end

predicate A

predicate B

goal Goal2 : A /\ B -> A
end
```

## 4.3  Calling External Provers

To call an external prover, we need to access the Why3 configuration file why3.conf, as it was built using the why3config command line tool or the Detect Provers menu of the graphical IDE. The following API calls allow to access the content of this configuration file.

 (* reads the config file *) let config : Whyconf.config = Whyconf.read_config None (* the [main] section of the config file *) let main : Whyconf.main = Whyconf.get_main config (* all the provers detected, from the config file *) let provers : Whyconf.config_prover Whyconf.Mprover.t = Whyconf.get_provers config

The type ’a Whyconf.Mprover.t is a map indexed by provers. A prover is a record with a name, a version, and an alternative description (to differentiate between various configurations of a given prover). Its definition is in the module Whyconf:

 type prover = { prover_name : string; (* "Alt-Ergo" *) prover_version : string; (* "2.95" *) prover_altern : string; (* "special" *) }

The map provers provides the set of existing provers. In the following, we directly attempt to access the prover Alt-Ergo, which is known to be identified with id "alt-ergo".

 (* the [prover alt-ergo] section of the config file *) let alt_ergo : Whyconf.config_prover = try Whyconf.prover_by_id config "alt-ergo" with Whyconf.ProverNotFound _ -> eprintf "Prover alt-ergo not installed or not configured@."; exit 0

We could also get a specific version with :

 let alt_ergo : Whyconf.config_prover = try let prover = {Whyconf.prover_name = "Alt-Ergo"; prover_version = "0.92.3"; prover_altern = ""} in Whyconf.Mprover.find prover provers with Not_found -> eprintf "Prover alt-ergo not installed or not configured@."; exit 0

The next step is to obtain the driver associated to this prover. A driver typically depends on the standard theories so these should be loaded first.

 (* builds the environment from the [loadpath] *) let env : Env.env = Env.create_env (Whyconf.loadpath main) (* loading the Alt-Ergo driver *) let alt_ergo_driver : Driver.driver = try Driver.load_driver env alt_ergo.Whyconf.driver with e -> eprintf "Failed to load driver for alt-ergo: %a@." Exn_printer.exn_printer e; exit 1

We are now ready to call the prover on the tasks. This is done by a function call that launches the external executable and waits for its termination. Here is a simple way to proceed:

 (* calls Alt-Ergo *) let result1 : Call_provers.prover_result = Call_provers.wait_on_call (Driver.prove_task ~command:alt_ergo.Whyconf.command alt_ergo_driver task1 ()) () (* prints Alt-Ergo answer *) let () = printf "@[On task 1, alt-ergo answers %a@]@." Call_provers.print_prover_result result1

This way to call a prover is in general too naive, since it may never return if the prover runs without time limit. The function prove_task has two optional parameters: timelimit is the maximum allowed running time in seconds, and memlimit is the maximum allowed memory in megabytes. The type prover_result is a record with three fields:

• pr_output: the output of the prover, i.e. both standard output and the standard error of the process (a redirection in why3.conf is required);
• pr_time : the time taken by the prover, in seconds.

• Valid: the task is valid according to the prover.
• Invalid: the task is invalid.
• Timeout: the prover exceeds the time or memory limit.
• Unknown msg: the prover can’t determine if the task is valid; the string parameter msg indicates some extra information.
• Failure msg: the prover reports a failure, i.e. it was unable to read correctly its input task.
• HighFailure: an error occurred while trying to call the prover, or the prover answer was not understood (i.e. none of the given regular expressions in the driver file matches the output of the prover).

Here is thus another way of calling the Alt-Ergo prover, on our second task.

The output of our program is now as follows.

```On task 1, alt-ergo answers Valid (0.01s)
```

## 4.4  Building Terms

An important feature of the functions for building terms and formulas is that they statically guarantee that only well-typed terms can be constructed.

Here is the way we build the formula 2+2=4. The main difficulty is to access the internal identifier for addition: it must be retrieved from the standard theory Int of the file int.why (see Chap 7.4).

 let two : Term.term = Term.t_const (Number.ConstInt (Number.int_const_dec "2")) let four : Term.term = Term.t_const (Number.ConstInt (Number.int_const_dec "4")) let int_theory : Theory.theory = Env.read_theory env ["int"] "Int" let plus_symbol : Term.lsymbol = Theory.ns_find_ls int_theory.Theory.th_export ["infix +"] let two_plus_two : Term.term = Term.t_app_infer plus_symbol [two;two] let fmla3 : Term.term = Term.t_equ two_plus_two four

An important point to notice as that when building the application of + to the arguments, it is checked that the types are correct. Indeed the constructor t_app_infer infers the type of the resulting term. One could also provide the expected type as follows.

 let two_plus_two : Term.term = Term.fs_app plus_symbol [two;two] Ty.ty_int

When building a task with this formula, we need to declare that we use theory Int:

## 4.5  Building Quantified Formulas

To illustrate how to build quantified formulas, let us consider the formula ∀ x:int. x*x ≥ 0. The first step is to obtain the symbols from Int.

 let zero : Term.term = Term.t_const (Number.ConstInt (Number.int_const_dec "0")) let mult_symbol : Term.lsymbol = Theory.ns_find_ls int_theory.Theory.th_export ["infix *"] let ge_symbol : Term.lsymbol = Theory.ns_find_ls int_theory.Theory.th_export ["infix >="]

The next step is to introduce the variable x with the type int.

 let var_x : Term.vsymbol = Term.create_vsymbol (Ident.id_fresh "x") Ty.ty_int

The formula x*x ≥ 0 is obtained as in the previous example.

 let x : Term.term = Term.t_var var_x let x_times_x : Term.term = Term.t_app_infer mult_symbol [x;x] let fmla4_aux : Term.term = Term.ps_app ge_symbol [x_times_x;zero]

To quantify on x, we use the appropriate smart constructor as follows.

 let fmla4 : Term.term = Term.t_forall_close [var_x] [] fmla4_aux

## 4.6  Building Theories

We illustrate now how one can build theories. Building a theory must be done by a sequence of calls:

• creating a theory “under construction”, of type `Theory.theory_uc`;
• adding declarations, one at a time;
• closing the theory under construction, obtaining something of type `Theory.theory`.

Creation of a theory named `My_theory` is done by

 let my_theory : Theory.theory_uc = Theory.create_theory (Ident.id_fresh "My_theory")

First let us add formula 1 above as a goal:

 let decl_goal1 : Decl.decl = Decl.create_prop_decl Decl.Pgoal goal_id1 fmla1 let my_theory : Theory.theory_uc = Theory.add_decl my_theory decl_goal1

Note that we reused the goal identifier `goal_id1` that we already defined to create task 1 above.

Adding formula 2 needs to add the declarations of predicate variables A and B first:

 let my_theory : Theory.theory_uc = Theory.add_param_decl my_theory prop_var_A let my_theory : Theory.theory_uc = Theory.add_param_decl my_theory prop_var_B let decl_goal2 : Decl.decl = Decl.create_prop_decl Decl.Pgoal goal_id2 fmla2 let my_theory : Theory.theory_uc = Theory.add_decl my_theory decl_goal2

Adding formula 3 is a bit more complex since it uses integers, thus it requires to “use” the theory `int.Int`. Using a theory is indeed not a primitive operation in the API: it must be done by a combination of an “export” and the creation of a namespace. We provide a helper function for that:

 (* [use th1 th2] insert the equivalent of a "use import th2" in theory th1 under construction *) let use th1 th2 = let name = th2.Theory.th_name in Theory.close_namespace (Theory.use_export (Theory.open_namespace th1 name.Ident.id_string) th2) true

Addition of formula 3 is then

 let my_theory : Theory.theory_uc = use my_theory int_theory let decl_goal3 : Decl.decl = Decl.create_prop_decl Decl.Pgoal goal_id3 fmla3 let my_theory : Theory.theory_uc = Theory.add_decl my_theory decl_goal3

Addition of goal 4 is nothing more complex:

 let decl_goal4 : Decl.decl = Decl.create_prop_decl Decl.Pgoal goal_id4 fmla4 let my_theory : Theory.theory_uc = Theory.add_decl my_theory decl_goal4

Finally, we close our theory under construction as follows.

 let my_theory : Theory.theory = Theory.close_theory my_theory

We can inspect what we did by printing that theory:

 let () = printf "@[theory is:@\n%a@]@." Pretty.print_theory my_theory

which outputs

```theory is:
theory My_theory
(* use BuiltIn *)

goal goal1 : true \/ false

predicate A

predicate B

goal goal2 : A /\ B -> A

(* use int.Int *)

goal goal3 : (2 + 2) = 4

goal goal4 : forall x:int. (x * x) >= 0
end
```

From a theory, one can compute at once all the proof tasks it contains as follows:

Note that the tasks are returned in reverse order, so we reverse the list above.

We can check our generated tasks by printing them:

 let () = printf "Tasks are:@."; let _ = List.fold_left (fun i t -> printf "Task %d: %a@." i Pretty.print_task t; i+1) 1 my_tasks in ()

One can run provers on those tasks exactly as we did above.

## 4.7  Applying Transformations

[TO BE COMPLETED]

## 4.8  Writing New Functions on Terms

[TO BE COMPLETED]

## 4.9  Proof Sessions

See the example `examples/use_api/create_session.ml` of the distribution for an illustration on how to manipulate proof sessions from an OCaml program.

## 4.10  ML Programs

There are two ways for building WhyML programs from OCaml. The first is to build untyped syntax trees for such WhyML programs, and then call the Why3 typing procedure to build typed declarations. The second way is to directly build typed programs using smart constructors that check well-typedness at each step.

The first approach, building untyped trees and then typing them, is examplified in file `examples/use_api/mlw_tree.ml` of the distribution. The second approach is examplified in file `examples/use_api/mlw.ml`. The first approach is significantly simpler to do since the internal typing mechanism using regions remains implicit, whereas when one uses the second approach one should care about such typing. On the other hand, the second approach is more “efficient” in the sense that no intermediate form needs to be built in memory.