Skip to content

Commit

Permalink
(docs) improve Utop tutorial (#2883)
Browse files Browse the repository at this point in the history
* (docs) improve Utop tutorial

* mention what a PPX is

* Update data/tutorials/getting-started/2_01_toplevel.md

Co-authored-by: Cuihtlauac Alvarado <[email protected]>

---------

Co-authored-by: Cuihtlauac Alvarado <[email protected]>
  • Loading branch information
sabine and cuihtlauac authored Dec 21, 2024
1 parent dde5874 commit 5ac9eea
Showing 1 changed file with 34 additions and 2 deletions.
36 changes: 34 additions & 2 deletions data/tutorials/getting-started/2_01_toplevel.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: |
category: "Tooling"
---

An OCaml toplevel is a chat between the user and OCaml. The user writes OCaml code, and UTop evaluates it. This is why it is also called a Read-Eval-Print-Loop (REPL). Several OCaml toplevels exist, like `ocaml` and `utop`. We recommend using UTop, which is part of the [OCaml Platform](/docs/platform) toolchain.
An OCaml toplevel is a chat between the user and OCaml. The user writes OCaml code, and UTop evaluates it. This is why it is also called a Read-Eval-Print-Loop (REPL). Several OCaml toplevels exist, like `ocaml` and `utop`. We recommend using UTop, which is part of the [OCaml Platform](/docs/platform) toolchain.

To run UTop, we use the `utop` command, which looks like this:
```shell
Expand All @@ -23,7 +23,7 @@ utop #

Press `Ctrl-D` (end of file) or enter `#quit;;` to exit `utop`.

UTop displays a hash prompt `#`, similar to the `$` in the CLI. This `#` means it is waiting for input, so you can start writing your code after the prompt. To evaluate it, add a double semicolon `;;` to signal the end of the expression and press `Enter`.
UTop displays a hash prompt `#`, similar to the `$` in the CLI. This `#` means it is waiting for input, so you can start writing your code after the prompt. To evaluate it, add a double semicolon `;;` to signal the end of the expression and press `Enter`.

Lines ending with double semicolons trigger the parsing, type checking, and evaluation of everything typed between the prompt and the double semicolon. The interpretation of that double semicolon isn't made by the OCaml interpreter; it is made by UTop. Once the evaluation of a double semicolon terminated entry is over, the REPL waits for another piece of input.

Expand All @@ -44,3 +44,35 @@ Commands beginning with a hash character `#`, such as `#quit` or `#help`, are no
You're now ready to hack with UTop! If you hit any issue with the toplevel, don't hesitate to [ask on Discuss](https://discuss.ocaml.org/).

> Note: The double semicolon `;;` is also a valid token in the OCaml syntax outside the toplevel. In OCaml source code, it is a [no-op](https://en.wikipedia.org/wiki/NOP_(code)), i.e., it does not trigger any behaviour, so it is ignored by the compiler. If your intention is to compile or interpret files as scripts, double semicolons can and should be avoided when writing in OCaml. Leaving them does not raise errors, but they are useless. The compiler tolerates them to allow copy-paste from UTop to a file without having to remove them.
## Using Packages in UTop

### Loading Libraries In UTop

If you want to use a library from a package installed in the current opam switch in UTop, enter

```ocaml
# #require "<LIBRARY_NAME>";;
```

into the toplevel to make all definitions from the library available. For, example, try

```ocaml
# Str.quote {|"hello"|};;
Error: Unbound module Str
# #require "str";;
# Str.quote {|"hello"|};;
- : string = "\"hello\""
```
**Tip**: UTop knows about the available libraries and completion works. Outside `utop` you can use `ocamlfind list` to display the complete list of libraries. Note that opam package may bundle several libraries and libraries may bundle several modules.

### Using a Pre-Processor Extension (PPX) in UTop

Pre-Processor Extensions enable code generation through annotations of your code
(for an example, see [section "Using the Preprocessor to Generate Code" in "Your First OCaml Program"](/docs/your-first-program#using-the-preprocessor-to-generate-code).

To activate a PPX in UTop, all you need to do is to load the corresponding library.

Assuming that the [`ppx_deriving`](https://ocaml.org/p/ppx_deriving/latest) package is installed in your opam switch, you run `#require "ppx_deriving.show"`.

0 comments on commit 5ac9eea

Please sign in to comment.