+
@@ -67,11 +70,42 @@ title: Cheat Sheet
|Variants|
type action =
| Increment of int
| Decrement of int
|
|Variant *(pattern)* matching|
let a: action = Increment 5
match a with
| Increment n -> n + 1
| Decrement n -> n - 1
|
|Records|
type person = {
age: int ;
name: string ;
}
let john : person = {
age = 18;
name = "John Doe";
}
let name: string = john.name
|
-|Maps|
type prices = (nat, tez) map
let prices : prices = Map.literal [
(10n, 60mutez);
(50n, 30mutez);
(100n, 10mutez)
]
let price: tez option = Map.find 50n prices
let prices: prices = Map.update 200n 5mutez prices
|
+|Maps|
type prices = (nat, tez) map
let prices : prices = Map.literal [
(10n, 60mutez);
(50n, 30mutez);
(100n, 10mutez)
]
let price: tez option = Map.find_opt 50n prices
let prices: prices = Map.update 200n (Some 5mutez) prices
|
|Contracts & Accounts|
let destination_address : address = "tz1..."
let contract : unit contract =
Operation.get_contract destination_address
|
-|Transactions|
let payment : operation =
Operation.transaction (unit, receiver, amount)
|
+|Transactions|
let payment : operation =
Operation.transaction unit amount receiver
|
|Exception/Failure|`failwith("Your descriptive error message for the user goes here.")`|
+
+
+|Primitive |Example|
+|--- |---|
+|Strings | `"Tezos"`|
+|Characters | `"t"`|
+|Integers | `42`, `7`|
+|Natural numbers | `42n`, `7n`|
+|Unit| `unit`|
+|Boolean|
let has_drivers_license: bool = false;
let adult: bool = true;
|
+|Boolean Logic|
(not true) = false = (false && true) = (false || false)
|
+|Mutez (micro tez)| `42mutez`, `7mutez` |
+|Address | `("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx": address)`, `("KT1JepfBfMSqkQyf9B1ndvURghGsSB8YCLMD": address)`|
+|Addition |`3 + 4`, `3n + 4n`|
+|Multiplication & Division| `3 * 4`, `3n * 4n`, `10 / 5`, `10n / 5n`|
+|Modulo| `10 mod 3`|
+|Tuples|
type name = (string, string);
let winner: name = ("John", "Doe");
let first_name: string = winner[0];
let last_name: string = winner[1];
|
+|Types|`type age = int;`, `type name = string;` |
+|Includes|```#include "library.mligo"```|
+|Functions |
let add = (a: int, b: int) : int => a + b;
|
+| If Statement |
let new_id: int = if (age < 16) {
failwith("Too young to drive.");
} else { prev_id + 1; }
|
+|Options|
type middle_name = option(string);
let middle_name : middle_name = Some("Foo");
let middle_name : middle_name = None;
|
+|Variable Binding | ```let age: int = 5;```|
+|Type Annotations| ```("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx" : address)```|
+|Variants|
type action =
| Increment(int)
| Decrement(int);
|
+|Variant *(pattern)* matching|
let a: action = Increment(5);
switch(a) {
| Increment(n) => n + 1
| Decrement(n) => n - 1;
}
|
+|Records|
type person = {
age: int,
name: string
}
let john : person = {
age: 18,
name: "John Doe"
};
let name: string = john.name;
|
+|Maps|
type prices = map(nat, tez);
let prices : prices = Map.literal([
(10n, 60mutez),
(50n, 30mutez),
(100n, 10mutez)
]);
let price: option(tez) = Map.find_opt(50n, prices);
let prices: prices = Map.update(200n, Some (5mutez), prices);
|
+|Contracts & Accounts|
let destination_address : address = "tz1...";
let contract : contract(unit) =
Operation.get_contract(destination_address);
|
+|Transactions|
let payment : operation =
Operation.transaction (unit, amount, receiver);
|
+|Exception/Failure|`failwith("Your descriptive error message for the user goes here.");`|
diff --git a/gitlab-pages/docs/contributors/getting-started.md b/gitlab-pages/docs/contributors/getting-started.md
index 7b186dfad..5a98402d3 100644
--- a/gitlab-pages/docs/contributors/getting-started.md
+++ b/gitlab-pages/docs/contributors/getting-started.md
@@ -23,9 +23,9 @@ The first issues will most likely be:
>Tests are **really** important, we don’t have lots of them, and mostly regression ones. This can’t be stressed enough. Some features are missing not because we can’t add them, but because we don’t know as no tests tell us they are missing.
## How
-Issues will be added to Gitlab tagged with `On-boarding and Front-End` / `Middle-End` / `Back-End` / `Everything`.
+Issues will be added to GitLab tagged with `On-boarding and Front-End` / `Middle-End` / `Back-End` / `Everything`.
-If you try to tackle an issue and you have **any** problem, please tell us by creating a new Gitlab issue, contacting us on Riot, on Discord, or even by mail!
+If you try to tackle an issue and you have **any** problem, please tell us by creating a new GitLab issue, contacting us on Riot, on Discord, or even by mail!
Problems might include:
* Installing the repository or the tools needed to work on it
diff --git a/gitlab-pages/docs/contributors/ligo_test_guide.md b/gitlab-pages/docs/contributors/ligo_test_guide.md
index 4726c7fe3..eea05d77d 100644
--- a/gitlab-pages/docs/contributors/ligo_test_guide.md
+++ b/gitlab-pages/docs/contributors/ligo_test_guide.md
@@ -111,4 +111,4 @@ What if we want to write a test of our own? If the test is in the integration te
1. Write a test contract which uses the new syntax or feature in [src/test/contracts](https://gitlab.com/ligolang/ligo/tree/dev/src/test/contracts).
2. Write an integration test in [src/test/integration_tests.ml](https://gitlab.com/ligolang/ligo/blob/dev/src/test/integration_tests.ml) in the vein of existing tests, make sure you add it to the test runner that is currently located at the bottom of the file.
3. Write the feature, assuming it doesn't already exist. Build the resulting version of LIGO without errors.
-4. Run the test suite, see if your test(s) pass. If they do, you're probably done. If not it's time to go debugging.
+4. Run the test suite, see if your test(s) pass. If they do, you're probably done. If not, it's time to go debugging.
diff --git a/gitlab-pages/docs/contributors/origin.md b/gitlab-pages/docs/contributors/origin.md
index 9c8df5900..6b20863a3 100644
--- a/gitlab-pages/docs/contributors/origin.md
+++ b/gitlab-pages/docs/contributors/origin.md
@@ -3,8 +3,8 @@ id: origin
title: Origin
---
-LIGO is a programming language that aims to provide developers with an uncomplicated and safe way to implement smart-contracts. Since it is being implemented for the Tezos blockchain LIGO compiles to Michelson—the native smart-contract language of Tezos.
+LIGO is a programming language that aims to provide developers with an uncomplicated and safe way to implement smart contracts. Since it is being implemented for the Tezos blockchain LIGO compiles to Michelson—the native smart contract language of Tezos.
-> Smart-contracts are programs that run within a blockchain network.
+> Smart contracts are programs that run within a blockchain network.
LIGO was meant to be a language for developing Marigold on top of a hacky framework called Meta-Michelson. However, due to the attention received by the Tezos community, LIGO is now a standalone language being developed to support Tezos directly.
\ No newline at end of file
diff --git a/gitlab-pages/docs/contributors/philosophy.md b/gitlab-pages/docs/contributors/philosophy.md
index 0af6e606b..351a470e2 100644
--- a/gitlab-pages/docs/contributors/philosophy.md
+++ b/gitlab-pages/docs/contributors/philosophy.md
@@ -6,7 +6,7 @@ title: Philosophy
To understand LIGO’s design choices it’s important to understand its philosophy. We have two main concerns in mind while building LIGO.
## Safety
-Once a smart-contract is deployed, it will likely be impossible to change it. You must get it right on the first try, and LIGO should help as much as possible. There are multiple ways to make LIGO a safer language for smart-contracts.
+Once a smart contract is deployed, it will likely be impossible to change it. You must get it right on the first try, and LIGO should help as much as possible. There are multiple ways to make LIGO a safer language for smart contracts.
### Automated Testing
Automated Testing is the process through which a program runs another program, and checks that this other program behaves correctly.
@@ -18,7 +18,7 @@ Static analysis is the process of having a program analyze another one.
For instance, type systems are a kind of static analysis through which it is possible to find lots of bugs. LIGO already has a simple type system, and we plan to make it much stronger.
### Conciseness
-Writing less code gives you less room to introduce errors. That's why LIGO encourages writing lean rather than chunky smart-contracts.
+Writing less code gives you less room to introduce errors. That's why LIGO encourages writing lean rather than chunky smart contracts.
---
diff --git a/gitlab-pages/docs/intro/installation.md b/gitlab-pages/docs/intro/installation.md
index cd45491ab..307e470c9 100644
--- a/gitlab-pages/docs/intro/installation.md
+++ b/gitlab-pages/docs/intro/installation.md
@@ -15,12 +15,12 @@ executable (see below). This manages the Docker bits for you.
* Use the Docker image available at [Docker Hub](https://hub.docker.com/r/ligolang/ligo).
This lets you run multiple versions and keep your installation(s) self contained, but requires more familiarity with Docker.
-Sources for the image can be found on [Gitlab](https://gitlab.com/ligolang/ligo/blob/master/docker/Dockerfile).
+Sources for the image can be found on [GitLab](https://gitlab.com/ligolang/ligo/blob/master/docker/Dockerfile).
If this is your first time using Docker, you probably want to set up a global LIGO executable as shown below.
### Setting up a globally available `ligo` executable
-> You can install additional ligo versions by replacing `next` with the required version number
+> You can install additional ligo versions by replacing `next` with the desired version number
Download the latest binaries here: https://gitlab.com/ligolang/ligo/pipelines/85536879/builds or get the latest pre-release:
diff --git a/gitlab-pages/docs/intro/src/what-and-why/ligo-counter.ligo b/gitlab-pages/docs/intro/src/what-and-why/ligo-counter.ligo
index 989afba07..4fd886fb7 100644
--- a/gitlab-pages/docs/intro/src/what-and-why/ligo-counter.ligo
+++ b/gitlab-pages/docs/intro/src/what-and-why/ligo-counter.ligo
@@ -1,12 +1,25 @@
-type action is
-| Increment of int
-| Decrement of int
-| Reset of unit
+type storage is int
-function main (const p : action ; const s : int) : (list(operation) * int) is
- block { skip } with ((nil : list(operation)),
- case p of
- | Increment(n) -> s + n
- | Decrement(n) -> s - n
- | Reset(n) -> 0
- end)
\ No newline at end of file
+type parameter is
+ Increment of int
+| Decrement of int
+| Reset
+
+type return is list (operation) * storage
+
+(* Two entrypoints *)
+
+function add (const store : storage; const delta : int) : storage is store + delta
+
+function sub (const store : storage; const delta : int) : storage is store - delta
+
+(* Main access point that dispatches to the entrypoints according to
+ the smart contract parameter. *)
+
+function main (const action : parameter; const store : storage) : return is
+ ((nil : list (operation)), // No operations
+ case action of
+ Increment (n) -> add (store, n)
+ | Decrement (n) -> sub (store, n)
+ | Reset -> 0
+ end)
diff --git a/gitlab-pages/docs/intro/src/what-and-why/ligo-counter.mligo b/gitlab-pages/docs/intro/src/what-and-why/ligo-counter.mligo
new file mode 100644
index 000000000..3cfa8551f
--- /dev/null
+++ b/gitlab-pages/docs/intro/src/what-and-why/ligo-counter.mligo
@@ -0,0 +1,23 @@
+type storage = int
+
+type parameter =
+ Increment of int
+| Decrement of int
+| Reset
+
+type return = operation list * storage
+
+(* Two entrypoints *)
+
+let add (store, delta : storage * int) : storage = store + delta
+let sub (store, delta : storage * int) : storage = store - delta
+
+(* Main access point that dispatches to the entrypoints according to
+ the smart contract parameter. *)
+
+let main (action, store : parameter * storage) : return =
+ ([] : operation list), // No operations
+ (match action with
+ Increment (n) -> add (store, n)
+ | Decrement (n) -> sub (store, n)
+ | Reset -> 0)
diff --git a/gitlab-pages/docs/intro/src/what-and-why/ligo-counter.religo b/gitlab-pages/docs/intro/src/what-and-why/ligo-counter.religo
new file mode 100644
index 000000000..74292563c
--- /dev/null
+++ b/gitlab-pages/docs/intro/src/what-and-why/ligo-counter.religo
@@ -0,0 +1,26 @@
+type storage = int;
+
+type parameter =
+ Increment (int)
+| Decrement (int)
+| Reset;
+
+type return = (list (operation), storage);
+
+(* Two entrypoints *)
+
+let add = ((store, delta) : (storage, int)) : storage => store + delta;
+
+let sub = ((store, delta) : (storage, int)) : storage => store - delta;
+
+(* Main access point that dispatches to the entrypoints according to
+ the smart contract parameter. *)
+
+let main = ((action, store) : (parameter, storage)) : return => {
+ (([] : list (operation)), // No operations
+ (switch (action) {
+ | Increment (n) => add ((store, n))
+ | Decrement (n) => sub ((store, n))
+ | Reset => 0
+ }))
+};
diff --git a/gitlab-pages/docs/intro/what-and-why.md b/gitlab-pages/docs/intro/what-and-why.md
index fdd1d2887..f195b97a7 100644
--- a/gitlab-pages/docs/intro/what-and-why.md
+++ b/gitlab-pages/docs/intro/what-and-why.md
@@ -1,14 +1,73 @@
---
id: what-and-why
-title: What & Why
+title: Michelson and LIGO
---
-Before we get into what LIGO is and why LIGO needs to exist, let's take a look at what options the Tezos blockchain offers us out of the box. If you want to implement smart contracts natively on Tezos, you have to learn [Michelson](https://tezos.gitlab.io/whitedoc/michelson.html).
+Before we get into what LIGO is and why LIGO needs to exist, let us
+take a look at what options the Tezos blockchain offers us out of the
+box. If you want to implement smart contracts natively on Tezos, you
+have to learn
+[Michelson](https://tezos.gitlab.io/whitedoc/michelson.html).
-> đź’ˇ The (Michelson) language is stack-based, with high level data types and primitives and strict static type checking.
+**The rationale and design of Michelson**
+The language native to the Tezos blockchain for writing smart
+contracts is *Michelson*, a Domain-Specific Language (DSL) inspired by
+Lisp and Forth. This unusual lineage aims at satisfying unusual
+constraints, but entails some tensions in the design.
-Here's an example of Michelson code:
+First, to measure stepwise gas consumption, *Michelson is interpreted*.
+
+On the one hand, to assess gas usage per instruction, instructions
+should be simple, which points to low-level features (a RISC-like
+language). On the other hand, it was originally thought that users
+will want to write in Michelson instead of lowering a language to
+Michelson, because the gas cost would otherwise be harder to
+predict. This means that *high-level features* were deemed necessary
+(like a restricted variant of Lisp lambdas, a way to encode algebraic
+data types, as well as built-in sets, maps and lists).
+
+To avoid ambiguous and otherwise misleading contracts, the layout of
+Michelson contracts has been constrained (e.g., indentation, no
+UTF-8), and a *canonical form* was designed and enforced when storing
+contracts on the chain.
+
+To reduce the size of the code, Michelson was designed as *a
+stack-based language*, whence the lineage from Forth and other
+concatenative languages like PostScript, Joy, Cat, Factor etc. (Java
+bytecode would count too.)
+
+Programs in those languages are *compact* because they assume an
+implicit stack in which some input values are popped, and output
+values are pushed, according to the current instruction being
+executed.
+
+*Each Michelson instruction modifies a prefix of the stack*, that is,
+a segment starting at the top.
+
+Whilst the types of Michelson instructions can be polymorphic, their
+instantiations must be monomorphic, hence *Michelson instructions are
+not first-class values* and cannot be partially interpreted.
+
+This enables a simple *static type checking*, as opposed to a complex
+type inference. It can be performed efficiently: *contract type
+checking consumes gas*. Basically, type checking aims at validating
+the composition of instructions, therefore is key to safely composing
+contracts (concatenation, activations). Once a contract passes type
+checking, it cannot fail due to inconsistent assumptions on the
+storage and other values (there are no null values, no casts), but it
+can still fail for other reasons: division by zero, token exhaustion,
+gas exhaustion, or an explicit `FAILWITH` instruction. This property
+is called *type safety*. Also, such a contract cannot remain stuck:
+this is the *progress property*.
+
+The existence of a formal type system for Michelson, of a formal
+specification of its dynamic semantics (evaluation), of a Michelson
+interpreter in Coq, of proofs in Coq of properties of some typical
+contracts, all those achievements are instances of *formal methods in
+Tezos*.
+
+Here is an example of a Michelson contract.
**`counter.tz`**
```text
@@ -21,118 +80,167 @@ Here's an example of Michelson code:
NIL operation ; PAIR } }
```
-The contract above maintains an `int` in its storage. It has two entrypoints *(functions)* `add` and `sub` to modify it, and the default *entrypoint* of type unit will reset it to 0.
+The contract above maintains an `int` as its storage. It has two
+[entrypoints](https://tezos.gitlab.io/whitedoc/michelson.html#entrypoints),
+`add` and `sub`, to modify it, and the `default` entrypoint of type
+`unit` will reset it to `0`.
-The contract itself contains three main parts:
+The contract itself contains three sections:
+- `parameter` - The argument provided by a transaction invoking the contract.
+- `storage` - The type definition for the contract's data storage.
+- `code` - Actual Michelson code that has the provided parameter and
+ the current storage value in its initial stack. It outputs in the
+ resulting stack a pair made of a list of operations and a new
+ storage value.
-- `parameter` - Argument provided by a transaction invoking the contract
-- `storage` - Type definition for the contract's data storage.
-- `code` - Actual Michelson code that has the provided parameter & the current storage value in its initial stack. It outputs a pair of operations and a new storage value as its resulting stack.
+Michelson code consists of *instructions* like `IF_LEFT`, `PUSH ...`,
+`UNPAIR` etc. that are composed sequentially in what is called a
+*sequence*. The implicit stack contains at all times the state of the
+evaluation of the program, whilst the storage represents the
+persistent state. If the contract execution is successful, the new
+storage state will be committed to the chain and become visible to all
+the nodes. Instructions are used to transform a prefix of the stack,
+that is, the topmost part of it, for example, by duplicating its top
+element, dropping it, subtracting the first two etc.
-Michelson code consists of *instructions* like `IF_LEFT`, `PUSH ...`, `UNPAIR` that are bundled togeter in what is called a *sequence*. Stack represents an intermediate state of the program, while **storage represents a persistent state**. Instructions are used to modify the run-time stack in order to yield a desired stack value when the program terminates.
+> đź’ˇ A Michelson program running on the Tezos blockchain is meant to
+> output a pair of values including a `list of operations` to include
+> in a transaction, and a new `storage` value to persist on the chain.
-> đź’ˇ A Michelson program running on the Tezos blockchain is meant to output a pair of values including a `list of operations` to emit and a new `storage` value to persist
+## Stack versus variables
-## Differences between a stack and traditional variable management
-
-Stack management might be a little bit challanging, especially if you're coming from a *C-like language*. Let's implement a similar program in Javascript:
+Perhaps the biggest challenge when programming in Michelson is the
+lack of *variables* to denote the data: the stack layout has to be
+kept in mind when retrieving and storing data. For example, let us
+implement a program in Javascript that is similar to the Michelson
+above:
**`counter.js`**
```javascript
var storage = 0;
-function add(a) {
- storage += a
-}
+function add (a) { storage += a; }
+function sub (a) { storage -= a; }
-function sub(a) {
- storage -= a
-}
+// We are calling this function "reset" instead of "default"
+// because `default` is a Javascript keyword
-// We're calling this function reset instead of default
-// because `default` is a javascript keyword
-function reset() {
- storage = 0;
-}
+function reset () { storage = 0; }
```
-In our javascript program the initial `storage` value is `0` and it can be modified by running the functions `add(a)`, `sub(a)` and `reset()`.
+In our Javascript program the initial `storage` value is `0` and it
+can be modified by calling `add (a)`, `sub (a)` and `reset ()`.
-Unfortunately (???), we **can't run Javascript on the Tezos blockchain** at the moment. But we can choose LIGO, which will abstract the stack management and allow us to create readable, type-safe, and efficient smart contracts.
+We cannot run Javascript on the Tezos blockchain, but we can choose
+LIGO, which will abstract the stack management and allow us to create
+readable, type-safe, and efficient smart contracts.
-> đź’ˇ You can try running the javascript program [here](https://codepen.io/maht0rz/pen/dyyvoPQ?editors=0012)
+## LIGO for Programming Smart Contracts on Tezos
-## C-like smart contracts instead of Michelson
+Perhaps the most striking feature of LIGO is that it comes in
+different concrete syntaxes, and even different programming
+paradigms. In other words, LIGO is not defined by one syntax and one
+paradigm, like imperative versus functional.
-Let's take a look at a similar LIGO program. Don't worry if it's a little confusing at first; we'll explain all the syntax in the upcoming sections of the documentation.
+ - There is **PascaLIGO**, which is inspired by Pascal, hence is an
+ imperative language with lots of keywords, where values can be
+ locally mutated after they have been annotated with their types
+ (declaration).
+
+ - There is **CameLIGO**, which is inspired by the pure subset of
+ [OCaml](https://ocaml.org/), hence is a functional language with
+ few keywords, where values cannot be mutated, but still require
+ type annotations (unlike OCaml, whose compiler performs almost
+ full type inference).
+
+ - There is **ReasonLIGO**, which is inspired by the pure subset of
+ [ReasonML](https://reasonml.github.io/), which is based upon
+ OCaml.
+
+Let us decline the same LIGO contract in the three flavours above. Do
+not worry if it is a little confusing at first; we will explain all
+the syntax in the upcoming sections of the documentation.
-
-```pascaligo
-type action is
-| Increment of int
-| Decrement of int
-| Reset of unit
+
+```pascaligo group=a
+type storage is int
-function main (const p : action ; const s : int) : (list(operation) * int) is
- block { skip } with ((nil : list(operation)),
- case p of
- | Increment(n) -> s + n
- | Decrement(n) -> s - n
- | Reset(n) -> 0
+type parameter is
+ Increment of int
+| Decrement of int
+| Reset
+
+type return is list (operation) * storage
+
+function main (const action : parameter; const store : storage) : return is
+ ((nil : list (operation)),
+ case action of
+ Increment (n) -> store + n
+ | Decrement (n) -> store - n
+ | Reset -> 0
end)
```
-```cameligo
-type action =
-| Increment of int
-| Decrement of int
-| Reset of unit
+```cameligo group=a
+type storage = int
-let main (p, s: action * int) : operation list * int =
- let result =
- match p with
- | Increment n -> s + n
- | Decrement n -> s - n
- | Reset n -> 0
- in
- (([]: operation list), result)
+type parameter =
+ Increment of int
+| Decrement of int
+| Reset
+
+type return = operation list * storage
+
+let main (action, store : parameter * storage) : return =
+ ([] : operation list),
+ (match action with
+ Increment n -> store + n
+ | Decrement n -> store - n
+ | Reset -> 0)
```
-```reasonligo
-type action =
-| Increment(int)
-| Decrement(int)
-| Reset(unit);
+```reasonligo group=a
+type storage = int;
-let main = ((p,s): (action, int)) : (list(operation), int) => {
- let result =
- switch (p) {
- | Increment(n) => s + n
- | Decrement(n) => s - n
- | Reset n => 0
- };
- (([]: list(operation)), result);
+type parameter =
+ Increment (int)
+| Decrement (int)
+| Reset;
+
+type return = (list (operation), storage);
+
+let main = ((action, store): (parameter, storage)) : return => {
+ (([] : list (operation)),
+ (switch (action) {
+ | Increment (n) => store + n
+ | Decrement (n) => store - n
+ | Reset => 0}));
};
```
+
+
-> đź’ˇ You can find the Michelson compilation output of the contract above in **`ligo-counter.tz`**
+This LIGO contract behaves almost exactly* like the Michelson
+contract we saw first, and it accepts the following LIGO expressions:
+`Increment(n)`, `Decrement(n)` and `Reset`. Those serve as
+`entrypoint` identification, same as `%add` `%sub` or `%default` in
+the Michelson contract.
-The LIGO contract behaves exactly* like the Michelson contract we've saw first, and it accepts the following LIGO expressions/values: `Increment(n)`, `Decrement(n)` and `Reset(n)`. Those serve as `entrypoint` identification, same as `%add` `%sub` or `%default` in the Michelson contract.
-
-**not exactly, the Michelson contract also checks if the `AMOUNT` sent is `0`*
+**The Michelson contract also checks if the `AMOUNT` sent is `0`*
---
## Runnable code snippets & exercises
Some of the sections in this documentation will include runnable code snippets and exercises. Sources for those are available at
-the [LIGO Gitlab repository](https://gitlab.com/ligolang/ligo).
+the [LIGO Gitlab repository](https://gitlab.com/ligolang/ligo).
### Snippets
For example **code snippets** for the *Types* subsection of this doc, can be found here:
@@ -141,7 +249,7 @@ For example **code snippets** for the *Types* subsection of this doc, can be fou
### Exercises
Solutions to exercises can be found e.g. here: `gitlab-pages/docs/language-basics/exercises/types/**/solutions/**`
-### Running snippets / excercise solutions
+### Running snippets / exercise solutions
In certain cases it makes sense to be able to run/evaluate the given snippet or a solution, usually there'll be an example command which you can use, such as:
```shell
diff --git a/gitlab-pages/docs/language-basics/boolean-if-else.md b/gitlab-pages/docs/language-basics/boolean-if-else.md
index d57e6fa99..8a872d777 100644
--- a/gitlab-pages/docs/language-basics/boolean-if-else.md
+++ b/gitlab-pages/docs/language-basics/boolean-if-else.md
@@ -1,205 +1,205 @@
---
id: boolean-if-else
-title: Boolean, If, Else
+title: Booleans and Conditionals
---
-## Boolean
+## Booleans
-The type of a Boolean is `bool` and the possible values are `True` and `False`.
-
-Here's how to define a boolean:
+The type of a boolean value is `bool`. Here is how to define a boolean
+value:
-
+
```pascaligo group=a
-const a: bool = True;
-const b: bool = False;
+const a : bool = True // Notice the capital letter
+const b : bool = False // Same.
```
```cameligo group=a
-let a: bool = true
-let b: bool = false
+let a : bool = true
+let b : bool = false
```
-
```reasonligo group=a
-let a: bool = true;
-let b: bool = false;
+let a : bool = true;
+let b : bool = false;
```
+## Comparing Values
-## Comparing two values
+In LIGO, only values of the same type can be compared. Moreover, not
+all values of the same type can be compared, only those with
+*comparable types*, which is a concept lifted from
+Michelson. Comparable types include, for instance, `int`, `nat`,
+`string`, `tez`, `timestamp`, `address`, etc. As an example of
+non-comparable types: maps, sets or lists are not comparable: if you
+wish to compare them, you will have to write your own comparison
+function.
-In LIGO, only values of the same type can be compared. We call these "comparable types." Comparable types include e.g. `int`, `nat`, `string`, `tez`, `timestamp`, `address`, ...
-
-### Comparing strings
+### Comparing Strings
-
+
```pascaligo group=b
-const a: string = "Alice";
-const b: string = "Alice";
-// True
-const c: bool = (a = b);
+const a : string = "Alice"
+const b : string = "Alice"
+const c : bool = (a = b) // True
```
```cameligo group=b
-let a: string = "Alice"
-let b: string = "Alice"
-// true
-let c: bool = (a = b)
+let a : string = "Alice"
+let b : string = "Alice"
+let c : bool = (a = b) // true
```
```reasonligo group=b
-let a: string = "Alice";
-let b: string = "Alice";
-(* true *)
-let c: bool = (a == b);
+let a : string = "Alice";
+let b : string = "Alice";
+let c : bool = (a == b); // true
```
-
### Comparing numbers
-
+
```pascaligo group=c
-const a: int = 5;
-const b: int = 4;
-const c: bool = (a = b);
-const d: bool = (a > b);
-const e: bool = (a < b);
-const f: bool = (a <= b);
-const g: bool = (a >= b);
-const h: bool = (a =/= b);
+const a : int = 5
+const b : int = 4
+const c : bool = (a = b)
+const d : bool = (a > b)
+const e : bool = (a < b)
+const f : bool = (a <= b)
+const g : bool = (a >= b)
+const h : bool = (a =/= b)
```
```cameligo group=c
-let a: int = 5
-let b: int = 4
-let c: bool = (a = b)
-let d: bool = (a > b)
-let e: bool = (a < b)
-let f: bool = (a <= b)
-let g: bool = (a >= b)
-let h: bool = (a <> b)
+let a : int = 5
+let b : int = 4
+let c : bool = (a = b)
+let d : bool = (a > b)
+let e : bool = (a < b)
+let f : bool = (a <= b)
+let g : bool = (a >= b)
+let h : bool = (a <> b)
```
```reasonligo group=c
-let a: int = 5;
-let b: int = 4;
-let c: bool = (a == b);
-let d: bool = (a > b);
-let e: bool = (a < b);
-let f: bool = (a <= b);
-let g: bool = (a >= b);
-let h: bool = (a != b);
+let a : int = 5;
+let b : int = 4;
+let c : bool = (a == b);
+let d : bool = (a > b);
+let e : bool = (a < b);
+let f : bool = (a <= b);
+let g : bool = (a >= b);
+let h : bool = (a != b);
```
-
### Comparing tez
-> đź’ˇ Comparing `tez` values is especially useful when dealing with an `amount` sent in a transaction.
+> đź’ˇ Comparing `tez` values is especially useful when dealing with an
+> amount sent in a transaction.
-
+
```pascaligo group=d
-const a: tez = 5mutez;
-const b: tez = 10mutez;
-const c: bool = (a = b);
+const a : tez = 5mutez
+const b : tez = 10mutez
+const c : bool = (a = b) // False
```
```cameligo group=d
-let a: tez = 5mutez
-let b: tez = 10mutez
-// false
-let c: bool = (a = b)
+let a : tez = 5mutez
+let b : tez = 10mutez
+let c : bool = (a = b) // false
```
```reasonligo group=d
-let a: tez = 5mutez;
-let b: tez = 10mutez;
-(* false *)
-let c: bool = (a == b);
+let a : tez = 5mutez;
+let b : tez = 10mutez;
+let c : bool = (a == b); // false
```
-## Conditionals, if staments, and more
+## Conditionals
-Conditional logic is an important part of every real world program.
-
-### If/else statements
+Conditional logic enables forking the control flow depending on the
+state.
-
+
```pascaligo group=e
-const min_age: nat = 16n;
+type magnitude is Small | Large // See variant types.
-(*
- This function is really obnoxious, but it showcases
- how the if statement and it's syntax can be used.
-
- Normally, you'd use `with (age > min_age)` instead.
-*)
-function is_adult(const age: nat): bool is
- block {
- var is_adult: bool := False;
- if (age > min_age) then begin
- is_adult := True;
- end else begin
- is_adult := False;
- end
- } with is_adult
+function compare (const n : nat) : magnitude is
+ if n < 10n then Small (Unit) else Large (Unit) // Unit is needed for now.
```
-> You can run the function above with
-> ```
-> ligo run-function -s pascaligo src/if-else.ligo is_adult 21n
-> ```
+You can run the `compare` function defined above using the LIGO compiler
+like this:
+```shell
+ligo run-function
+gitlab-pages/docs/language-basics/boolean-if-else/cond.ligo compare 21n'
+# Outputs: Large (Unit)
+```
+
+When the branches of the conditional are not a single expression, as
+above, we need a block:
+
+```pascaligo skip
+if x < y then
+ block {
+ const z : nat = x;
+ x := y; y := z
+ }
+else skip;
+```
+
+As an exception to the rule, the blocks in a conditional branch do not
+need to be introduced by the keywor `block`, so, we could have written
+instead:
+```pascaligo skip
+if x < y then {
+ const z : nat = x;
+ x := y; y := z
+}
+else skip;
+```
```cameligo group=e
-let min_age: nat = 16n
+type magnitude = Small | Large // See variant types.
-(**
-
- This function is really obnoxious, but it showcases
- how the if statement and it's syntax can be used.
-
- Normally, you'd use `with (age > min_age)` instead.
-
-*)
-let is_adult (age: nat) : bool =
- if (age > min_age) then true else false
+let compare (n : nat) : magnitude =
+ if n < 10n then Small else Large
```
+
+You can run the `compare` function defined above using the LIGO compiler
+like this:
+```shell
+ligo run-function
+gitlab-pages/docs/language-basics/boolean-if-else/cond.mligo compare 21n'
+# Outputs: Large
+```
+
```reasonligo group=e
-let min_age: nat = 16n;
+type magnitude = | Small | Large; // See variant types.
-(**
-
- This function is really obnoxious, but it showcases
- how the if statement and it's syntax can be used.
-
- Normally, you'd use `with (age > min_age)` instead.
-
-*)
-
-let is_adult = (age: nat): bool =>
- if (age > min_age) {
- true;
- } else {
- false;
- };
+let compare = (n : nat) : magnitude =>
+ if (n < 10n) { Small; } else { Large; };
```
-> You can run the function above with
-> ```
-> ligo run-function -s reasonligo src/if-else.religo is_adult 21n
-> ```
-
-
\ No newline at end of file
+You can run the `compare` function defined above using the LIGO compiler
+like this:
+```shell
+ligo run-function
+gitlab-pages/docs/language-basics/boolean-if-else/cond.religo compare 21n'
+# Outputs: Large
+```
+
diff --git a/gitlab-pages/docs/language-basics/functions.md b/gitlab-pages/docs/language-basics/functions.md
index 5cf99f761..d0344a754 100644
--- a/gitlab-pages/docs/language-basics/functions.md
+++ b/gitlab-pages/docs/language-basics/functions.md
@@ -3,131 +3,270 @@ id: functions
title: Functions
---
-Writing code is fun as long as it doesn't get out of hand. To make sure our code doesn't turn into spaghetti we can group some logic into functions.
+LIGO functions are the basic building block of contracts. For example,
+entrypoints are functions.
-## Instruction blocks
-
-With `block`(s) you can wrap *instructions* and *expressions* into an isolated scope.
-Each `block` needs to include at least one `instruction`, or a *placeholder* instruction called `skip`.
+## Declaring Functions
-
+
+
+There are two ways in PascaLIGO to define functions: with or without a
+*block*.
+
+### Blocks
+
+In PascaLIGO, *blocks* enable the sequential composition of
+instructions into an isolated scope. Each block needs to include at
+least one instruction.
```pascaligo skip
-// shorthand syntax
-block { skip }
-// verbose syntax
-begin
- skip
-end
+block { a := a + 1 }
```
-
+If we need a placeholder, we use the instruction `skip` which leaves
+the state unchanged. The rationale for `skip` instead of a truly
+empty block is that it prevents you from writing an empty block by
+mistake.
-## Defining a function
+```pascaligo skip
+block { skip }
+```
-
-
+Blocks are more versatile than simply containing instructions: they
+can also include *declarations* of values, like so:
-Functions in PascaLIGO are defined using the `function` keyword followed by their `name`, `parameters` and `return` type definitions.
+```pascaligo skip
+block { const a : int = 1 }
+```
-Here's how you define a basic function that accepts two `ints` and returns a single `int`:
+Functions in PascaLIGO are defined using the `function` keyword
+followed by their `name`, `parameters` and `return` type definitions.
+Here is how you define a basic function that computes the sum of two
+integers:
```pascaligo group=a
-function add(const a: int; const b: int): int is
- begin
- const result: int = a + b;
- end with result;
+function add (const a : int; const b : int) : int is
+ block {
+ const sum : int = a + b
+ } with sum
```
The function body consists of two parts:
-- `block {
}` - logic of the function
-- `with ` - the return value of the function
+- `block { }` is the logic of the function;
+- `with ` is the value returned by the function.
-#### Blockless functions
+### Blockless functions
-Functions that can contain all of their logic into a single instruction/expression, can be defined without the surrounding `block`.
-Instead, you can inline the necessary logic directly, like this:
+Functions that can contain all of their logic into a single
+*expression* can be defined without the need of a block:
+
+```pascaligo
+function identity (const n : int) : int is block { skip } with n // Bad! Empty block not needed!
+
+function identity (const n : int) : int is n // Blockless
+```
+
+The value of the expression is implicitly returned by the
+function. Another example is as follows:
```pascaligo group=b
-function add(const a: int; const b: int): int is a + b
+function add (const a: int; const b : int) : int is a + b
+```
+
+You can call the function `add` defined above using the LIGO compiler
+like this:
+```shell
+ligo run-function gitlab-pages/docs/language-basics/src/functions/blockless.ligo add '(1,2)'
+# Outputs: 3
```
-Functions in CameLIGO are defined using the `let` keyword, like value bindings.
-The difference is that after the value name a list of function parameters is provided,
-along with a return type.
-
-CameLIGO is a little different from other syntaxes when it comes to function
-parameters. In OCaml, functions can only take one parameter. To get functions
-with multiple arguments like we're used to in traditional programming languages,
-a technique called [currying](https://en.wikipedia.org/wiki/Currying) is used.
-Currying essentially translates a function with multiple arguments into a series
-of single argument functions, each returning a new function accepting the next
-argument until every parameter is filled. This is useful because it means that
-CameLIGO can support [partial application](https://en.wikipedia.org/wiki/Partial_application).
-
-Currying is however *not* the preferred way to pass function arguments in CameLIGO.
-While this approach is faithful to the original OCaml, it's costlier in Michelson
-than naive function execution accepting multiple arguments. Instead for most
-functions with more than one parameter we should place the arguments in a
-[tuple](language-basics/sets-lists-tuples.md) and pass the tuple in as a single
-parameter.
-
-Here's how you define a basic function that accepts two `ints` and returns an `int` as well:
-
-```cameligo group=b
-
-let add (a,b: int * int) : int = a + b
-
-let add_curry (a: int) (b: int) : int = a + b
+Functions in CameLIGO are defined using the `let` keyword, like other
+values. The difference is that a succession of parameters is provided
+after the value name, followed by the return type. This follows OCaml
+syntax. For example:
+```cameligo group=c
+let add (a : int) (b : int) : int = a + b
```
-The function body is a series of expressions, which are evaluated to give the return
-value.
+You can call the function `add` defined above using the LIGO compiler
+like this:
+```shell
+ligo run-function gitlab-pages/docs/language-basics/src/functions/blockless.mligo add '(1,2)'
+# Outputs: 3
+```
+CameLIGO is a little different from other syntaxes when it comes to
+function parameters. In OCaml, functions can only take one
+parameter. To get functions with multiple arguments like we are used
+to in imperative programming languages, a technique called
+[currying](https://en.wikipedia.org/wiki/Currying) is used. Currying
+essentially translates a function with multiple arguments into a
+series of single argument functions, each returning a new function
+accepting the next argument until every parameter is filled. This is
+useful because it means that CameLIGO supports
+[partial application](https://en.wikipedia.org/wiki/Partial_application).
+
+Currying is however *not* the preferred way to pass function arguments
+in CameLIGO. While this approach is faithful to the original OCaml,
+it is costlier in Michelson than naive function execution accepting
+multiple arguments. Instead, for most functions with more than one
+parameter, we should gather the arguments in a
+[tuple](language-basics/sets-lists-tuples.md) and pass the tuple in as
+a single parameter.
+
+Here is how you define a basic function that accepts two integers and
+returns an integer as well:
+
+```cameligo group=b
+let add (a, b : int * int) : int = a + b // Uncurried
+let add_curry (a : int) (b : int) : int = add (a, b) // Curried
+let increment (b : int) : int = add_curry 1 // Partial application
+```
+
+You can run the `increment` function defined above using the LIGO
+compiler like this:
+```shell
+ligo run-function gitlab-pages/docs/language-basics/src/functions/curry.mligo increment 5
+# Outputs: 6
+```
+
+The function body is a single expression, whose value is returned.
-Functions in ReasonLIGO are defined using the `let` keyword, like value bindings.
-The difference is that after the value name a list of function parameters is provided,
-along with a return type.
-
-Here's how you define a basic function that accepts two `ints` and returns an `int` as well:
+Functions in ReasonLIGO are defined using the `let` keyword, like
+other values. The difference is that a tuple of parameters is provided
+after the value name, with its type, then followed by the return type.
+Here is how you define a basic function that sums two integers:
```reasonligo group=b
-let add = ((a,b): (int, int)) : int => a + b;
+let add = ((a, b): (int, int)) : int => a + b;
```
-The function body is a series of expressions, which are evaluated to give the return
-value.
+You can call the function `add` defined above using the LIGO compiler
+like this:
+```shell
+ligo run-function gitlab-pages/docs/language-basics/src/functions/blockless.religo add '(1,2)'
+# Outputs: 3
+```
+
+As in CameLIGO and with blockless functions in PascaLIGO, the function
+body is a single expression, whose value is returned.
+
+If the body contains more than a single expression, you use block
+between braces:
+```reasonligo group=b
+let myFun = ((x, y) : (int, int)) : int => {
+ let doubleX = x + x;
+ let doubleY = y + y;
+ doubleX + doubleY
+};
+```
-## Anonymous functions
+## Anonymous functions (a.k.a. lambdas)
-Functions without a name, also known as anonymous functions are useful in cases when you want to pass the function as an argument or assign it to a key in a record/map.
+It is possible to define functions without assigning them a name. They
+are useful when you want to pass them as arguments, or assign them to
+a key in a record or a map.
+
+Here is how to define an anonymous function:
-Here's how to define an anonymous function assigned to a variable `increment`, with it's appropriate function type signature.
-
+
```pascaligo group=c
-const increment : (int -> int) = (function (const i : int) : int is i + 1);
-// a = 2
-const a: int = increment(1);
+function increment (const b : int) : int is
+ (function (const a : int) : int is a + 1) (b)
+const a : int = increment (1); // a = 2
+```
+
+You can check the value of `a` defined above using the LIGO compiler
+like this:
+```shell
+ligo evaluate-value gitlab-pages/docs/language-basics/src/functions/anon.ligo a
+# Outputs: 2
```
```cameligo group=c
-let increment : (int -> int) = fun (i: int) -> i + 1
+let increment (b : int) : int = (fun (a : int) -> a + 1) b
+let a : int = increment 1 // a = 2
+```
+
+You can check the value of `a` defined above using the LIGO compiler
+like this:
+```shell
+ligo evaluate-value gitlab-pages/docs/language-basics/src/functions/anon.mligo a
+# Outputs: 2
```
```reasonligo group=c
-let increment: (int => int) = (i: int) => i + 1;
+let increment = (b : int) : int => ((a : int) : int => a + 1) (b);
+let a : int = increment (1); // a == 2
+```
+
+You can check the value of `a` defined above using the LIGO compiler
+like this:
+```shell
+ligo evaluate-value gitlab-pages/docs/language-basics/src/functions/anon.religo a
+# Outputs: 2
+```
+
+
+
+If the example above seems contrived, here is a more common design
+pattern for lambdas: to be used as parameters to functions. Consider
+the use case of having a list of integers and mapping the increment
+function to all its elements.
+
+
+
+```pascaligo group=c
+function incr_map (const l : list (int)) : list (int) is
+ list_map (function (const i : int) : int is i + 1, l)
+```
+You can call the function `incr_map` defined above using the LIGO compiler
+like so:
+```shell
+ligo run-function
+gitlab-pages/docs/language-basics/src/functions/incr_map.ligo incr_map
+"list [1;2;3]"
+# Outputs: [ 2 ; 3 ; 4 ]
+```
+
+
+```cameligo group=c
+let incr_map (l : int list) : int list =
+ List.map (fun (i : int) -> i + 1) l
+```
+You can call the function `incr_map` defined above using the LIGO compiler
+like so:
+```shell
+ligo run-function
+gitlab-pages/docs/language-basics/src/functions/incr_map.mligo incr_map
+"list [1;2;3]"
+# Outputs: [ 2 ; 3 ; 4 ]
+```
+
+
+```reasonligo group=c
+let incr_map = (l : list (int)) : list (int) =>
+ List.map ((i : int) => i + 1, l);
+```
+You can call the function `incr_map` defined above using the LIGO compiler
+like so:
+```shell
+ligo run-function
+gitlab-pages/docs/language-basics/src/functions/incr_map.religo incr_map
+"list [1;2;3]"
+# Outputs: [ 2 ; 3 ; 4 ]
```
diff --git a/gitlab-pages/docs/language-basics/loops.md b/gitlab-pages/docs/language-basics/loops.md
index 9fd26d024..bb31e124f 100644
--- a/gitlab-pages/docs/language-basics/loops.md
+++ b/gitlab-pages/docs/language-basics/loops.md
@@ -3,108 +3,246 @@ id: loops
title: Loops
---
-
-
-## While Loop
+## General Iteration
-
+
-The PascaLIGO while loop should look familiar to users of imperative languages.
-While loops are of the form `while `, and evaluate
-their associated block until the condition evaluates to false.
+General iteration in PascaLIGO takes the shape of general loops, which
+should be familiar to programmers of imperative languages as "while
+loops". Those loops are of the form `while `. Their
+associated block is repeatedly evaluated until the condition becomes
+true, or never evaluated if the condition is false at the start. The
+loop never terminates if the condition never becomes true. Because we
+are writing smart contracts on Tezos, when the condition of a "while"
+loops fails to become true, the execution will run out of gas and stop
+with a failure anyway.
-> ⚠️ The current PascaLIGO while loop has semantics that have diverged from other LIGO syntaxes. The goal of LIGO is that the various syntaxes express the same semantics, so this will be corrected in future versions. For details on how loops will likely work after refactoring, see the CameLIGO tab of this example.
+Here is how to compute the greatest common divisors of two natural
+numbers by means of Euclid's algorithm:
-```pascaligo
-function while_sum (var n : nat) : nat is block {
- var i : nat := 0n ;
- var r : nat := 0n ;
- while i < n block {
- i := i + 1n;
- r := r + i;
- }
-} with r
+```pascaligo group=a
+function gcd (var x : nat; var y : nat) : nat is
+ block {
+ if x < y then {
+ const z : nat = x;
+ x := y; y := z
+ }
+ else skip;
+ var r : nat := 0n;
+ while y =/= 0n block {
+ r := x mod y;
+ x := y;
+ y := r
+ }
+ } with x
+```
+
+You can call the function `gcd` defined above using the LIGO compiler
+like so:
+```shell
+ligo run-function
+gitlab-pages/docs/language-basics/src/loops/gcd.ligo gcd '(2n*2n*3n*11n, 2n*2n*2n*3n*3n*5n*7n)'
+# Outputs: +12
```
-`Loop.fold_while` is a fold operation that takes an initial value of a certain type
-and then iterates on it until a condition is reached. The auxillary function
-that does the fold returns either boolean true or boolean false to indicate
-whether the fold should continue or not. The initial value must match the input
-parameter of the auxillary function, and the auxillary should return type `(bool * input)`.
+CameLIGO is a functional language where user-defined values are
+constant, therefore it makes no sense in CameLIGO to feature loops,
+which we understand as syntactic constructs where the state of a
+stopping condition is mutated, as with "while" loops in PascaLIGO.
-`continue` and `stop` are provided as syntactic sugar for the return values.
+Instead, CameLIGO implements a *folded operation* by means of a
+predefined function named `Loop.fold_while`. It takes an initial value
+of a certain type, called an *accumulator*, and repeatedly calls a
+given function, called *folded function*, that takes that
+accumulator and returns the next value of the accumulator, until a
+condition is met and the fold stops with the final value of the
+accumulator. The iterated function needs to have a special type: if
+the type of the accumulator is `t`, then it must have the type `bool *
+t` (not simply `t`). It is the boolean value that denotes whether the
+stopping condition has been reached.
-```cameligo
-let aux (i: int) : bool * int =
- if i < 100 then continue (i + 1) else stop i
+Here is how to compute the greatest common divisors of two natural
+numbers by means of Euclid's algorithm:
-let counter_simple (n: int) : int =
- Loop.fold_while aux n
+```cameligo group=a
+let iter (x,y : nat * nat) : bool * (nat * nat) =
+ if y = 0n then false, (x,y) else true, (y, x mod y)
+
+let gcd (x,y : nat * nat) : nat =
+ let x,y = if x < y then y,x else x,y in
+ let x,y = Loop.fold_while iter (x,y)
+ in x
+```
+
+To ease the writing and reading of the iterated functions (here,
+`iter`), two predefined functions are provided: `continue` and `stop`:
+
+```cameligo group=a
+let iter (x,y : nat * nat) : bool * (nat * nat) =
+ if y = 0n then stop (x,y) else continue (y, x mod y)
+
+let gcd (x,y : nat * nat) : nat =
+ let x,y = if x < y then y,x else x,y in
+ let x,y = Loop.fold_while iter (x,y)
+ in x
+```
+You can call the function `gcd` defined above using the LIGO compiler
+like so:
+```shell
+ligo run-function
+gitlab-pages/docs/language-basics/src/loops/gcd.mligo gcd (2n*2n*3n*11n, 2n*2n*2n*3n*3n*5n*7n)'
+# Outputs: +12
```
-`Loop.fold_while` is a fold operation that takes an initial value of a certain type
-and then iterates on it until a condition is reached. The auxillary function
-that does the fold returns either boolean true or boolean false to indicate
-whether the fold should continue or not. The initial value must match the input
-parameter of the auxillary function, and the auxillary should return type `(bool, input)`.
+ReasonLIGO is a functional language where user-defined values are
+constant, therefore it makes no sense in ReasonLIGO to feature loops,
+which we understand as syntactic constructs where the state of a
+stopping condition is mutated, as with "while" loops in PascaLIGO.
-`continue` and `stop` are provided as syntactic sugar for the return values.
+Instead, ReasonLIGO features a *fold operation* as a predefined
+function named `Loop.fold_while`. It takes an initial value of a
+certain type, called an *accumulator*, and repeatedly calls a given
+function, called *iterated function*, that takes that accumulator and
+returns the next value of the accumulator, until a condition is met
+and the fold stops with the final value of the accumulator. The
+iterated function needs to have a special type: if the type of the
+accumulator is `t`, then it must have the type `bool * t` (not simply
+`t`). It is the boolean value that denotes whether the stopping
+condition has been reached.
-```reasonligo
-let aux = (i: int): (bool, int) =>
- if (i < 100) {
- continue(i + 1);
- } else {
- stop(i);
- };
+Here is how to compute the greatest common divisors of two natural
+numbers by means of Euclid's algorithm:
-let counter_simple = (n: int): int => Loop.fold_while(aux, n);
+```reasonligo group=a
+let iter = ((x,y) : (nat, nat)) : (bool, (nat, nat)) =>
+ if (y == 0n) { (false, (x,y)); } else { (true, (y, x mod y)); };
+
+let gcd = ((x,y) : (nat, nat)) : nat => {
+ let (x,y) = if (x < y) { (y,x); } else { (x,y); };
+ let (x,y) = Loop.fold_while (iter, (x,y));
+ x
+};
```
+To ease the writing and reading of the iterated functions (here,
+`iter`), two predefined functions are provided: `continue` and `stop`:
+
+```reasonligo group=b
+let iter = ((x,y) : (nat, nat)) : (bool, (nat, nat)) =>
+ if (y == 0n) { stop ((x,y)); } else { continue ((y, x mod y)); };
+
+let gcd = ((x,y) : (nat, nat)) : nat => {
+ let (x,y) = if (x < y) { (y,x); } else { (x,y); };
+ let (x,y) = Loop.fold_while (iter, (x,y));
+ x
+};
+```
-## For Loop
+## Bounded Loops
-
-
+In addition to general loops, PascaLIGO features a specialised kind of
+*loop to iterate over bounded intervals*. These loops are familiarly
+known as "for loops" and they have the form `for
+to `, as found in imperative languages.
-To iterate over a range of integers you use a loop of the form `for to `.
+Consider how to sum the natural numbers up to `n`:
-```pascaligo
-function for_sum (var n : nat) : int is block {
- var acc : int := 0 ;
- for i := 1 to int(n)
- begin
- acc := acc + i;
- end
+```pascaligo group=c
+function sum (var n : nat) : int is block {
+ var acc : int := 0;
+ for i := 1 to int (n) block {
+ acc := acc + i
+ }
} with acc
```
-
+(Please do not use that function: there exists a closed form formula.)
-
-
-
-PascaLIGO for loops can also iterate through the contents of a collection. This is
-done with a loop of the form `for in `.
-
-```pascaligo
-function for_collection_list (var nee : unit) : (int * string) is block {
- var acc : int := 0;
- var st : string := "to";
- var mylist : list(int) := list 1; 1; 1 end;
- for x in list mylist
- begin
- acc := acc + x;
- st := st ^ "to";
- end
-} with (acc, st)
+You can call the function `sum` defined above using the LIGO compiler
+like so:
+```shell
+ligo run-function
+gitlab-pages/docs/language-basics/src/loops/sum.ligo sum 7n
+# Outputs: 28
```
-
+PascaLIGO "for" loops can also iterate through the contents of a
+collection, that is, a list, a set or a map. This is done with a loop
+of the form `for in
+`, where `` is any of the following keywords:
+`list`, `set` or `map`.
+
+Here is an example where the integers in a list are summed up.
+
+```pascaligo group=d
+function sum_list (var l : list (int)) : int is block {
+ var total : int := 0;
+ for i in list l block {
+ total := total + i
+ }
+} with total
+```
+
+You can call the function `sum_list` defined above using the LIGO compiler
+like so:
+```shell
+ligo run-function
+gitlab-pages/docs/language-basics/src/loops/collection.ligo sum_list
+'list [1;2;3]'
+# Outputs: 6
+```
+
+Here is an example where the integers in a set are summed up.
+
+```pascaligo group=d
+function sum_set (var s : set (int)) : int is block {
+ var total : int := 0;
+ for i in set s block {
+ total := total + i
+ }
+} with total
+```
+
+You can call the function `sum_set` defined above using the LIGO compiler
+like so:
+```shell
+ligo run-function
+gitlab-pages/docs/language-basics/src/loops/collection.ligo sum_set
+'set [1;2;3]'
+# Outputs: 6
+```
+
+Loops over maps are actually loops over the bindings of the map, that
+is, a pair key-value noted `key -> value` (or any other
+variables). Given a map from strings to integers, here is how to sum
+all the integers and concatenate all the strings.
+
+Here is an example where the keys are concatenated and the values are
+summed up.
+
+```pascaligo group=d
+function sum_map (var m : map (string, int)) : string * int is block {
+ var string_total : string := "";
+ var int_total : int := 0;
+ for key -> value in map m block {
+ string_total := string_total ^ key;
+ int_total := int_total + value
+ }
+} with (string_total, int_total)
+```
+
+You can call the function `sum_map` defined above using the LIGO compiler
+like so:
+```shell
+ligo run-function
+gitlab-pages/docs/language-basics/src/loops/collection.ligo sum_map
+'map ["1"->1; "2"->2; "3"->3]'
+# Outputs: ( "123", 6 )
+```
diff --git a/gitlab-pages/docs/language-basics/maps-records.md b/gitlab-pages/docs/language-basics/maps-records.md
index 5f51de96c..d691d588e 100644
--- a/gitlab-pages/docs/language-basics/maps-records.md
+++ b/gitlab-pages/docs/language-basics/maps-records.md
@@ -1,510 +1,899 @@
---
id: maps-records
-title: Maps, Records
+title: Records and Maps
---
-So far we've seen pretty basic data types. LIGO also offers more complex built-in constructs, such as Maps and Records.
+So far we have seen pretty basic data types. LIGO also offers more
+complex built-in constructs, such as *records* and *maps*.
-## Maps
+## Records
-Maps are natively available in Michelson, and LIGO builds on top of them. A requirement for a Map is that its keys be of the same type, and that type must be comparable.
+Records are one way data of different types can be packed into a
+single type. A record is made of a set of *fields*, which are made of
+a *field name* and a *field type*. Given a value of a record type, the
+value bound to a field can be accessed by giving its field name to a
+special operator (`.`).
-Here's how a custom map type is defined:
+Let us first consider and example of record type declaration.
-
-```pascaligo
-type move is (int * int);
-type moveset is map(address, move);
-```
-
-```cameligo
-type move = int * int
-type moveset = (address, move) map
-```
-
-
-```reasonligo
-type move = (int, int);
-type moveset = map(address, move);
-```
-
-
-
-And here's how a map value is populated:
-
-
-
-
-```pascaligo
-const moves: moveset = map
- ("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx": address) -> (1, 2);
- ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address) -> (0, 3);
-end
-```
-> Notice the `->` between the key and its value and `;` to separate individual map entries.
->
-> `("": address)` means that we type-cast a string into an address.
-
-
-
-```cameligo
-let moves: moveset = Map.literal
- [ (("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx": address), (1, 2)) ;
- (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address), (0, 3)) ;
+
+```pascaligo group=a
+type user is
+ record [
+ id : nat;
+ is_admin : bool;
+ name : string
]
```
-> Map.literal constructs the map from a list of key-value pair tuples, `(, )`.
-> Note also the `;` to separate individual map entries.
->
-> `("": address)` means that we type-cast a string into an address.
-
-
-
-```reasonligo
-let moves : moveset =
- Map.literal([
- ("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx": address, (1, 2)),
- ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address, (0, 3)),
- ]);
-```
-> Map.literal constructs the map from a list of key-value pair tuples, `(, )`.
->
-> `("": address)` means that we type-cast a string into an address.
-
-
-
-### Accessing map values by key
-
-If we want to access a move from our moveset above, we can use the `[]` operator/accessor to read the associated `move` value. However, the value we'll get will be wrapped as an optional; in our case `option(move)`. Here's an example:
-
-
-
-```pascaligo
-const my_balance : option(move) = moves[("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address)];
-```
-
-```cameligo
-let my_balance : move option = Map.find_opt ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address) moves
+```cameligo group=a
+type user = {
+ id : nat;
+ is_admin : bool;
+ name : string
+}
```
-
-```reasonligo
-let my_balance : option(move) =
- Map.find_opt("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address, moves);
-```
-
-
-#### Obtaining a map value forcefully
-
-Accessing a value in a map yields an option, however you can also get the value directly:
-
-
-
-```pascaligo
-const my_balance : move = get_force(("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address), moves);
-```
-
-
-
-```cameligo
-let my_balance : move = Map.find ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address) moves
-```
-
-
-
-```reasonligo
-let my_balance : move =
- Map.find("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address, moves);
-```
-
-
-
-### Updating the contents of a map
-
-
-
-
-
-The values of a PascaLIGO map can be updated using the ordinary assignment syntax:
-
-```pascaligo
-
-function set_ (var m: moveset) : moveset is
- block {
- m[("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address)] := (4,9);
- } with m
-```
-
-
-
-We can update a map in CameLIGO using the `Map.update` built-in:
-
-```cameligo
-
-let updated_map: moveset = Map.update ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address) (Some (4,9)) moves
-```
-
-
-
-We can update a map in ReasonLIGO using the `Map.update` built-in:
-
-```reasonligo
-
-let updated_map: moveset = Map.update(("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address), Some((4,9)), moves);
-```
-
-
-
-
-### Iteration over the contents of a map
-
-There are three kinds of iteration on LIGO maps, `iter`, `map` and `fold`. `iter`
-is an iteration over the map with no return value, its only use is to
-generate side effects. This can be useful if for example you would like to check
-that each value inside of a map is within a certain range, with an error thrown
-otherwise.
-
-
-
-```pascaligo
-function iter_op (const m : moveset) : unit is
- block {
- function aggregate (const i : address ; const j : move) : unit is block
- { if (j.1 > 1) then skip else failwith("fail") } with unit ;
- } with map_iter(aggregate, m) ;
-```
-
-
-```cameligo
-let iter_op (m : moveset) : unit =
- let assert_eq = fun (i,j: address * move) -> assert (j.0 > 1)
- in Map.iter assert_eq m
-```
-
-
-```reasonligo
-let iter_op = (m: moveset): unit => {
- let assert_eq = ((i,j): (address, move)) => assert(j[0] > 1);
- Map.iter(assert_eq, m);
+```reasonligo group=a
+type user = {
+ id : nat,
+ is_admin : bool,
+ name : string
};
```
-`map` is a way to create a new map by modifying the contents of an existing one.
+And here is how a record value is defined:
-
-```pascaligo
-function map_op (const m : moveset) : moveset is
- block {
- function increment (const i : address ; const j : move) : move is block { skip } with (j.0, j.1 + 1) ;
- } with map_map(increment, m) ;
+
+```pascaligo group=a
+const alice : user =
+ record [
+ id = 1n;
+ is_admin = True;
+ name = "Alice"
+ ]
```
-```cameligo
-let map_op (m : moveset) : moveset =
- let increment = fun (i,j: address * move) -> (j.0, j.1 + 1)
+```cameligo group=a
+let alice : user = {
+ id = 1n;
+ is_admin = true;
+ name = "Alice"
+}
+```
+
+
+```reasonligo group=a
+let alice : user = {
+ id : 1n,
+ is_admin : true,
+ name : "Alice"
+};
+```
+
+
+### Accessing Record Fields
+
+If we want the contents of a given field, we use the (`.`) infix
+operator, like so:
+
+
+
+```pascaligo group=a
+const alice_admin : bool = alice.is_admin
+```
+
+
+```cameligo group=a
+let alice_admin : bool = alice.is_admin
+```
+
+
+```reasonligo group=a
+let alice_admin : bool = alice.is_admin;
+```
+
+
+### Functional Updates
+
+Given a record value, it is a common design pattern to update only a
+small number of its fields. Instead of copying the fields that are
+unchanged, LIGO offers a way to only update the fields that are
+modified.
+
+One way to understand the update of record values is the *functional
+update*. The idea is to have an *expression* whose value is the
+updated record.
+
+Let us consider defining a function that translates three-dimensional
+points on a plane.
+
+
+
+
+
+In PascaLIGO, the shape of that expression is ` with
+`. The record variable is the record to update and the
+record value is the update itself.
+
+```pascaligo group=b
+type point is record [x : int; y : int; z : int]
+type vector is record [dx : int; dy : int]
+
+const origin : point = record [x = 0; y = 0; z = 0]
+
+function xy_translate (var p : point; const vec : vector) : point is
+ p with record [x = p.x + vec.dx; y = p.y + vec.dy]
+```
+
+You can call the function `xy_translate` defined above by running the
+following command of the shell:
+```shell
+ligo run-function
+gitlab-pages/docs/language-basics/src/maps-records/record_update.ligo
+translate "(record [x=2;y=3;z=1], record [dx=3;dy=4])"
+# Outputs: {z = 1 , y = 7 , x = 5}
+```
+
+You have to understand that `p` has not been changed by the functional
+update: a namless new version of it has been created and returned by
+the blockless function.
+
+
+
+The syntax for the functional updates of record in CameLIGO follows
+that of OCaml:
+
+```cameligo group=b
+type point = {x : int; y : int; z : int}
+type vector = {dx : int; dy : int}
+
+let origin : point = {x = 0; y = 0; z = 0}
+
+let xy_translate (p, vec : point * vector) : point =
+ {p with x = p.x + vec.dx; y = p.y + vec.dy}
+```
+
+You can call the function `xy_translate` defined above by running the
+following command of the shell:
+```shell
+ligo run-function
+gitlab-pages/docs/language-basics/src/maps-records/record_update.mligo
+xy_translate "({x=2;y=3;z=1}, {dx=3;dy=4})"
+# Outputs: {z = 1 , y = 7 , x = 5}
+```
+
+> You have to understand that `p` has not been changed by the
+> functional update: a nameless new version of it has been created and
+> returned.
+
+
+
+The syntax for the functional updates of record in ReasonLIGO follows
+that of ReasonML:
+
+```reasonligo group=b
+type point = {x : int, y : int, z : int};
+type vector = {dx : int, dy : int};
+
+let origin : point = {x : 0, y : 0, z : 0};
+
+let xy_translate = ((p, vec) : (point, vector)) : point =>
+ {...p, x : p.x + vec.dx, y : p.y + vec.dy};
+```
+
+
+You can call the function `xy_translate` defined above by running the
+following command of the shell:
+```shell
+ligo run-function
+gitlab-pages/docs/language-basics/src/maps-records/record_update.religo
+xy_translate "({x:2,y:3,z:1}, {dx:3,dy:4})"
+# Outputs: {z = 1 , y = 7 , x = 5}
+```
+
+You have to understand that `p` has not been changed by the functional
+update: a nameless new version of it has been created and returned.
+
+### Record Patches
+
+Another way to understand what it means to update a record value is to
+make sure that any further reference to the value afterwards will
+exhibit the modification. This is called a `patch` and this is only
+possible in PascaLIGO, because a patch is an *instruction*, therefore
+we can only use it in a block. Similarly to a *functional update*, a
+patch takes a record to be updated and a record with a subset of the
+fields to update, then applies the latter to the former (hence the
+name "patch").
+
+Let us consider defining a function that translates three-dimensional
+points on a plane.
+
+```pascaligo group=c
+type point is record [x : int; y : int; z : int]
+type vector is record [dx : int; dy : int]
+
+const origin : point = record [x = 0; y = 0; z = 0]
+
+function xy_translate (var p : point; const vec : vector) : point is
+ block {
+ patch p with record [x = p.x + vec.dx];
+ patch p with record [y = p.y + vec.dy]
+ } with p
+```
+
+You can call the function `xy_translate` defined above by running the
+following command of the shell:
+```shell
+ligo run-function
+gitlab-pages/docs/language-basics/src/maps-records/record_patch.ligo
+xy_translate "(record [x=2;y=3;z=1], record [dx=3;dy=4])"
+# Outputs: {z = 1 , y = 7 , x = 5}
+```
+
+Of course, we can actually translate the point with only one `patch`,
+as the previous example was meant to show that, after the first patch,
+the value of `p` indeed changed. So, a shorter version would be
+
+```pascaligo group=d
+type point is record [x : int; y : int; z : int]
+type vector is record [dx : int; dy : int]
+
+const origin : point = record [x = 0; y = 0; z = 0]
+
+function xy_translate (var p : point; const vec : vector) : point is
+ block {
+ patch p with record [x = p.x + vec.dx; y = p.y + vec.dy]
+ } with p
+```
+
+You can call the new function `xy_translate` defined above by running the
+following command of the shell:
+```shell
+ligo run-function
+gitlab-pages/docs/language-basics/src/maps-records/record_patch2.ligo
+xy_translate "(record [x=2;y=3;z=1], record [dx=3;dy=4])"
+# Outputs: {z = 1 , y = 7 , x = 5}
+```
+
+Record patches can actually be simulated with functional updates. All
+we have to do is *declare a new record value with the same name as the
+one we want to update* and use a functional update, like so:
+
+```pascaligo group=e
+type point is record [x : int; y : int; z : int]
+type vector is record [dx : int; dy : int]
+
+const origin : point = record [x = 0; y = 0; z = 0]
+
+function xy_translate (var p : point; const vec : vector) : point is
+ block {
+ const p : point = p with record [x = p.x + vec.dx; y = p.y + vec.dy]
+ } with p
+```
+
+You can call the new function `xy_translate` defined above by running the
+following command of the shell:
+```shell
+ligo run-function
+gitlab-pages/docs/language-basics/src/maps-records/record_simu.ligo
+xy_translate "(record [x=2;y=3;z=1], record [dx=3;dy=4])"
+# Outputs: {z = 1 , y = 7 , x = 5}
+```
+
+The hiding of a variable by another (here `p`) is called `shadowing`.
+
+## Maps
+
+*Maps* are a data structure which associate values of the same type to
+values of the same type. The former are called *key* and the latter
+*values*. Together they make up a *binding*. An additional requirement
+is that the type of the keys must be *comparable*, in the Michelson
+sense.
+
+Here is how a custom map from addresses to a pair of integers is
+defined.
+
+
+
+```pascaligo group=f
+type move is int * int
+type register is map (address, move)
+```
+
+
+```cameligo group=f
+type move = int * int
+type register = (address, move) map
+```
+
+
+```reasonligo group=f
+type move = (int, int);
+type register = map (address, move);
+```
+
+
+And here is how a map value is defined:
+
+
+
+
+```pascaligo group=f
+const moves : register =
+ map [
+ ("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx" : address) -> (1,2);
+ ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address) -> (0,3)]
+```
+
+> Notice the `->` between the key and its value and `;` to separate
+> individual map entries. The annotated value `("" :
+> address)` means that we cast a string into an address. Also, `map`
+> is a keyword.
+
+
+```cameligo group=f
+let moves : register =
+ Map.literal [
+ (("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx" : address), (1,2));
+ (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address), (0,3))]
+```
+
+> The `Map.literal` predefined function builds a map from a list of
+> key-value pair tuples, `(, )`. Note also the `;` to
+> separate individual map entries. `("": address)`
+> means that we type-cast a string into an address.
+
+
+```reasonligo group=f
+let moves : register =
+ Map.literal ([
+ ("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx" : address, (1,2)),
+ ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address, (0,3))]);
+```
+
+> The `Map.literal` predefined function builds a map from a list of
+> key-value pair tuples, `(, )`. Note also the `;` to
+> separate individual map entries. `("": address)`
+> means that we type-cast a string into an address.
+
+
+
+### Accessing Map Bindings
+
+
+
+
+In PascaLIGO, we can use the postfix `[]` operator to read the `move`
+value associated to a given key (`address` here) in the register. Here
+is an example:
+
+```pascaligo group=f
+const my_balance : option (move) =
+ moves [("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address)]
+```
+
+
+```cameligo group=f
+let my_balance : move option =
+ Map.find_opt ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address) moves
+```
+
+
+```reasonligo group=f
+let my_balance : option (move) =
+ Map.find_opt (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address), moves);
+```
+
+
+Notice how the value we read is an optional value: this is to force
+the reader to account for a missing key in the map. This requires
+*pattern matching*.
+
+
+
+
+```pascaligo group=f
+function force_access (const key : address; const moves : register) : move is
+ case moves[key] of
+ Some (move) -> move
+ | None -> (failwith ("No move.") : move)
+ end
+```
+
+
+```cameligo group=f
+let force_access (key, moves : address * register) : move =
+ match Map.find_opt key moves with
+ Some move -> move
+ | None -> (failwith "No move." : move)
+```
+
+
+```reasonligo group=f
+let force_access = ((key, moves) : (address, register)) : move => {
+ switch (Map.find_opt (key, moves)) {
+ | Some (move) => move
+ | None => failwith ("No move.") : move
+ }
+};
+```
+
+
+
+### Updating a Map
+
+Given a map, we may want to add a new binding, remove one, or modify
+one by changing the value associated to an already existing key. We
+may even want to retain the key but not the associated value. All
+those operations are called *updates*.
+
+
+
+
+
+The values of a PascaLIGO map can be updated using the usual
+assignment syntax `