Commit 86b757492fc6e0323ff81a670684e091550ca1b3

Thomas de Grivel 2025-05-02T13:13:22

document named blocks

diff --git a/.ikc3_history b/.ikc3_history
index d42da38..cdd74dd 100644
--- a/.ikc3_history
+++ b/.ikc3_history
@@ -1,18 +1,3 @@
-q
-"#{inspect(%HTTP.Upload{})}"
-git diff
-Math.pow(2, 3)
-Math.greatest_divisor(4)
-Math.greatest_divisor(5)
-Math.greatest_divisor(6)
-Math.greatest_divisor(4)
-Math.greatest_divisor(1)
-Math.greatest_divisor(2)
-Math.greatest_divisor(3)
-Math.greatest_divisor(4)
-Math.greatest_divisor(5)
-Math.nth_mersenne_prime(2, 1)
-Math.nth_mersenne_prime(2, 2)
 Math.nth_mersenne_prime(2, 3)
 Math.nth_mersenne_prime(2, 1)
 Math.nth_mersenne_prime(2, 2)
@@ -97,3 +82,18 @@ s = %File.Stat{st_dev: (Uw) 1039}
 s.st_mtim
 List.to_array
 a = %KC3.Op{sym: :dot, callable: fn (a, b) { a.x * b.y + a.y * b.y }}
+block :abc do
+  return 1
+end
+block :abc do
+  return 1
+  123
+end
+block :abc do
+  return_from :abc 1
+  123
+end
+block :abc do
+  return_from :abc 1 + 1
+  123
+end
diff --git a/doc/1_KC3/1.03_Block.en.md b/doc/1_KC3/1.03_Block.en.md
index 6d5c778..6489622 100644
--- a/doc/1_KC3/1.03_Block.en.md
+++ b/doc/1_KC3/1.03_Block.en.md
@@ -1,9 +1,9 @@
-# 1.3 Block
+# 1.3 Do block
 
-A KC3 block is a source code block. It starts with `do` or `{` and
+A KC3 **do** block is a source code block. It starts with `do` or `{` and
 ends with `end` or `}` respectively.
 It can be passed to a special operator or macro function to
-be evaluated explicitly in C with `env_eval_block` (see
+be evaluated explicitly in C with `env_eval_do_block` (see
 `libkc3/env_eval.c`).
 
 A block evaluates all its instructions in turn, and returns the value
diff --git a/doc/1_KC3/1.25_Facts.en.md b/doc/1_KC3/1.25_Facts.en.md
index fddb6cb..a18a923 100644
--- a/doc/1_KC3/1.25_Facts.en.md
+++ b/doc/1_KC3/1.25_Facts.en.md
@@ -72,4 +72,4 @@ Top : [KC3 documentation](/doc/)
 
 Previous : [1.24 Variable](1.24_Variable)
 
-Next : [2 HTTPd](../2_HTTPd)
+Next : [1.26 Named block](1.26_Named_block)
diff --git a/doc/1_KC3/1.26_Named_block.en.md b/doc/1_KC3/1.26_Named_block.en.md
new file mode 100644
index 0000000..05a7b12
--- /dev/null
+++ b/doc/1_KC3/1.26_Named_block.en.md
@@ -0,0 +1,29 @@
+# 1.26 Named block
+
+In KC3, a named block is a macro that allows you to do debranching returns.
+First you create a block using `block :name do ... end`, then using
+`return` or `return_from :name` you can return an abitrary value from
+the block, expressions after return are not executed.
+
+## 1.26.1 Examples
+
+```elixir
+ikc3> block :abc do
+ikc3>   return 1
+ikc3>   123
+ikc3> end
+1
+ikc3> block :abc do
+ikc3>   return_from :abc 1 + 1
+ikc3>   123
+ikc3> end
+2
+```
+
+---
+
+Top : [KC3 documentation](/doc/)
+
+Previous : [1.25 Facts](1.25_Facts)
+
+Next : [2 HTTPd](../2_HTTPd)