Add variable repetition count support

[normand.git] / README.adoc

diff --git a/README.adoc b/README.adoc
index 3ec0744c7f176116726e2b6fc92bdfa8532432f3..7e455408e72e30b65aae1f5ca7ab81e6ac350773 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -157,15 +157,19 @@ Repetition::
 Input:
 +
 ----
-aa bb * 5 cc "yeah\0" * 8
+aa bb * 5 cc <zoom> "yeah\0" * {zoom * 3}
 ----
 +
 Output:
 +
 ----
-aa bb bb bb bb bb cc 79  65 61 68 00 79 65 61 68  ┆ •••••••yeah.yeah
+aa bb bb bb bb bb cc 79  65 61 68 00 79 65 61 68  ┆ •••••••yeah•yeah
+00 79 65 61 68 00 79 65  61 68 00 79 65 61 68 00  ┆ •yeah•yeah•yeah•
+79 65 61 68 00 79 65 61  68 00 79 65 61 68 00 79  ┆ yeah•yeah•yeah•y
+65 61 68 00 79 65 61 68  00 79 65 61 68 00 79 65  ┆ eah•yeah•yeah•ye
+61 68 00 79 65 61 68 00  79 65 61 68 00 79 65 61  ┆ ah•yeah•yeah•yea
+68 00 79 65 61 68 00 79  65 61 68 00 79 65 61 68  ┆ h•yeah•yeah•yeah
 00 79 65 61 68 00 79 65  61 68 00 79 65 61 68 00  ┆ •yeah•yeah•yeah•
-79 65 61 68 00 79 65 61  68 00 79 65 61 68 00     ┆ yeah•yeah•yeah•
 ----
 
 
@@ -200,7 +204,7 @@ Precise error reporting::
 ----
 +
 ----
-/tmp/meow.normand:24:19 - Unknown variable/label name `meow` in expression `(meow - 45) // 8`.
+/tmp/meow.normand:24:19 - Illegal (unknown or unreachable) variable/label name `meow` in expression `(meow - 45) // 8`; the legal names are {`mix`, `zoom`}.
 ----
 +
 ----
@@ -311,7 +315,8 @@ This is similar to an assembly label.
 * A <<group,group>>, that is, a scoped sequence of items.
 
 Moreover, you can <<repetition,repeat>> any item above, except an offset
-or a label, a given number of times. This is called a repetition.
+or a label, a given fixed or variable number of times. This is called a
+repetition.
 
 A Normand comment may exist:
 
@@ -319,7 +324,8 @@ A Normand comment may exist:
 * Between the nibbles of a constant hexadecimal byte.
 * Between the bits of a constant binary byte.
 * Between the last item and the ``pass:[*]`` character of a repetition,
-  and between that ``pass:[*]`` character and the following number.
+  and between that ``pass:[*]`` character and the following number
+  or expression.
 
 A comment is anything between two ``pass:[#]`` characters on the same
 line, or from ``pass:[#]`` until the end of the line. Whitespaces and
@@ -807,8 +813,16 @@ A repetition is:
 
 . The ``pass:[*]`` character.
 
-. A positive integer (hexadecimal starting with `0x` or `0X` accepted)
-  which is the number of times to repeat the previous item.
+. One of:
+
+** A positive integer (hexadecimal starting with `0x` or `0X` accepted)
+   which is the number of times to repeat the previous item.
+
+** The ``pass:[{]`` prefix, a valid {py3} expression, and the
+   ``pass:[}]`` suffix.
+
+When using an expression, it can't refer, directly or indirectly, to a
+subsequent label name and to the reserved `ICITTE` name.
 
 ====
 Input:
@@ -839,6 +853,65 @@ af ae ad ac ab aa a9 a8  a7 a6 a5 a4 a3 a2 a1 a0  ┆ ••••••••
 ----
 ====
 
+====
+Input:
+
+----
+{times = 1}
+aa bb cc dd
+(
+  <here>
+  (ee ff) * {here + 1}
+  11 22 33 * {times}
+  {times = times + 1}
+) * 3
+"coucou!"
+----
+
+Output:
+
+----
+aa bb cc dd ee ff ee ff  ee ff ee ff ee ff 11 22  ┆ •••••••••••••••"
+33 ee ff ee ff ee ff ee  ff ee ff ee ff ee ff ee  ┆ 3•••••••••••••••
+ff ee ff ee ff ee ff ee  ff ee ff ee ff ee ff ee  ┆ ••••••••••••••••
+ff ee ff ee ff 11 22 33  33 ee ff ee ff ee ff ee  ┆ ••••••"33•••••••
+ff ee ff ee ff ee ff ee  ff ee ff ee ff ee ff ee  ┆ ••••••••••••••••
+ff ee ff ee ff ee ff ee  ff ee ff ee ff ee ff ee  ┆ ••••••••••••••••
+ff ee ff ee ff ee ff ee  ff ee ff ee ff ee ff ee  ┆ ••••••••••••••••
+ff ee ff ee ff ee ff ee  ff ee ff ee ff ee ff ee  ┆ ••••••••••••••••
+ff ee ff ee ff ee ff ee  ff ee ff ee ff ee ff ee  ┆ ••••••••••••••••
+ff ee ff ee ff ee ff ee  ff ee ff ee ff ee ff ee  ┆ ••••••••••••••••
+ff ee ff ee ff ee ff ee  ff ee ff ee ff 11 22 33  ┆ ••••••••••••••"3
+33 33 63 6f 75 63 6f 75  21                       ┆ 33coucou!
+----
+====
+
+====
+This example shows how to use a repetition as a conditional section
+depending on some predefined variable.
+
+Input:
+
+----
+aa bb cc dd
+(ee ff "meow mix" 00) * {cond}
+{be} {-1993:16}
+----
+
+Output (`cond` is 0):
+
+----
+aa bb cc dd f8 37
+----
+
+Output (`cond` is 1):
+
+----
+aa bb cc dd ee ff 6d 65  6f 77 20 6d 69 78 00 f8  ┆ ••••••meow mix••
+37                                                ┆ 7
+----
+====
+
 == Command-line tool
 
 If you <<install-normand,installed>> the `normand` package, then you