Rework conditionals topic in language-basics

gitlab-pages/docs/data-types/booleans.md

@@ -5,7 +5,7 @@ title: Booleans
 
 import Syntax from '@theme/Syntax';
 
-The predefined type `bool` has exactly two values: `true` and `false`.
+The predefined Boolean type `bool` has exactly two values: `true` and `false`.
 
 <Syntax syntax="cameligo">
 
@@ -29,9 +29,7 @@ const b: bool = false;
 
 <Syntax syntax="cameligo">
 
-The logical disjunction ("or") is implemented by the binary operator
-`||`:
-
+The logical disjunction ("or") is implemented by the binary operator `||`:
 
 ```cameligo group=or
 let or_1 : bool = false || true  // true
@@ -40,8 +38,7 @@ let or_3 : bool = true  || true  // true
 let or_4 : bool = true  || false // true
 ```
 
-Note that you can also use the keyword `or` instead of the symbol `||`
-(as in OCaml):
+You can also use the keyword `or` instead of the symbol `||` (as in OCaml):
 
 ```cameligo group=or
 let or_1 : bool = false or true  // true
@@ -54,8 +51,7 @@ let or_4 : bool = true  or false // true
 
 <Syntax syntax="jsligo">
 
-The logical disjunction ("or") is implemented by the binary operator
-`||`.
+The logical disjunction ("or") is implemented by the binary operator `||`.
 
 ```jsligo group=or
 const or_1: bool = false || true;  // true
@@ -68,8 +64,7 @@ const or_4: bool = true  || false; // true
 
 ## And
 
-The logical conjunction ("and") is implemented by the binary operator
-`&&`.
+The logical conjunction ("and") is implemented by the binary operator `&&`.
 
 <Syntax syntax="cameligo">
 
@@ -97,8 +92,7 @@ const and_4: bool = true  && false; // false
 
 <Syntax syntax="cameligo">
 
-The logical negation ("not") is implemented by the unary operator
-`not`.
+The logical negation ("not") is implemented by the unary operator `not`.
 
 ```cameligo group=not
 let not_1 : bool = not true  // false
@@ -109,8 +103,7 @@ let not_2 : bool = not false // true
 
 <Syntax syntax="jsligo">
 
-The logical negation ("not") is implemented by the unary operator
-`!`.
+The logical negation ("not") is implemented by the unary operator `!`.
 
 ```jsligo group=not
 const not_1: bool = !true  // false
@@ -121,12 +114,10 @@ const not_2: bool = !false // true
 
 ## Comparing
 
-Boolean values are the result of comparisons of values. Numbers and
-strings are completely ordered. Booleans can be compared for
-equality. Two values need to be of the same type to be compared, but
-not all values of the same type can be compared: only those with <em>comparable types</em> (a concept directly lifted from Michelson)
-such as `int`, `nat`, `string`, and `bool` itself. The comparison
-operators are overloaded so they are defined on all comparable types.
+Boolean values are the result of comparisons of other values.
+As described in [Comparisons](../syntax/comparisons), values must be the same type to be compared, and not all types are comparable.
+You can compare comparable types such as `int`, `nat`, `string`, and `bool` to each other.
+The comparison operators are overloaded so they are defined on all comparable types, as in these examples:
 
 <Syntax syntax="cameligo">
 
@@ -154,41 +145,31 @@ const f: bool = 0 <= 0;  // lower than or equal (true)
 
 </Syntax>
 
-## Conditional expressions
-
-Conditional logic enables forking the control flow depending on the
-state, that is, the values available at a given point in the code. Put
-in a less technical manner, conditionals enable decision making.
-
-A conditional expression is made of three parts:
-<ol>
-  <li> a condition, that is, a boolean expression;</li>
-  <li> an expression evaluated if, and only if, the condition is true;</li>
-  <li> an expression evaluated if, and only if, the condition is false.</li>
-</ol>
+You can also use a single value to create a Boolean value.
+For example, empty strings and the number 0 are false, while strings with any content in them and nonzero numbers are true:
 
 <Syntax syntax="cameligo">
 
