Add offset alignment support

[normand.git] / README.adoc

diff --git a/README.adoc b/README.adoc
index 44e62c513f90f599a86a4d58335974fdfb4fa24b..954f3546e56049e45d41333f82fe24ea2e26c9e4 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -29,7 +29,7 @@ _**Normand**_ is a text-to-binary processor with its own language.
 This package offers both a portable {py3} module and a command-line
 tool.
 
-WARNING: This version of Normand is 0.6, meaning both the Normand
+WARNING: This version of Normand is 0.7, meaning both the Normand
 language and the module/CLI interface aren't stable.
 
 ifdef::env-github[]
@@ -192,6 +192,25 @@ aa bb bb bb bb bb cc 79  65 61 68 00 79 65 61 68  ┆ •••••••yeah
 00 79 65 61 68 00 79 65  61 68 00 79 65 61 68 00  ┆ •yeah•yeah•yeah•
 ----
 
+Alignment::
++
+Input:
++
+----
+{be}
+
+        {199:32}
+@64     {43:64}
+@16     {-123:16}
+@32~255 {5584:32}
+----
++
+Output:
++
+----
+00 00 00 c7 00 00 00 00  00 00 00 00 00 00 00 2b
+ff 85 ff ff 00 00 15 d0
+----
 
 Multilevel grouping::
 +
@@ -285,7 +304,10 @@ number>>, <<leb-128-integer,LEB128 integer>>, and
 Each generated byte increments the current offset.
 
 A <<current-offset-setting,current offset setting>> may change the
-current offset.
+current offset without generating data.
+
+An <<current-offset-alignment,current offset alignment>> generates
+padding bytes to make the current offset satisfy a given alignment.
 |`init_offset` parameter of the `parse()` function.
 |`--offset` option.
 
@@ -329,6 +351,8 @@ The available items are:
 
 * A <<current-offset-setting,current offset setting>>.
 
+* A <<current-offset-alignment,current offset alignment>>.
+
 * A <<label,label>>, that is, a named constant holding the current
   offset.
 +
@@ -358,7 +382,7 @@ the following symbol characters are also considered comments where a
 comment may exist:
 
 ----
-! @ / \ ? & : ; . , + [ ] _ = | -
+! / \ ? & : ; . , + [ ] _ = | -
 ----
 
 The latter serve to improve readability so that you may write, for
@@ -784,6 +808,82 @@ aa bb cc dd ee ff 11 22  33 44 55 04 0f  ┆ •••••••"3DU••
 ----
 ====
 
+=== Current offset alignment
+
+An _current offset alignment_ represents zero or more padding bytes to
+make the <<cur-offset,current offset>> meet a given
+https://en.wikipedia.org/wiki/Data_structure_alignment[alignment] value.
+
+More specifically, for an alignment value of{nbsp}__**N**__{nbsp}bits,
+a current offset alignment represents the required padding bytes until
+the current offset is a multiple of __**N**__{nbsp}/{nbsp}8.
+
+A current offset alignment is:
+
+. The `@` prefix.
+
+. A positive integer (hexadecimal starting with `0x` or `0X` accepted)
+  which is the alignment value in _bits_.
++
+This value must be greater than zero and a multiple of{nbsp}8.
+
+. **Optional**:
++
+--
+. The ``pass:[~]`` prefix.
+. A positive integer (hexadecimal starting with `0x` or `0X` accepted)
+  which is the value of the byte to use as padding to align the
+  <<cur-offset,current offset>>.
+--
++
+Without this section, the padding byte value is zero.
+
+====
+Input:
+
+----
+11 22 (@32 aa bb cc) * 3
+----
+
+Output:
+
+----
+11 22 00 00 aa bb cc 00  aa bb cc 00 aa bb cc
+----
+====
+
+====
+Input:
+
+----
+{le}
+77 88
+@32~0xcc {-893.5:32}
+@128~0x55 "meow"
+----
+
+Output:
+
+----
+77 88 cc cc 00 60 5f c4  55 55 55 55 55 55 55 55  ┆ w••••`_•UUUUUUUU
+6d 65 6f 77                                       ┆ meow
+----
+====
+
+====
+Input:
+
+----
+aa bb cc <29> @64~255 "zoom"
+----
+
+Output:
+
+----
+aa bb cc ff ff ff 7a 6f  6f 6d  ┆ ••••••zoom
+----
+====
+
 === Label
 
 A _label_ associates a name to the <<cur-offset,current offset>>.
@@ -927,7 +1027,13 @@ of times.
 
 A repetition is:
 
-. Any item.
+. Any item except:
+
+** A <<current-byte-order-setting,current byte order setting>>.
+** A <<current-offset-setting,current offset setting>>.
+** A <<label,label>>.
+** A <<offset-alignment,offset alignment>>.
+** A <<variable-assignment,variable assignment>>.
 
 . The ``pass:[*]`` character.