language improvements

- Arithmetic operators:
  - Division operators can't have a wrapping or saturating version
  - Use `%` prefix for wrapping version (instead of `@`)
  - Removing skipping version of the operators
  - New extending type of operators
- Changing `=?`, `=!`, `>=?` `<=?` to `=?=`, `=/=`, `>?=`, `<?=`
- Leaving `_ |? _ |: _` for ternary operator and changing pattern matching to `>| _ => _`
- Clarifying syntax for generic closure function arguments with `fx _: F: a -> b => a, F -> b`

Author: dr-orlovsky

CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 1st Nov 2024
+
+- Arithmetic operators:
+  - Division operators can't have a wrapping or saturating version
+  - Use `%` prefix for wrapping version (instead of `@`)
+  - Removing skipping version of the operators
+  - New extending type of operators
+- Changing `=?`, `=!`, `>=?` `<=?` to `=?=`, `=/=`, `>?=`, `<?=`
+- Leaving `_ |? _ |: _` for ternary operator and changing pattern matching to `>| _ => _`
+- Clarifying syntax for generic closure function arguments with `fx _: F: a -> b => a, F -> b`

content/category.md

@@ -134,7 +134,7 @@ val projA := new.a
 val projB := new.b
 
 -- testing that the result is the same as the original values:
-projA =? valueA && projB =? valueB !! mustBeEqual 
+projA =?= valueA && projB =?= valueB !! mustBeEqual 
 ```
 
 <aside>

content/design.md

@@ -190,18 +190,22 @@ components and pattern-match against them. In other words, injection operators a
 they are the way how *if-else* statements and pattern matching is handled in the language.
 
 There are several ways of doing branching constructions using injection operators. First, one can use `value >|` in
-combination with `pattern |?` expressions to match the value against a set of patterns and handle a default variant
-with `|:`:
+combination with `pattern => code` expressions to match the value against a set of patterns and handle a default variant
+with `_ => code`:
+
+<aside>
+  <p>We use `=>` operator to signify that each pattern is in fact a natural transformation</p>
+</aside>
 
 ```
 data WorldDirection: north | south | west | east
 
 val sample: WorldDirection
 
 sample >|                   – match sample {
-  north |? doSomething1     –   north => {} 
-  south |? doSomething2     –   south => {}
-        |: doSomething3     –   _ => {}
+  north => doSomething1     –   north => {} 
+  south => doSomething2     –   south => {}
+      _ => doSomething3     –   _ => {}
                             – }
 ```
 
@@ -221,11 +225,11 @@ condition. Let's assume we have an expression `test` which results in a boolean
 </aside>
 
 ```
-sample =? north             – if sample == north
+sample =?= north             – if sample == north
 |? doSomething1
 |: doSomething2             – else
 
-sample =? north             – if sample == north
+sample =?= north             – if sample == north
 |? doSomething1
 |: sample =? south          – else if sample == south
 |? doSomething2             
@@ -549,22 +553,22 @@ class ord
   
   @final
   infx `<?`: a Self, b Self -> Bool
-    ~ a >? b
+    ~ (a >? b)
 
 class eq: ord
-  infx `=?`: Self, Self -> Bool
+  infx `=?=`: Self, Self -> Bool
 
   @final
-  infx `=!`: a Self, b Self -> Bool
+  infx `=/=`: a Self, b Self -> Bool
     ~ a =? b
   
   @final
-  infx `>=?`: a Self, b Self -> Bool
-    a =? b |? true |: a >? b
+  infx `>?=`: a Self, b Self -> Bool
+    a =?= b |? true |: a >? b
   
   @final
-  infx `<=?`: a Self, b Self -> Bool
-    a =? b |? true |: a <? b
+  infx `<?=`: a Self, b Self -> Bool
+    a =?= b |? true |: a <? b
 ```
 
 <aside>

content/examples.md

@@ -98,11 +98,11 @@ class iter: item any
     fx next: _ -> item?
 
 infx findFirst: V eq, I iter(item eq) => iter I, value V -> U64?
-    enumerate iter |> fst =? value |? $ := lst _
+    enumerate iter |> fst =?= value |? $ := lst _
 
 infx hasUnique: V eq, I iter(item eq) => iter I, value V -> Bool
     val index := iter findFirst value !! false
-    (iter[index..] |> =? value |? $ := false) ?? true
+    (iter[index..] |> =?= value |? $ := false) ?? true
     
 [0, 1, 2, 3, 4] hasUnique 1 -- true
 ```
@@ -136,18 +136,18 @@ class ord
     ~ a >? b
 
 class eq: ord
-  infx `=?`: Self, Self -> Bool
+  infx `=?=`: Self, Self -> Bool
 
   @final
-  infx `=!`: a Self, b Self -> Bool
-    ~ a =? b
+  infx `=/=`: a Self, b Self -> Bool
+    ~ (a =?= b)
   
   @final
-  infx `>=?`: a Self, b Self -> Bool
-    a =? b |? true |: a >? b
+  infx `>?=`: a Self, b Self -> Bool
+    a =?= b |? true |: a >? b
   
   @final
