1 // Show ToC at a specific location for a GitHub rendering
10 // This is to mimic what GitHub does so that anchors work in an offline
21 image::normand-logo.png[]
24 image:https://img.shields.io/pypi/v/normand.svg?label=Latest%20version[link="https://pypi.python.org/pypi/normand"]
27 _**Normand**_ is a text-to-binary processor with its own language.
29 This package offers both a portable {py3} module and a command-line
32 WARNING: This version of Normand is 0.8, meaning both the Normand
33 language and the module/CLI interface aren't stable.
36 // ToC location for a GitHub rendering
42 The purpose of Normand is to consume human-readable text representing
43 bytes and to produce the corresponding binary data.
47 Consider the following Normand input:
50 4f 55 32 bb $167 fe %10100111 a9 $-32
53 The generated nine bytes are:
56 4f 55 32 bb a7 fe a7 a9 e0
60 As you can see in the last example, the fundamental unit of the Normand
61 language is the _byte_. The order in which you list bytes will be the
62 order of the generated data.
64 The Normand language is more than simple lists of bytes, though. Its
67 Comments, including a bunch of insignificant symbols which may improve readability::
72 ff bb %1101:0010 # This is a comment
73 78 29 af $192 # This too # 99 $-80
74 fe80::6257:18ff:fea3:4229
76 10839636-5d65-4a68-8e6a-21608ddf7258
82 ff bb d2 78 29 af c0 99 b0 fe 80 62 57 18 ff fe
83 a3 42 29 60 57 18 a3 42 29 10 83 96 36 5d 65 4a
84 68 8e 6a 21 60 8d df 72 58
87 Hexadecimal, decimal, and binary byte constants::
92 aa bb $247 $-89 %0011_0010 %11.01= 10/10
101 UTF-8, UTF-16, and UTF-32 literal strings::
107 u16le"stress\nverdict 🤣"
113 68 65 6c 6c 6f 20 77 6f 72 6c 64 21 00 73 00 74 ┆ hello world!•s•t
114 00 72 00 65 00 73 00 73 00 0a 00 76 00 65 00 72 ┆ •r•e•s•s•••v•e•r
115 00 64 00 69 00 63 00 74 00 20 00 3e d8 23 dd ┆ •d•i•c•t• •>•#•
118 Labels: special variables holding the offset where they're defined::
121 <beg> b2 52 e3 bc 91 05
122 $100 $50 <chair> 33 9f fe
129 5e 65 {tower = 47} c6 7f f2 c4
130 44 {hurl = tower - 14} b5 {tower = hurl} 26 2d
133 The value of a variable assignment is the evaluation of a valid {py3}
134 expression which may include label and variable names.
136 Fixed-length number with a given length (8{nbsp}bits to 64{nbsp}bits) and byte order::
142 {be} 67 <lbl> 44 $178 {(end - lbl) * 8 + strength : 16} $99 <end>
150 67 44 b2 00 2c 63 37 f8 ff ff 7f bd c2 82 fb 21
154 The encoded number is the evaluation of a valid {py3} expression which
155 may include label and variable names.
157 https://en.wikipedia.org/wiki/LEB128[LEB128] integer::
162 aa bb cc {-1993 : sleb128} <meow> dd ee ff
163 {meow * 199 : uleb128}
169 aa bb cc b7 70 dd ee ff e3 07
172 The encoded integer is the evaluation of a valid {py3} expression which
173 may include label and variable names.
180 aa bb * 5 cc <zoom> "yeah\0" * {zoom * 3}
190 aa bb bb bb bb bb cc 79 65 61 68 00 79 65 61 68 ┆ •••••••yeah•yeah
191 00 79 65 61 68 00 79 65 61 68 00 79 65 61 68 00 ┆ •yeah•yeah•yeah•
192 79 65 61 68 00 79 65 61 68 00 79 65 61 68 00 79 ┆ yeah•yeah•yeah•y
193 65 61 68 00 79 65 61 68 00 79 65 61 68 00 79 65 ┆ eah•yeah•yeah•ye
194 61 68 00 79 65 61 68 00 79 65 61 68 00 79 65 61 ┆ ah•yeah•yeah•yea
195 68 00 79 65 61 68 00 79 65 61 68 00 79 65 61 68 ┆ h•yeah•yeah•yeah
196 00 79 65 61 68 00 79 65 61 68 00 79 65 61 68 00 ┆ •yeah•yeah•yeah•
197 ff ee 6a 75 69 63 65 ff ee 6a 75 69 63 65 ff ee ┆ ••juice••juice••
198 6a 75 69 63 65 ┆ juice
217 00 00 00 c7 00 00 00 00 00 00 00 00 00 00 00 2b
218 ff 85 ff ff 00 00 15 d0
221 Multilevel grouping::
226 ff ((aa bb "zoom" cc) * 5) * 3 $-34 * 4
232 ff aa bb 7a 6f 6f 6d cc aa bb 7a 6f 6f 6d cc aa ┆ •••zoom•••zoom••
233 bb 7a 6f 6f 6d cc aa bb 7a 6f 6f 6d cc aa bb 7a ┆ •zoom•••zoom•••z
234 6f 6f 6d cc aa bb 7a 6f 6f 6d cc aa bb 7a 6f 6f ┆ oom•••zoom•••zoo
235 6d cc aa bb 7a 6f 6f 6d cc aa bb 7a 6f 6f 6d cc ┆ m•••zoom•••zoom•
236 aa bb 7a 6f 6f 6d cc aa bb 7a 6f 6f 6d cc aa bb ┆ ••zoom•••zoom•••
237 7a 6f 6f 6d cc aa bb 7a 6f 6f 6d cc aa bb 7a 6f ┆ zoom•••zoom•••zo
238 6f 6d cc aa bb 7a 6f 6f 6d cc de de de de ┆ om•••zoom•••••
241 Precise error reporting::
244 /tmp/meow.normand:10:24 - Expecting a bit (`0` or `1`).
248 /tmp/meow.normand:32:6 - Unexpected character `k`.
252 /tmp/meow.normand:24:19 - Illegal (unknown or unreachable) variable/label name `meow` in expression `(meow - 45) // 8`; the legal names are {`mix`, `zoom`}.
256 /tmp/meow.normand:18:9 - Value 315 is outside the 8-bit range when evaluating expression `end - ICITTE` at byte offset 45.
259 You can use Normand to track data source files in your favorite VCS
260 instead of raw binary files. The binary files that Normand generates can
261 be used to test file format decoding, including malformatted data, for
262 example, as well as for education.
264 See <<learn-normand>> to explore all the Normand features.
268 Normand requires Python ≥ 3.4.
273 $ python3 -m pip install --user normand
277 https://packaging.python.org/en/latest/tutorials/installing-packages/#installing-to-the-user-site[Installing to the User Site]
278 to learn more about a user site installation.
282 Normand has a single module file, `normand.py`, which you can copy as is
283 to your project to use it (both the <<python3-api,`normand.parse()`>>
284 function and the <<command-line-tool,command-line tool>>).
286 `normand.py` has _no external dependencies_, but if you're using
287 Python{nbsp}3.4, you'll need a local copy of the standard `typing`
293 A Normand text input is a sequence of items which represent a sequence
296 [[state]] During the processing of items to data, Normand relies on a
301 |State variable |Description |Initial value: <<python3-api,{py3} API>> |Initial value: <<command-line-tool,CLI>>
303 |[[cur-offset]] Current offset
305 The current offset has an effect on the value of <<label,labels>> and of
306 the special `ICITTE` name in <<fixed-length-number,fixed-length
307 number>>, <<leb-128-integer,LEB128 integer>>, and
308 <<variable-assignment,variable assignment>> expression evaluation.
310 Each generated byte increments the current offset.
312 A <<current-offset-setting,current offset setting>> may change the
313 current offset without generating data.
315 An <<current-offset-alignment,current offset alignment>> generates
316 padding bytes to make the current offset satisfy a given alignment.
317 |`init_offset` parameter of the `parse()` function.
320 |[[cur-bo]] Current byte order
322 The current byte order has an effect on the encoding of
323 <<fixed-length-number,fixed-length numbers>>.
325 A <<current-byte-order-setting,current byte order setting>> may change
326 the current byte order.
327 |`init_byte_order` parameter of the `parse()` function.
328 |`--byte-order` option.
331 |Mapping of label names to integral values.
332 |`init_labels` parameter of the `parse()` function.
333 |One or more `--label` options.
335 |<<variable-assignment,Variables>>
336 |Mapping of variable names to integral values.
337 |`init_variables` parameter of the `parse()` function.
338 |One or more `--var` options.
341 The available items are:
343 * A <<byte-constant,constant integer>> representing a single byte.
345 * A <<literal-string,literal string>> representing a sequence of bytes
346 encoding UTF-8, UTF-16, or UTF-32 data.
348 * A <<current-byte-order-setting,current byte order setting>> (big or
351 * A <<fixed-length-number,fixed-length number>> (integer or
352 floating point) using the <<cur-bo,current byte order>> and of which
353 the value is the result of a {py3} expression.
355 * An <<leb128-integer,LEB128 integer>> of which the value is the result
356 of a {py3} expression.
358 * A <<current-offset-setting,current offset setting>>.
360 * A <<current-offset-alignment,current offset alignment>>.
362 * A <<label,label>>, that is, a named constant holding the current
365 This is similar to an assembly label.
367 * A <<variable-assignment,variable assignment>> associating a name to
368 the integral result of an evaluated {py3} expression.
370 * A <<group,group>>, that is, a scoped sequence of items.
372 * A <<repetition-block,repetition block>>.
374 Moreover, you can repeat many items above a constant or variable number
375 of times with the ``pass:[*]`` operator _after_ the item to repeat. This
376 is called a <<post-item-repetition,post-item repetition>>.
378 A Normand comment may exist:
380 * Between items, possibly within a group.
381 * Between the nibbles of a constant hexadecimal byte.
382 * Between the bits of a constant binary byte.
383 * Between the last item and the ``pass:[*]`` character of a post-item
384 repetition, and between that ``pass:[*]`` character and the following
385 number or expression.
386 * Between the ``!repeat``/``!r`` prefix and the following constant
387 integer, name, or expression of a repetition block.
389 A comment is anything between two ``pass:[#]`` characters on the same
390 line, or from ``pass:[#]`` until the end of the line. Whitespaces and
391 the following symbol characters are also considered comments where a
395 / \ ? & : ; . , + [ ] _ = | -
398 The latter serve to improve readability so that you may write, for
399 example, a MAC address or a UUID as is.
401 You can test the examples of this section with the `normand`
402 <<command-line-tool,command-line tool>> as such:
405 $ normand file | hexdump -C
408 where `file` is the name of a file containing the Normand input.
412 A _byte constant_ represents a single byte.
417 Two consecutive hexits.
420 A decimal number after the `$` prefix.
423 Eight bits after the `%` prefix.
443 $192 %1100/0011 $ -77
457 58f64689-6316-4d55-8a1a-04cada366172
458 fe80::6257:18ff:fea3:4229
464 58 f6 46 89 63 16 4d 55 8a 1a 04 ca da 36 61 72 ┆ X•F•c•MU•••••6ar
465 fe 80 62 57 18 ff fe a3 42 29 ┆ ••bW••••B)
473 %01110011 %01100001 %01101100 %01110101 %01110100
479 73 61 6c 75 74 ┆ salut
485 A _literal string_ represents the UTF-8-, UTF-16-, or UTF-32-encoded
488 The string to encode isn't implicitly null-terminated: use `\0` at the
489 end of the string to add a null character.
493 . **Optional**: one of the following encodings instead of UTF-8:
503 . The ``pass:["]`` prefix.
505 . A sequence of zero or more characters, possibly containing escape
508 An escape sequence is the ``\`` character followed by one of:
514 `b`:: Backspace (U+0008)
515 `e`:: Escape (U+001B)
516 `f`:: Form feed (U+000C)
517 `n`:: End of line (U+000A)
518 `r`:: Carriage return (U+000D)
519 `t`:: Character tabulation (U+0009)
520 `v`:: Line tabulation (U+000B)
521 ``\``:: Reverse solidus (U+005C)
522 ``pass:["]``:: Quotation mark (U+0022)
525 . The ``pass:["]`` suffix.
531 "coucou tout le monde!"
537 63 6f 75 63 6f 75 20 74 6f 75 74 20 6c 65 20 6d ┆ coucou tout le m
538 6f 6e 64 65 21 ┆ onde!
546 u16le"I am not young enough to know everything."
552 49 00 20 00 61 00 6d 00 20 00 6e 00 6f 00 74 00 ┆ I• •a•m• •n•o•t•
553 20 00 79 00 6f 00 75 00 6e 00 67 00 20 00 65 00 ┆ •y•o•u•n•g• •e•
554 6e 00 6f 00 75 00 67 00 68 00 20 00 74 00 6f 00 ┆ n•o•u•g•h• •t•o•
555 20 00 6b 00 6e 00 6f 00 77 00 20 00 65 00 76 00 ┆ •k•n•o•w• •e•v•
556 65 00 72 00 79 00 74 00 68 00 69 00 6e 00 67 00 ┆ e•r•y•t•h•i•n•g•
565 u32be "\"illusion is the first\nof all pleasures\" 🦉"
571 00 00 00 22 00 00 00 69 00 00 00 6c 00 00 00 6c ┆ •••"•••i•••l•••l
572 00 00 00 75 00 00 00 73 00 00 00 69 00 00 00 6f ┆ •••u•••s•••i•••o
573 00 00 00 6e 00 00 00 20 00 00 00 69 00 00 00 73 ┆ •••n••• •••i•••s
574 00 00 00 20 00 00 00 74 00 00 00 68 00 00 00 65 ┆ ••• •••t•••h•••e
575 00 00 00 20 00 00 00 66 00 00 00 69 00 00 00 72 ┆ ••• •••f•••i•••r
576 00 00 00 73 00 00 00 74 00 00 00 0a 00 00 00 6f ┆ •••s•••t•••••••o
577 00 00 00 66 00 00 00 20 00 00 00 61 00 00 00 6c ┆ •••f••• •••a•••l
578 00 00 00 6c 00 00 00 20 00 00 00 70 00 00 00 6c ┆ •••l••• •••p•••l
579 00 00 00 65 00 00 00 61 00 00 00 73 00 00 00 75 ┆ •••e•••a•••s•••u
580 00 00 00 72 00 00 00 65 00 00 00 73 00 00 00 22 ┆ •••r•••e•••s•••"
581 00 00 00 20 00 01 f9 89 ┆ ••• ••••
585 === Current byte order setting
587 This special item sets the <<cur-bo,_current byte order_>>.
589 The two accepted forms are:
592 ``pass:[{be}]``:: Set the current byte order to big endian.
593 ``pass:[{le}]``:: Set the current byte order to little endian.
595 === Fixed-length number
597 A _fixed-length number_ represents a fixed number of bytes encoding
600 * An unsigned or signed integer (two's complement).
602 The available lengths are 8, 16, 24, 32, 40, 48, 56, and 64.
604 * A floating point number
605 ([IEEE{nbsp}754-2008[https://standards.ieee.org/standard/754-2008.html]).
607 The available length are 32 (_binary32_) and 64 (_binary64_).
609 The value is the result of evaluating a {py3} expression using the
610 <<cur-bo,current byte order>>.
612 A fixed-length number is:
614 . The ``pass:[{]`` prefix.
616 . A valid {py3} expression.
618 For a fixed-length number at some source location{nbsp}__**L**__, this
619 expression may contain the name of any accessible <<label,label>> (not
620 within a nested group), including the name of a label defined
621 after{nbsp}__**L**__, as well as the name of any
622 <<variable-assignment,variable>> known at{nbsp}__**L**__.
624 The value of the special name `ICITTE` (`int` type) in this expression
625 is the <<cur-offset,current offset>> (before encoding the number).
629 . An encoding length in bits amongst:
632 The expression evaluates to an `int` value::
633 `8`, `16`, `24`, `32`, `40`, `48`, `56`, and `64`.
635 The expression evaluates to a `float` value::
662 # String length in bits
663 {8 * (str_end - str_beg) : 16}
674 00 60 68 65 6c 6c 6f 20 77 6f 72 6c 64 21 ┆ •`hello world!
682 {20 - ICITTE : 8} * 10
688 14 13 12 11 10 0f 0e 0d 0c 0b
709 An _LEB128 integer_ represents a variable number of bytes encoding an
710 unsigned or signed integer which is the result of evaluating a {py3}
711 expression following the https://en.wikipedia.org/wiki/LEB128[LEB128]
714 An LEB128 integer is:
716 . The ``pass:[{]`` prefix.
718 . A valid {py3} expression.
720 For an LEB128 integer at some source location{nbsp}__**L**__, this
721 expression may contain:
724 * The name of any <<label,label>> defined before{nbsp}__**L**__.
725 * The name of any <<variable-assignment,variable>> known at{nbsp}__**L**__
726 which doesn't, directly or indirectly, refer to a label
727 defined after{nbsp}__**L**__.
730 The value of the special name `ICITTE` (`int` type) in this expression
731 is the <<cur-offset,current offset>> (before encoding the integer).
739 `uleb128`:: Use the unsigned LEB128 format.
740 `sleb128`:: Use the signed LEB128 format.
766 {-981238311 + (meow * -23) : sleb128}
773 aa bb cc dd ee ff fd fa 8d ac 7c 68 65 6c 6c 6f ┆ ••••••••••|hello
777 === Current offset setting
779 This special item sets the <<cur-offset,_current offset_>>.
781 A current offset setting is:
785 . A positive integer (hexadecimal starting with `0x` or `0X` accepted)
786 which is the new current offset.
795 <0x61> {ICITTE : 8} * 8
801 00 01 02 03 04 05 06 07 61 62 63 64 65 66 67 68 ┆ ••••••••abcdefgh
809 aa bb cc dd <meow> ee ff
810 <12> 11 22 33 <mix> 44 55
817 aa bb cc dd ee ff 11 22 33 44 55 04 0f ┆ •••••••"3DU••
821 === Current offset alignment
823 A _current offset alignment_ represents zero or more padding bytes to
824 make the <<cur-offset,current offset>> meet a given
825 https://en.wikipedia.org/wiki/Data_structure_alignment[alignment] value.
827 More specifically, for an alignment value of{nbsp}__**N**__{nbsp}bits,
828 a current offset alignment represents the required padding bytes until
829 the current offset is a multiple of __**N**__{nbsp}/{nbsp}8.
831 A current offset alignment is:
835 . A positive integer (hexadecimal starting with `0x` or `0X` accepted)
836 which is the alignment value in _bits_.
838 This value must be greater than zero and a multiple of{nbsp}8.
843 . The ``pass:[~]`` prefix.
844 . A positive integer (hexadecimal starting with `0x` or `0X` accepted)
845 which is the value of the byte to use as padding to align the
846 <<cur-offset,current offset>>.
849 Without this section, the padding byte value is zero.
855 11 22 (@32 aa bb cc) * 3
861 11 22 00 00 aa bb cc 00 aa bb cc 00 aa bb cc
878 77 88 cc cc 00 60 5f c4 55 55 55 55 55 55 55 55 ┆ w••••`_•UUUUUUUU
887 aa bb cc <29> @64~255 "zoom"
893 aa bb cc ff ff ff 7a 6f 6f 6d ┆ ••••••zoom
899 A _label_ associates a name to the <<cur-offset,current offset>>.
901 All the labels of a whole Normand input must have unique names.
903 A label must not share the name of a <<variable-assignment,variable>>
910 . A valid {py3} name which is not `ICITTE` (see
911 <<fixed-length-number>>, <<leb128-integer>>, and
912 <<variable-assignment>> to learn more).
916 === Variable assignment
918 A _variable assignment_ associates a name to the integral result of an
919 evaluated {py3} expression.
921 A variable assignment is:
923 . The ``pass:[{]`` prefix.
925 . A valid {py3} name which is not `ICITTE` (see
926 <<fixed-length-number>>, <<leb128-integer>>, and
927 <<variable-assignment>> to learn more).
931 . A valid {py3} expression.
933 For a variable assignment at some source location{nbsp}__**L**__, this
934 expression may contain the name of any accessible <<label,label>> (not
935 within a nested group), including the name of a label defined
936 after{nbsp}__**L**__, as well as the name of any
937 <<variable-assignment,variable>> known at{nbsp}__**L**__.
939 The value of the special name `ICITTE` (`int` type) in this expression
940 is the <<cur-offset,current offset>>.
949 {meow = 42} 11 22 {meow:8} 33 {meow = ICITTE + 17}
950 "yooo" {meow + mix : 16}
956 11 22 2a 33 79 6f 6f 6f 7a 00 ┆ •"*3yoooz•
962 A _group_ is a scoped sequence of items.
964 The <<label,labels>> within a group aren't visible outside of it.
966 The main purpose of a group is to <<post-item-repetition,repeat>> more
967 than a single item and to isolate labels.
973 . Zero or more items.
981 ((aa bb cc) dd () ee) "leclerc"
987 aa bb cc dd ee 6c 65 63 6c 65 72 63 ┆ •••••leclerc
995 ((aa bb cc) * 3 dd ee) * 5
1001 aa bb cc aa bb cc aa bb cc dd ee aa bb cc aa bb
1002 cc aa bb cc dd ee aa bb cc aa bb cc aa bb cc dd
1003 ee aa bb cc aa bb cc aa bb cc dd ee aa bb cc aa
1004 bb cc aa bb cc dd ee
1014 <str_beg> u16le"sébastien diaz" <str_end>
1015 {ICITTE - str_beg : 8}
1016 {(end - str_beg) * 5 : 24}
1024 73 00 e9 00 62 00 61 00 73 00 74 00 69 00 65 00 ┆ s•••b•a•s•t•i•e•
1025 6e 00 20 00 64 00 69 00 61 00 7a 00 1c 00 01 e0 ┆ n• •d•i•a•z•••••
1026 73 00 e9 00 62 00 61 00 73 00 74 00 69 00 65 00 ┆ s•••b•a•s•t•i•e•
1027 6e 00 20 00 64 00 69 00 61 00 7a 00 1c 00 01 40 ┆ n• •d•i•a•z••••@
1028 73 00 e9 00 62 00 61 00 73 00 74 00 69 00 65 00 ┆ s•••b•a•s•t•i•e•
1029 6e 00 20 00 64 00 69 00 61 00 7a 00 1c 00 00 a0 ┆ n• •d•i•a•z•••••
1033 === Repetition block
1035 A _repetition block_ represents the bytes of one or more items repeated
1036 a given number of times.
1038 A repetition block is:
1040 . The `!repeat` or `!r` prefix.
1044 ** A positive integer (hexadecimal starting with `0x` or `0X` accepted)
1045 which is the number of times to repeat the previous item.
1047 ** The ``pass:[{]`` prefix, a valid {py3} expression, and the
1048 ``pass:[}]`` suffix.
1050 For a repetition at some source location{nbsp}__**L**__, this expression
1054 * The name of any <<label,label>> defined before{nbsp}__**L**__.
1055 * The name of any <<variable-assignment,variable>> known
1056 at{nbsp}__**L**__ which doesn't, directly or indirectly, refer to a
1057 label defined after{nbsp}__**L**__.
1060 The value of the special name `ICITTE` (`int` type) in this expression
1061 is the <<cur-offset,current offset>> (before handling the items to
1064 ** A valid {py3} name.
1066 For the name `__NAME__`, this is equivalent to the
1067 `pass:[{]__NAME__pass:[}]` form above.
1069 . Zero or more items.
1071 . The `!end` suffix.
1073 You may also use a <<post-item-repetition,post-item repetition>> after
1074 some items. The form ``!repeat{nbsp}__X__{nbsp}__ITEMS__{nbsp}!end``
1075 is equivalent to ``(__ITEMS__){nbsp}pass:[*]{nbsp}__X__``.
1082 {end - ICITTE - 1 : 8}
1091 ff fe fd fc fb fa f9 f8 f7 f6 f5 f4 f3 f2 f1 f0 ┆ ••••••••••••••••
1092 ef ee ed ec eb ea e9 e8 e7 e6 e5 e4 e3 e2 e1 e0 ┆ ••••••••••••••••
1093 df de dd dc db da d9 d8 d7 d6 d5 d4 d3 d2 d1 d0 ┆ ••••••••••••••••
1094 cf ce cd cc cb ca c9 c8 c7 c6 c5 c4 c3 c2 c1 c0 ┆ ••••••••••••••••
1095 bf be bd bc bb ba b9 b8 b7 b6 b5 b4 b3 b2 b1 b0 ┆ ••••••••••••••••
1096 af ae ad ac ab aa a9 a8 a7 a6 a5 a4 a3 a2 a1 a0 ┆ ••••••••••••••••
1097 9f 9e 9d 9c 9b 9a 99 98 97 96 95 94 93 92 91 90 ┆ ••••••••••••••••
1098 8f 8e 8d 8c 8b 8a 89 88 87 86 85 84 83 82 81 80 ┆ ••••••••••••••••
1099 7f 7e 7d 7c 7b 7a 79 78 77 76 75 74 73 72 71 70 ┆ •~}|{zyxwvutsrqp
1100 6f 6e 6d 6c 6b 6a 69 68 67 66 65 64 63 62 61 60 ┆ onmlkjihgfedcba`
1101 5f 5e 5d 5c 5b 5a 59 58 57 56 55 54 53 52 51 50 ┆ _^]\[ZYXWVUTSRQP
1102 4f 4e 4d 4c 4b 4a 49 48 47 46 45 44 43 42 41 40 ┆ ONMLKJIHGFEDCBA@
1103 3f 3e 3d 3c 3b 3a 39 38 37 36 35 34 33 32 31 30 ┆ ?>=<;:9876543210
1104 2f 2e 2d 2c 2b 2a 29 28 27 26 25 24 23 22 21 20 ┆ /.-,+*)('&%$#"!
1105 1f 1e 1d 1c 1b 1a 19 18 17 16 15 14 13 12 11 10 ┆ ••••••••••••••••
1106 0f 0e 0d 0c 0b 0a 09 08 07 06 05 04 03 02 01 00 ┆ ••••••••••••••••
1125 11 22 !repeat times 33 !end
1136 aa bb cc dd ee ff ee ff ee ff ee ff ee ff 11 22 ┆ •••••••••••••••"
1137 33 ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ 3•••••••••••••••
1138 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1139 ff ee ff ee ff 11 22 33 33 ee ff ee ff ee ff ee ┆ ••••••"33•••••••
1140 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1141 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1142 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1143 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1144 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1145 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1146 ff ee ff ee ff ee ff ee ff ee ff ee ff 11 22 33 ┆ ••••••••••••••"3
1147 33 33 63 6f 75 63 6f 75 21 ┆ 33coucou!
1152 This example shows how to use a repetition block as a conditional
1153 section depending on some predefined variable.
1167 Output (`cond` is 0):
1173 Output (`cond` is 1):
1176 aa bb cc dd ee ff 6d 65 6f 77 20 6d 69 78 00 f8 ┆ ••••••meow mix••
1181 === Post-item repetition
1183 A _post-item repetition_ represents the bytes of an item repeated a
1184 given number of times.
1186 A post-item repetition is:
1190 ** A <<current-byte-order-setting,current byte order setting>>.
1191 ** A <<current-offset-setting,current offset setting>>.
1192 ** A <<label,label>>.
1193 ** A <<offset-alignment,offset alignment>>.
1194 ** A <<variable-assignment,variable assignment>>.
1195 ** A <<repetition-block,repetition block>>.
1197 . The ``pass:[*]`` character.
1201 ** A positive integer (hexadecimal starting with `0x` or `0X` accepted)
1202 which is the number of times to repeat the previous item.
1204 ** The ``pass:[{]`` prefix, a valid {py3} expression, and the
1205 ``pass:[}]`` suffix.
1207 For a repetition at some source location{nbsp}__**L**__, this expression
1211 * The name of any <<label,label>> defined before{nbsp}__**L**__ and
1212 which isn't part of its repeated item.
1213 * The name of any <<variable-assignment,variable>> known
1214 at{nbsp}__**L**__, which isn't part of its repeated item, and which
1215 doesn't, directly or indirectly, refer to a label defined
1216 after{nbsp}__**L**__.
1219 The value of the special name `ICITTE` (`int` type) in this expression
1220 is the <<cur-offset,current offset>> (before handling the items to
1223 ** A valid {py3} name.
1225 For the name `__NAME__`, this is equivalent to the
1226 `pass:[{]__NAME__pass:[}]` form above.
1228 You may also use a <<repetition-block,repetition block>>. The form
1229 ``__ITEM__{nbsp}pass:[*]{nbsp}__X__`` is equivalent to
1230 ``!repeat{nbsp}__X__{nbsp}__ITEM__{nbsp}!end``.
1236 {end - ICITTE - 1 : 8} * 0x100 <end>
1242 ff fe fd fc fb fa f9 f8 f7 f6 f5 f4 f3 f2 f1 f0 ┆ ••••••••••••••••
1243 ef ee ed ec eb ea e9 e8 e7 e6 e5 e4 e3 e2 e1 e0 ┆ ••••••••••••••••
1244 df de dd dc db da d9 d8 d7 d6 d5 d4 d3 d2 d1 d0 ┆ ••••••••••••••••
1245 cf ce cd cc cb ca c9 c8 c7 c6 c5 c4 c3 c2 c1 c0 ┆ ••••••••••••••••
1246 bf be bd bc bb ba b9 b8 b7 b6 b5 b4 b3 b2 b1 b0 ┆ ••••••••••••••••
1247 af ae ad ac ab aa a9 a8 a7 a6 a5 a4 a3 a2 a1 a0 ┆ ••••••••••••••••
1248 9f 9e 9d 9c 9b 9a 99 98 97 96 95 94 93 92 91 90 ┆ ••••••••••••••••
1249 8f 8e 8d 8c 8b 8a 89 88 87 86 85 84 83 82 81 80 ┆ ••••••••••••••••
1250 7f 7e 7d 7c 7b 7a 79 78 77 76 75 74 73 72 71 70 ┆ •~}|{zyxwvutsrqp
1251 6f 6e 6d 6c 6b 6a 69 68 67 66 65 64 63 62 61 60 ┆ onmlkjihgfedcba`
1252 5f 5e 5d 5c 5b 5a 59 58 57 56 55 54 53 52 51 50 ┆ _^]\[ZYXWVUTSRQP
1253 4f 4e 4d 4c 4b 4a 49 48 47 46 45 44 43 42 41 40 ┆ ONMLKJIHGFEDCBA@
1254 3f 3e 3d 3c 3b 3a 39 38 37 36 35 34 33 32 31 30 ┆ ?>=<;:9876543210
1255 2f 2e 2d 2c 2b 2a 29 28 27 26 25 24 23 22 21 20 ┆ /.-,+*)('&%$#"!
1256 1f 1e 1d 1c 1b 1a 19 18 17 16 15 14 13 12 11 10 ┆ ••••••••••••••••
1257 0f 0e 0d 0c 0b 0a 09 08 07 06 05 04 03 02 01 00 ┆ ••••••••••••••••
1269 (ee ff) * {here + 1}
1279 aa bb cc dd ee ff ee ff ee ff ee ff ee ff 11 22 ┆ •••••••••••••••"
1280 33 ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ 3•••••••••••••••
1281 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1282 ff ee ff ee ff 11 22 33 33 ee ff ee ff ee ff ee ┆ ••••••"33•••••••
1283 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1284 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1285 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1286 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1287 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1288 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1289 ff ee ff ee ff ee ff ee ff ee ff ee ff 11 22 33 ┆ ••••••••••••••"3
1290 33 33 63 6f 75 63 6f 75 21 ┆ 33coucou!
1294 == Command-line tool
1296 If you <<install-normand,installed>> the `normand` package, then you
1297 can use the `normand` command-line tool:
1300 $ normand <<< '"ma gang de malades"' | hexdump -C
1304 00000000 6d 61 20 67 61 6e 67 20 64 65 20 6d 61 6c 61 64 |ma gang de malad|
1308 If you copy the `normand.py` module to your own project, then you can
1309 run the module itself:
1312 $ python3 -m normand <<< '"ma gang de malades"' | hexdump -C
1316 00000000 6d 61 20 67 61 6e 67 20 64 65 20 6d 61 6c 61 64 |ma gang de malad|
1320 Without a path argument, the `normand` tool reads from the standard
1323 The `normand` tool prints the generated binary data to the standard
1326 Various options control the initial <<state,state>> of the processor:
1327 use the `--help` option to learn more.
1331 The whole `normand` package/module public API is:
1336 class ByteOrder(enum.Enum):
1348 def line_no(self) -> int:
1353 def col_no(self) -> int:
1358 class ParseError(RuntimeError):
1359 # Source text location.
1361 def text_loc(self) -> TextLocation:
1365 # Variables dictionary type (for type hints).
1366 VariablesT = typing.Dict[str, typing.Union[int, float]]
1369 # Labels dictionary type (for type hints).
1370 LabelsT = typing.Dict[str, int]
1377 def data(self) -> bytearray:
1380 # Updated variable values.
1382 def variables(self) -> SymbolsT:
1385 # Updated main group label values.
1387 def labels(self) -> SymbolsT:
1392 def offset(self) -> int:
1397 def byte_order(self) -> typing.Optional[ByteOrder]:
1401 # Parses the `normand` input using the initial state defined by
1402 # `init_variables`, `init_labels`, `init_offset`, and `init_byte_order`,
1403 # and returns the corresponding parsing result.
1404 def parse(normand: str,
1405 init_variables: typing.Optional[SymbolsT] = None,
1406 init_labels: typing.Optional[SymbolsT] = None,
1407 init_offset: int = 0,
1408 init_byte_order: typing.Optional[ByteOrder] = None) -> ParseResult:
1412 The `normand` parameter is the actual <<learn-normand,Normand input>>
1413 while the other parameters control the initial <<state,state>>.
1415 The `parse()` function raises a `ParseError` instance should it fail to
1416 parse the `normand` string for any reason.
1420 Normand is a https://python-poetry.org/[Poetry] project.
1422 To develop it, install it through Poetry and enter the virtual
1428 $ normand <<< '"lol" * 10 0a'
1431 `normand.py` is processed by:
1433 * https://microsoft.github.io/pyright/[Pyright]
1434 * https://github.com/psf/black[Black]
1435 * https://pycqa.github.io/isort/[isort]
1439 Use https://docs.pytest.org/[pytest] to test Normand once the package is
1440 part of your virtual environment, for example:
1444 $ poetry run pip3 install pytest
1448 The `pytest` project is currently not a development dependency in
1449 `pyproject.toml` due to backward compatibiliy issues with
1452 In the `tests` directory, each `*.nt` file is a test. The file name
1453 prefix indicates what it's meant to test:
1456 Everything above the `---` line is the valid Normand input
1459 Everything below the `---` line is the expected data
1460 (whitespace-separated hexadecimal bytes).
1463 Everything above the `---` line is the invalid Normand input
1466 Everything below the `---` line is the expected error message having
1475 Normand uses https://review.lttng.org/admin/repos/normand,general[Gerrit]
1478 To report a bug, https://github.com/efficios/normand/issues/new[create a