-The syntax uses the keywords `if`, `then` and `else` to separate the
-three parts, like so:
-
-```cameligo group=conditionals
-let a = 0
-let b = 1
-let min = if a < b then a else b // min = 0
+```cameligo group=unary_boolean
+let natToBoolTrue : bool = 1n      (* True *)
+let natToBoolFalse : bool = 0n     (* False *)
+let stringToBoolTrue : bool = "A"  (* True *)
+let stringToBoolFalse : bool = ""  (* False *)
 ```
 
 </Syntax>
 
 <Syntax syntax="jsligo">
 
-The syntax uses a ternary operator with the symbols `?` and `:` to
-separate the three parts:
-
-```jsligo group=conditionals
-const a = 0;
-const b = 1;
-const min = (a < b) ? a : b; // min == 0
+```jsligo group=unary_boolean
+const natToBoolTrue: bool = (1 as nat);   // True
+const natToBoolFalse: bool = (0 as nat);  // False
+const stringToBoolTrue: bool = "A";       // True
+const stringToBoolFalse: bool = "";       // False
 ```
 
 </Syntax>
+
+For more information about comparing values, see [Comparisons](../syntax/comparisons).
+
+You can use Boolean values and comparisons in logical `if` and `else` statements like many other languages; see [Conditionals](../imperative/conditionals).

gitlab-pages/docs/imperative/conditionals.md

@@ -0,0 +1,114 @@
+---
+id: conditionals
+title: Conditionals
+---
+
+LIGO includes logical `if` and `else` statements like many other languages.
+
+<Syntax syntax="cameligo">
+
+```cameligo group=if
+let greater_than_5 (input : int) : bool =
+  if input > 5 then true else false
+```
+
+:::note
+
+As in OCaml, in CameLIGO, if a conditional has a branch `else ()`, that branch can be omitted.
+The resulting so-called *dangling else* problem is parsed by associating any `else` to the closest previous `then`.
+
+:::
+
+</Syntax>
+
+<Syntax syntax="jsligo">
+
+```jsligo group=if
+function greater_than_5(input: int) {
+  if (input > 5) {
+    return true;
+  } else {
+    return false;
+  }
+}
+```
+
+</Syntax>
+
+<Syntax syntax="jsligo">
+
+## Switch statement
+
+JsLIGO also supports branching of control flow via the `switch` statement.
+
+```jsligo group=switch
+let quarter = n => {
+  let output = "";
+  switch (n) {
+    case 1:
+    case 2:
+    case 3:
+      output = "Q1";
+      break;
+    case 4:
+    case 5:
+    case 6:
+      output = "Q2";
+      break;
+    case 7:
+    case 8:
+    case 9:
+      output = "Q3";
+      break;
+    case 10:
+    case 11:
+    case 12:
+      output = "Q4";
+      break;
+    default:
+      output = "Invalid month."
+  };
+  return output;
+}
+```
+
+The `switch` statement takes an expression and tries to find a case that matches the expression.
+If a matching case is found, the statements of the matching case are executed until a `break;` statement.
+If no `break` statement is found, LIGO continues to the next case or `default` case.
+If no matching case is found, LIGO runs the statements in the `default` case.
+
+In LIGO, the `switch` statement has these limitations:
+
+- The `switch` statement must have at least one case or `default` case.
+- If a `default` case is provided, it should be the last case.
+- Conditional `break` statements are not supported; for example, you can't include a `break` statement inside a `if-then-else` block.
+- In the case of nested `switch` statements, the inner `switch` statement should not contain a `return` statement.
+
+You can run the `quarter` function defined above using the LIGO compiler like this:
+
+```shell
+ligo run evaluate-call  gitlab-pages/docs/imperative/src/conditionals/switch.jsligo quarter '5'
+# Outputs: "Q2"
+```
+
+## Ternary conditional expression
+
+JsLIGO also supports JavaScript's ternary expression:
+
+```jsligo group=ternary
+const ternary = a => (a == 1) ? true : false;
+```
+
+Ternary expressions can be nested, as in this example:
+
+```jsligo group=ternary
+const ternary_nested = a =>
+  a == 1 ? "one"   :
+  a == 2 ? "two"   :
+  a == 3 ? "three" :
+           "other"
+```
+
+</Syntax>
+
+<!-- updated use of entry -->