-  infx `<=?`: a Self, b Self -> Bool
-    a =? b |? true |: a <? b
+  infx `<?=`: a Self, b Self -> Bool
+    a =?= b |? true |: a <? b
 ```
 

content/reference.md

@@ -168,13 +168,22 @@ Call of an infix function `infn` is `arg0 infn arg1, .., argLast`. It can be rev
 
 #### Injections
 
-Constructs with `>|`, `|?`, `|:` symbols are called branching operators.
-They correspond to `match { .. -> .., .. -> .. }` construction.
+Injections are branching operators, which allow code execution to branch execution basing on a value of a co-product
+type. They are either pattern matching (an equivalent of Rust `match` and Haskell `case`), or a boolean-test based.
 
-Operator `.. |? .. |: ..` is also the ternary operator, corresponding to
-`if .. then .. else` construction. It also has a form of
-`condition1 |? statement1 |: condition2 |? statement2 |: statementElse`,
-corresponding to
+Pattern matching is done with `>|` infix operator, which takes a value of a co-product type on the left side, and a
+set of natural transformations matching each of the injections on the right:
+
+```idris
+value >|
+  pattern1 => code
+  pattern2 => code
+  _ => code -- default match
+```
+
+Branching based on the boolean conditions uses `.. |? .. |: ..` operator, which is also a ternary operator, 
+corresponding to `if .. then .. else` construction. It also has a form of
+`condition1 |? statement1 |: condition2 |? statement2 |: statementElse`, corresponding to
 `if condition1 then statement1 elseIf condition2 then statement2 else statementElse`.
 
 #### Annotations
@@ -322,9 +331,9 @@ postfixed with a symbol representing the way of handling overflow, underflow or
 - `?` for converting the result of the operation into `Maybe` monad;
 - `!` for converting the result of the operation into `Result::error` monad variant with details on specific condition
   which has occurred;
-- `@` for wrapping a value in case of overflow;
+- `%` for wrapping a value in case of overflow (modulo-arithmetic) and returning `ArRes` monad;
 - `^` for saturating a value with a maximum possible value in case of overflow;
-- `|` for skipping the operation as whole.
+- with no postfix for extending the result type to the next bit dimension so it always fits.
 
 Additionally, Cation allows <dfn>native arithmetic operations</dfn> when an operation itself and the resulting type 
 guarantees impossibility of overflow or other exceptional conditions. These operations are:
@@ -341,14 +350,14 @@ guarantees impossibility of overflow or other exceptional conditions. These oper
 
 Thus, the resulting table of the arithmetic operations is the following:
 
-| Operation       | Native | Maybe | Result | Wrapping | Saturating | Skipping |
-|-----------------|--------|-------|--------|----------|------------|----------|
-| Addition        | `+`    | `+?`  | `+!`   | `+@`     | `+^`       | `+`\|    |
-| Subtraction     | `-`    | `-?`  | `-!`   | `-@`     | `-^`       | `-`\|    |
-| Multiplication  | `*`    | `*?`  | `*!`   | `*@`     | `*^`       | `*`\|    |
-| Division        | `/`    | `/?`  | `/!`   | `/@`     | `/^`       | `/`\|    |
-| Modulo division | `%`    | `%?`  | `%!`   | `%@`     | `%^`       | `%`\|    |
-| Potentiation    | `^`    | `^?`  | `^!`   | `^@`     | `^^`       | `^`\|    |
+| Operation       | Native | Maybe | Result | Wrapping | Saturating | Extending |
+|-----------------|--------|-------|--------|----------|------------|-----------|
+| Addition        | `+`    | `+?`  | `+!`   | `+%`     | `+^`       | `+`       |
+| Subtraction     | `-`    | `-?`  | `-!`   | `-%`     | `-^`       | `-`       |
+| Multiplication  | `*`    | `*?`  | `*!`   | `*%`     | `*^`       | `*`       |
+| Division        | `/`    | `/?`  | `/!`   | n/a      | n/a        | n/a       |
+| Modulo division | `%`    | `%?`  | `%!`   | n/a      | n/a        | n/a       |
+| Potentiation    | `^`    | `^?`  | `^!`   | `^%`     | `^^`       | `^`       |
 
 #### Bitwise operators
 

content/stdlib.md

@@ -36,3 +36,28 @@ template = "page.html"
 
 - `read`
 - `write`
+
+## Monads
+
+```idris
+data Maybe: T => none | some(T)
+
+data Result: T, E => err(E) | ok(T)
+
+data Either: L, R => left(L) | right(R)
+
+data Tern: N, P => neg(N)#0xff | zero#0 | pos(p)#1
+
+data MayError: R, E => ok T, err Maybe E
+
+fx map: T, U, F: T -> U => Maybe T, F -> Maybe U
+   none, _ => none
+   some(val), f => some(f val)
+
+infx `=?=`: T eq => _ Maybe T, _ Maybe T -> Bool
+    none, none => true
+    some(_), none | none, some(_) => false
+    some(v), some(w) => v =?= w
+
+impl eq: T eq => Maybe T
+```