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.18, 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.
196 aa bb cc 66 6f 6f 66 69 67 68 74 66 6f 6f 66 69 ┆ •••foofightfoofi
197 67 68 74 66 6f 6f 62 61 72 66 6f 6f 62 61 72 ┆ ghtfoobarfoobar
205 aa bb * 5 cc <zoom> "yeah\0" * {zoom * 3}
215 aa bb bb bb bb bb cc 79 65 61 68 00 79 65 61 68 ┆ •••••••yeah•yeah
216 00 79 65 61 68 00 79 65 61 68 00 79 65 61 68 00 ┆ •yeah•yeah•yeah•
217 79 65 61 68 00 79 65 61 68 00 79 65 61 68 00 79 ┆ yeah•yeah•yeah•y
218 65 61 68 00 79 65 61 68 00 79 65 61 68 00 79 65 ┆ eah•yeah•yeah•ye
219 61 68 00 79 65 61 68 00 79 65 61 68 00 79 65 61 ┆ ah•yeah•yeah•yea
220 68 00 79 65 61 68 00 79 65 61 68 00 79 65 61 68 ┆ h•yeah•yeah•yeah
221 00 79 65 61 68 00 79 65 61 68 00 79 65 61 68 00 ┆ •yeah•yeah•yeah•
222 ff ee 6a 75 69 63 65 ff ee 6a 75 69 63 65 ff ee ┆ ••juice••juice••
223 6a 75 69 63 65 ┆ juice
242 00 00 00 c7 00 00 00 00 00 00 00 00 00 00 00 2b
243 ff 85 ff ff 00 00 15 d0
265 ef be ad de 37 f8 09 00 00 00 00 00 00 00 00 00 ┆ ••••7•••••••••••
266 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ┆ ••••••••••••••••
267 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ┆ ••••••••••••••••
268 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ┆ ••••••••••••••••
269 40 6d 65 6f 77 20 6d 69 78 ff ff ff ff ff ff ff ┆ @meow mix•••••••
270 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ┆ ••••••••••••••••
271 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ┆ ••••••••••••••••
272 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ┆ ••••••••••••••••
273 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ┆ ••••••••••••••••
274 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ┆ ••••••••••••••••
275 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ┆ ••••••••••••••••
276 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ┆ ••••••••••••••••
277 ff ff ff ff ff ff ff ff c8 ┆ •••••••••
280 Multilevel grouping::
285 ff ((aa bb "zoom" cc) * 5) * 3 $-34 * 4
291 ff aa bb 7a 6f 6f 6d cc aa bb 7a 6f 6f 6d cc aa ┆ •••zoom•••zoom••
292 bb 7a 6f 6f 6d cc aa bb 7a 6f 6f 6d cc aa bb 7a ┆ •zoom•••zoom•••z
293 6f 6f 6d cc aa bb 7a 6f 6f 6d cc aa bb 7a 6f 6f ┆ oom•••zoom•••zoo
294 6d cc aa bb 7a 6f 6f 6d cc aa bb 7a 6f 6f 6d cc ┆ m•••zoom•••zoom•
295 aa bb 7a 6f 6f 6d cc aa bb 7a 6f 6f 6d cc aa bb ┆ ••zoom•••zoom•••
296 7a 6f 6f 6d cc aa bb 7a 6f 6f 6d cc aa bb 7a 6f ┆ zoom•••zoom•••zo
297 6f 6d cc aa bb 7a 6f 6f 6d cc de de de de ┆ om•••zoom•••••
307 !if world " world" !end
312 m:hello({ICITTE > 15 and ICITTE < 60})
319 ff ff ff ff 68 65 6c 6c 6f ff ff ff ff 68 65 6c ┆ ••••hello••••hel
320 6c 6f ff ff ff ff 68 65 6c 6c 6f 20 77 6f 72 6c ┆ lo••••hello worl
321 64 ff ff ff ff 68 65 6c 6c 6f 20 77 6f 72 6c 64 ┆ d••••hello world
322 ff ff ff ff 68 65 6c 6c 6f 20 77 6f 72 6c 64 ff ┆ ••••hello world•
323 ff ff ff 68 65 6c 6c 6f ff ff ff ff 68 65 6c 6c ┆ •••hello••••hell
324 6f ff ff ff ff 68 65 6c 6c 6f ff ff ff ff 68 65 ┆ o••••hello••••he
325 6c 6c 6f ff ff ff ff 68 65 6c 6c 6f ff ff ff ff ┆ llo••••hello••••
326 68 65 6c 6c 6f ff ff ff ff 68 65 6c 6c 6f ff ff ┆ hello••••hello••
327 ff ff 68 65 6c 6c 6f ff ff ff ff 68 65 6c 6c 6f ┆ ••hello••••hello
328 ff ff ff ff 68 65 6c 6c 6f ff ff ff ff 68 65 6c ┆ ••••hello••••hel
329 6c 6f ff ff ff ff 68 65 6c 6c 6f ┆ lo••••hello
332 Precise error reporting::
335 /tmp/meow.normand:10:24 - Expecting a bit (`0` or `1`).
339 /tmp/meow.normand:32:6 - Unexpected character `k`.
343 /tmp/meow.normand:24:19 - Illegal (unknown or unreachable) variable/label name `meow` in expression `(meow - 45) // 8`; the legal names are {`ICITTE`, `mix`, `zoom`}.
347 /tmp/meow.normand:32:19 - While expanding the macro `meow`:
348 /tmp/meow.normand:35:5 - While expanding the macro `zzz`:
349 /tmp/meow.normand:18:9 - Value 315 is outside the 8-bit range when evaluating expression `end - ICITTE`.
352 You can use Normand to track data source files in your favorite VCS
353 instead of raw binary files. The binary files that Normand generates can
354 be used to test file format decoding, including malformatted data, for
355 example, as well as for education.
357 See <<learn-normand>> to explore all the Normand features.
361 Normand requires Python ≥ 3.4.
366 $ python3 -m pip install --user normand
370 https://packaging.python.org/en/latest/tutorials/installing-packages/#installing-to-the-user-site[Installing to the User Site]
371 to learn more about a user site installation.
375 Normand has a single module file, `normand.py`, which you can copy as is
376 to your project to use it (both the <<python3-api,`normand.parse()`>>
377 function and the <<command-line-tool,command-line tool>>).
379 `normand.py` has _no external dependencies_, but if you're using
380 Python{nbsp}3.4, you'll need a local copy of the standard `typing`
386 The design goals of Normand are:
389 We're making sure `normand.py` works with Python{nbsp}≥{nbsp}3.4 and
390 doesn't have any external dependencies so that you may just copy the
391 module as is to your own project.
394 The most basic Normand input is a sequence of hexadecimal constants
395 (for example, `4e6f726d616e64`) which produce exactly what you'd
398 Most Normand features map to programming language concepts you already
399 know and understand: constant integers, literal strings, variables,
400 conditionals, repetitions/loops, and the rest.
402 Concise and readable input::
403 We could have chosen XML or YAML as the input format, but having a
404 DSL here makes a Normand input compact and easy to read, two
405 important traits when using Normand to write tests, for example.
407 Compare the following Normand input and some hypothetical XML
408 equivalent, for example:
410 .Actual normand input.
412 ff dd 01 ab $192 $-128 %1101:0011
419 # five times because xyz
421 "hello world " {iter:8}
429 .Hypothetical Normand XML input.
432 <?xml version="1.0" encoding="utf-8" ?>
434 <byte base="x" val="ff" />
435 <byte base="x" val="dd" />
436 <byte base="x" val="1" />
437 <byte base="x" val="ab" />
438 <byte base="d" val="192" />
439 <byte base="d" val="-128" />
440 <byte base="b" val="11010011" />
441 <fixed-len-num expr="end" len="8" />
442 <var-assign name="iter" expr="1" />
443 <cond expr="not something">
444 <!-- five times because xyz -->
446 <str>hello world </str>
447 <fixed-len-num expr="iter" len="8" />
448 <var-assign name="iter" expr="iter + 1" />
457 A Normand text input is a sequence of items which represent a sequence
460 [[state]] During the processing of items to data, Normand relies on a
465 |State variable |Description |Initial value: <<python3-api,{py3} API>> |Initial value: <<command-line-tool,CLI>>
467 |[[cur-offset]] Current offset
469 The current offset has an effect on the value of <<label,labels>> and of
470 the special `ICITTE` name in <<fixed-length-number,fixed-length
471 number>>, <<leb-128-integer,LEB128 integer>>,
472 <<filling,filling>>, <<variable-assignment,variable assignment>>,
473 <<conditional-block,conditional block>>, <<repetition-block,repetition
474 block>>, <<macro-expansion,macro expansion>>, and
475 <<post-item-repetition,post-item repetition>> expression evaluation.
477 Each generated byte increments the current offset.
479 A <<current-offset-setting,current offset setting>> may change the
480 current offset without generating data.
482 An <<current-offset-alignment,current offset alignment>> generates
483 padding bytes to make the current offset satisfy a given alignment.
484 |`init_offset` parameter of the `parse()` function.
487 |[[cur-bo]] Current byte order
489 The current byte order has an effect on the encoding of
490 <<fixed-length-number,fixed-length numbers>>.
492 A <<current-byte-order-setting,current byte order setting>> may change
493 the current byte order.
494 |`init_byte_order` parameter of the `parse()` function.
495 |`--byte-order` option.
498 |Mapping of label names to integral values.
499 |`init_labels` parameter of the `parse()` function.
500 |One or more `--label` options.
502 |<<variable-assignment,Variables>>
503 |Mapping of variable names to integral or floating point number values.
504 |`init_variables` parameter of the `parse()` function.
505 |One or more `--var` options.
508 The available items are:
510 * A <<byte-constant,constant integer>> representing one or more
513 * A <<literal-string,literal string>> representing a sequence of bytes
514 encoding UTF-8, UTF-16, or UTF-32 data.
516 * A <<current-byte-order-setting,current byte order setting>> (big or
519 * A <<fixed-length-number,fixed-length number>> (integer or
520 floating point) using the <<cur-bo,current byte order>> and of which
521 the value is the result of a {py3} expression.
523 * An <<leb128-integer,LEB128 integer>> of which the value is the result
524 of a {py3} expression.
526 * A <<current-offset-setting,current offset setting>>.
528 * A <<current-offset-alignment,current offset alignment>>.
530 * A <<filling,filling>>.
532 * A <<label,label>>, that is, a named constant holding the current
535 This is similar to an assembly label.
537 * A <<variable-assignment,variable assignment>> associating a name to
538 the integral result of an evaluated {py3} expression.
540 * A <<group,group>>, that is, a scoped sequence of items.
542 * A <<conditional-block,conditional block>>.
544 * A <<repetition-block,repetition block>>.
546 * A <<macro-definition-block,macro definition block>>.
548 * A <<macro-expansion,macro expansion>>.
550 Moreover, you can repeat many items above a constant or variable number
551 of times with the ``pass:[*]`` operator _after_ the item to repeat. This
552 is called a <<post-item-repetition,post-item repetition>>.
554 A Normand comment may exist:
556 * Between items, possibly within a group.
557 * Between the nibbles of a constant hexadecimal byte.
558 * Between the bits of a constant binary byte.
559 * Between the last item and the ``pass:[*]`` character of a post-item
560 repetition, and between that ``pass:[*]`` character and the following
561 number or expression.
562 * Between the ``!repeat``/``!r`` block opening and the following
563 constant integer, name, or expression of a repetition block.
564 * Between the ``!if`` block opening and the following name or expression
565 of a conditional block.
567 A comment is anything between two ``pass:[#]`` characters on the same
568 line, or from ``pass:[#]`` until the end of the line. Whitespaces and
569 the following symbol characters are also considered comments where a
573 / \ ? & : ; . , [ ] _ = | -
576 The latter serve to improve readability so that you may write, for
577 example, a MAC address or a UUID as is.
579 [[const-int]] Many items require a _constant integer_, possibly
580 negative, in which case it may start with `-` for a negative integer. A
581 positive constant integer is any of:
584 One or mode digits (`0` to `9`).
589 * The `0x` or `0X` prefix followed with one or more hexadecimal digits
590 (`0` to `9`, `a` to `f`, or `A` to `F`).
591 * One or more hexadecimal digits followed with the `h` or `H` suffix.
596 * The `0o` or `0O` prefix followed with one or more octal digits
598 * One or more octal digits followed with the `o`, `O`, `q`, or `Q`
604 * The `0b` or `0B` prefix followed with one or more bits (`0` or `1`).
605 * One or more bits followed with the `b` or `B` suffix.
607 You can test the examples of this section with the `normand`
608 <<command-line-tool,command-line tool>> as such:
611 $ normand file | hexdump -C
614 where `file` is the name of a file containing the Normand input.
618 A _byte constant_ represents one or more constant bytes.
623 Two consecutive hexadecimal digits representing a single byte.
626 One or more digits after the `$` prefix representing a single byte.
628 Binary form:: {empty}
631 . __**N**__ `%` prefixes (at least one).
633 The number of `%` characters is the number of subsequent expected bytes.
635 . __**N**__{nbsp}×{nbsp}8 bits (`0` or `1`).
656 $192 %1100/0011 $ -77
670 58f64689-6316-4d55-8a1a-04cada366172
671 fe80::6257:18ff:fea3:4229
677 58 f6 46 89 63 16 4d 55 8a 1a 04 ca da 36 61 72 ┆ X•F•c•MU•••••6ar
678 fe 80 62 57 18 ff fe a3 42 29 ┆ ••bW••••B)
686 %01110011 %01100001 %01101100 %01110101 %01110100
687 %%%1101:0010 11111111 #A#11 #B#00 #C#011 #D#1
693 73 61 6c 75 74 d2 ff c7 ┆ salut•••
699 A _literal string_ represents the UTF-8-, UTF-16-, or UTF-32-encoded
702 The string to encode isn't implicitly null-terminated: use `\0` at the
703 end of the string to add a null character.
707 . **Optional**: one of the following encodings instead of UTF-8:
717 . The ``pass:["]`` prefix.
719 . A sequence of zero or more characters, possibly containing escape
722 An escape sequence is the ``\`` character followed by one of:
728 `b`:: Backspace (U+0008)
729 `e`:: Escape (U+001B)
730 `f`:: Form feed (U+000C)
731 `n`:: End of line (U+000A)
732 `r`:: Carriage return (U+000D)
733 `t`:: Character tabulation (U+0009)
734 `v`:: Line tabulation (U+000B)
735 ``\``:: Reverse solidus (U+005C)
736 ``pass:["]``:: Quotation mark (U+0022)
739 . The ``pass:["]`` suffix.
745 "coucou tout le monde!"
751 63 6f 75 63 6f 75 20 74 6f 75 74 20 6c 65 20 6d ┆ coucou tout le m
752 6f 6e 64 65 21 ┆ onde!
760 u16le"I am not young enough to know everything."
766 49 00 20 00 61 00 6d 00 20 00 6e 00 6f 00 74 00 ┆ I• •a•m• •n•o•t•
767 20 00 79 00 6f 00 75 00 6e 00 67 00 20 00 65 00 ┆ •y•o•u•n•g• •e•
768 6e 00 6f 00 75 00 67 00 68 00 20 00 74 00 6f 00 ┆ n•o•u•g•h• •t•o•
769 20 00 6b 00 6e 00 6f 00 77 00 20 00 65 00 76 00 ┆ •k•n•o•w• •e•v•
770 65 00 72 00 79 00 74 00 68 00 69 00 6e 00 67 00 ┆ e•r•y•t•h•i•n•g•
779 u32be "\"illusion is the first\nof all pleasures\" 🦉"
785 00 00 00 22 00 00 00 69 00 00 00 6c 00 00 00 6c ┆ •••"•••i•••l•••l
786 00 00 00 75 00 00 00 73 00 00 00 69 00 00 00 6f ┆ •••u•••s•••i•••o
787 00 00 00 6e 00 00 00 20 00 00 00 69 00 00 00 73 ┆ •••n••• •••i•••s
788 00 00 00 20 00 00 00 74 00 00 00 68 00 00 00 65 ┆ ••• •••t•••h•••e
789 00 00 00 20 00 00 00 66 00 00 00 69 00 00 00 72 ┆ ••• •••f•••i•••r
790 00 00 00 73 00 00 00 74 00 00 00 0a 00 00 00 6f ┆ •••s•••t•••••••o
791 00 00 00 66 00 00 00 20 00 00 00 61 00 00 00 6c ┆ •••f••• •••a•••l
792 00 00 00 6c 00 00 00 20 00 00 00 70 00 00 00 6c ┆ •••l••• •••p•••l
793 00 00 00 65 00 00 00 61 00 00 00 73 00 00 00 75 ┆ •••e•••a•••s•••u
794 00 00 00 72 00 00 00 65 00 00 00 73 00 00 00 22 ┆ •••r•••e•••s•••"
795 00 00 00 20 00 01 f9 89 ┆ ••• ••••
799 === Current byte order setting
801 This special item sets the <<cur-bo,_current byte order_>>.
803 The two accepted forms are:
806 ``pass:[{be}]``:: Set the current byte order to big endian.
807 ``pass:[{le}]``:: Set the current byte order to little endian.
809 === Fixed-length number
811 A _fixed-length number_ represents a fixed number of bytes encoding
814 * An unsigned or signed integer (two's complement).
816 The available lengths are 8, 16, 24, 32, 40, 48, 56, and 64.
818 * A floating point number
819 (https://standards.ieee.org/standard/754-2008.html[IEEE{nbsp}754-2008]).
821 The available length are 32 (_binary32_) and 64 (_binary64_).
823 The value is the result of evaluating a {py3} expression using the
824 <<cur-bo,current byte order>>.
826 A fixed-length number is:
828 . The ``pass:[{]`` prefix.
830 . A valid {py3} expression.
832 For a fixed-length number at some source location{nbsp}__**L**__, this
833 expression may contain the name of any accessible <<label,label>> (not
834 within a nested group), including the name of a label defined
835 after{nbsp}__**L**__, as well as the name of any
836 <<variable-assignment,variable>> known at{nbsp}__**L**__.
838 The value of the special name `ICITTE` (`int` type) in this expression
839 is the <<cur-offset,current offset>> (before encoding the number).
843 . An encoding length in bits amongst:
846 The expression evaluates to an `int` or `bool` value::
847 `8`, `16`, `24`, `32`, `40`, `48`, `56`, and `64`.
849 NOTE: Normand automatically converts a `bool` value to `int`.
851 The expression evaluates to a `float` value::
878 # String length in bits
879 {8 * (str_end - str_beg) : 16}
890 00 60 68 65 6c 6c 6f 20 77 6f 72 6c 64 21 ┆ •`hello world!
898 {20 - ICITTE : 8} * 10
904 14 13 12 11 10 0f 0e 0d 0c 0b
925 An _LEB128 integer_ represents a variable number of bytes encoding an
926 unsigned or signed integer which is the result of evaluating a {py3}
927 expression following the https://en.wikipedia.org/wiki/LEB128[LEB128]
930 An LEB128 integer is:
932 . The ``pass:[{]`` prefix.
934 . A valid {py3} expression of which the evaluation result type
935 is `int` or `bool` (automatically converted to `int`).
937 For an LEB128 integer at some source location{nbsp}__**L**__, this
938 expression may contain:
941 * The name of any <<label,label>> defined before{nbsp}__**L**__
942 which isn't within a nested group.
943 * The name of any <<variable-assignment,variable>> known
947 The value of the special name `ICITTE` (`int` type) in this expression
948 is the <<cur-offset,current offset>> (before encoding the integer).
956 `uleb128`:: Use the unsigned LEB128 format.
957 `sleb128`:: Use the signed LEB128 format.
983 {-981238311 + (meow * -23) : sleb128}
990 aa bb cc dd ee ff fd fa 8d ac 7c 68 65 6c 6c 6f ┆ ••••••••••|hello
994 === Current offset setting
996 This special item sets the <<cur-offset,_current offset_>>.
998 A current offset setting is:
1002 . A <<const-int,positive constant integer>> which is the new current
1012 <0x61> {ICITTE : 8} * 8
1018 00 01 02 03 04 05 06 07 61 62 63 64 65 66 67 68 ┆ ••••••••abcdefgh
1026 aa bb cc dd <meow> ee ff
1027 <12> 11 22 33 <mix> 44 55
1028 {meow : 8} {mix : 8}
1034 aa bb cc dd ee ff 11 22 33 44 55 04 0f ┆ •••••••"3DU••
1038 === Current offset alignment
1040 A _current offset alignment_ represents zero or more padding bytes to
1041 make the <<cur-offset,current offset>> meet a given
1042 https://en.wikipedia.org/wiki/Data_structure_alignment[alignment] value.
1044 More specifically, for an alignment value of{nbsp}__**N**__{nbsp}bits,
1045 a current offset alignment represents the required padding bytes until
1046 the current offset is a multiple of __**N**__{nbsp}/{nbsp}8.
1048 A current offset alignment is:
1052 . A <<const-int,positive constant integer>> which is the alignment value
1055 This value must be greater than zero and a multiple of{nbsp}8.
1060 . The ``pass:[~]`` prefix.
1061 . A <<const-int,positive constant integer>> which is the value of the
1062 byte to use as padding to align the <<cur-offset,current offset>>.
1065 Without this section, the padding byte value is zero.
1071 11 22 (@32 aa bb cc) * 3
1077 11 22 00 00 aa bb cc 00 aa bb cc 00 aa bb cc
1087 @32~0xcc {-893.5:32}
1094 77 88 cc cc 00 60 5f c4 55 55 55 55 55 55 55 55 ┆ w••••`_•UUUUUUUU
1095 6d 65 6f 77 ┆ meow
1103 aa bb cc <29> @64~255 "zoom"
1109 aa bb cc ff ff ff 7a 6f 6f 6d ┆ ••••••zoom
1115 A _filling_ represents zero or more padding bytes to make the
1116 <<cur-offset,current offset>> reach a given value.
1120 . The ``pass:[+]`` prefix.
1124 ** A <<const-int,positive constant integer>> which is the current offset
1127 ** The ``pass:[{]`` prefix, a valid {py3} expression of which the
1128 evaluation result type is `int` or `bool` (automatically converted to
1129 `int`), and the ``pass:[}]`` suffix.
1131 For a filling at some source location{nbsp}__**L**__, this expression
1135 * The name of any <<label,label>> defined before{nbsp}__**L**__
1136 which isn't within a nested group.
1137 * The name of any <<variable-assignment,variable>> known
1141 The value of the special name `ICITTE` (`int` type) in this expression
1142 is the <<cur-offset,current offset>> (before handling the items to
1145 ** A valid {py3} name.
1147 For the name `__NAME__`, this is equivalent to the
1148 `pass:[{]__NAME__pass:[}]` form above.
1151 This value must be greater than or equal to the current offset where
1157 . The ``pass:[~]`` prefix.
1158 . A <<const-int,positive constant integer>> which is the value of the
1159 byte to use as padding to reach the current offset target.
1162 Without this section, the padding byte value is zero.
1176 aa bb cc dd 00 00 00 00 00 00 00 00 00 00 00 00 ┆ ••••••••••••••••
1177 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ┆ ••••••••••••••••
1178 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ┆ ••••••••••••••••
1179 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ┆ ••••••••••••••••
1180 68 65 6c 6c 6f 20 77 6f 72 6c 64 ┆ hello world
1188 !macro part(iter, fill)
1189 <0> "particular security " {ord('0') + iter : 8} +fill~0x80
1195 m:part(iter, {32 + 4 * iter})
1203 70 61 72 74 69 63 75 6c 61 72 20 73 65 63 75 72 ┆ particular secur
1204 69 74 79 20 31 80 80 80 80 80 80 80 80 80 80 80 ┆ ity 1•••••••••••
1205 80 80 80 80 70 61 72 74 69 63 75 6c 61 72 20 73 ┆ ••••particular s
1206 65 63 75 72 69 74 79 20 32 80 80 80 80 80 80 80 ┆ ecurity 2•••••••
1207 80 80 80 80 80 80 80 80 80 80 80 80 70 61 72 74 ┆ ••••••••••••part
1208 69 63 75 6c 61 72 20 73 65 63 75 72 69 74 79 20 ┆ icular security
1209 33 80 80 80 80 80 80 80 80 80 80 80 80 80 80 80 ┆ 3•••••••••••••••
1210 80 80 80 80 80 80 80 80 70 61 72 74 69 63 75 6c ┆ ••••••••particul
1211 61 72 20 73 65 63 75 72 69 74 79 20 34 80 80 80 ┆ ar security 4•••
1212 80 80 80 80 80 80 80 80 80 80 80 80 80 80 80 80 ┆ ••••••••••••••••
1213 80 80 80 80 80 80 80 80 70 61 72 74 69 63 75 6c ┆ ••••••••particul
1214 61 72 20 73 65 63 75 72 69 74 79 20 35 80 80 80 ┆ ar security 5•••
1215 80 80 80 80 80 80 80 80 80 80 80 80 80 80 80 80 ┆ ••••••••••••••••
1216 80 80 80 80 80 80 80 80 80 80 80 80 ┆ ••••••••••••
1222 A _label_ associates a name to the <<cur-offset,current offset>>.
1224 All the labels of a whole Normand input must have unique names.
1226 A label must not share the name of a <<variable-assignment,variable>>
1233 . A valid {py3} name which is not `ICITTE`.
1237 === Variable assignment
1239 A _variable assignment_ associates a name to the integral result of an
1240 evaluated {py3} expression.
1242 A variable assignment is:
1244 . The ``pass:[{]`` prefix.
1246 . A valid {py3} name which is not `ICITTE`.
1248 . The `=` character.
1250 . A valid {py3} expression of which the evaluation result type
1251 is `int`, `float`, or `bool` (automatically converted to `int`).
1253 For a variable assignment at some source location{nbsp}__**L**__, this
1254 expression may contain:
1257 * The name of any <<label,label>> defined before{nbsp}__**L**__
1258 which isn't within a nested group.
1259 * The name of any <<variable-assignment,variable>> known
1263 The value of the special name `ICITTE` (`int` type) in this expression
1264 is the <<cur-offset,current offset>>.
1273 {meow = 42} 11 22 {meow:8} 33 {meow = ICITTE + 17}
1274 "yooo" {meow + mix : 16}
1280 11 22 2a 33 79 6f 6f 6f 7a 00 ┆ •"*3yoooz•
1286 A _group_ is a scoped sequence of items.
1288 The <<label,labels>> within a group aren't visible outside of it.
1290 The main purpose of a group is to <<post-item-repetition,repeat>> more
1291 than a single item and to isolate labels.
1295 . The `(`, `!group`, or `!g` opening.
1297 . Zero or more items.
1299 . Depending on the group opening:
1314 ((aa bb cc) dd () ee) "leclerc"
1320 aa bb cc dd ee 6c 65 63 6c 65 72 63 ┆ •••••leclerc
1329 (aa bb cc) * 3 dd ee
1336 aa bb cc aa bb cc aa bb cc dd ee aa bb cc aa bb
1337 cc aa bb cc dd ee aa bb cc aa bb cc aa bb cc dd
1338 ee aa bb cc aa bb cc aa bb cc dd ee aa bb cc aa
1339 bb cc aa bb cc dd ee
1349 <str_beg> u16le"sébastien diaz" <str_end>
1350 {ICITTE - str_beg : 8}
1351 {(end - str_beg) * 5 : 24}
1359 73 00 e9 00 62 00 61 00 73 00 74 00 69 00 65 00 ┆ s•••b•a•s•t•i•e•
1360 6e 00 20 00 64 00 69 00 61 00 7a 00 1c 00 01 e0 ┆ n• •d•i•a•z•••••
1361 73 00 e9 00 62 00 61 00 73 00 74 00 69 00 65 00 ┆ s•••b•a•s•t•i•e•
1362 6e 00 20 00 64 00 69 00 61 00 7a 00 1c 00 01 40 ┆ n• •d•i•a•z••••@
1363 73 00 e9 00 62 00 61 00 73 00 74 00 69 00 65 00 ┆ s•••b•a•s•t•i•e•
1364 6e 00 20 00 64 00 69 00 61 00 7a 00 1c 00 00 a0 ┆ n• •d•i•a•z•••••
1368 === Conditional block
1370 A _conditional block_ represents either the bytes of zero or more items
1371 if some expression is true, or the bytes of zero or more other items if
1374 A conditional block is:
1376 . The `!if` opening.
1380 ** The ``pass:[{]`` prefix, a valid {py3} expression of which the
1381 evaluation result type is `int` or `bool` (automatically converted to
1382 `int`), and the ``pass:[}]`` suffix.
1384 For a conditional block at some source location{nbsp}__**L**__, this
1385 expression may contain:
1388 * The name of any <<label,label>> defined before{nbsp}__**L**__
1389 which isn't within a nested group.
1390 * The name of any <<variable-assignment,variable>> known
1394 The value of the special name `ICITTE` (`int` type) in this expression
1395 is the <<cur-offset,current offset>> (before handling the contained
1398 ** A valid {py3} name.
1400 For the name `__NAME__`, this is equivalent to the
1401 `pass:[{]__NAME__pass:[}]` form above.
1403 . Zero or more items to be handled when the condition is true.
1407 .. The `!else` opening.
1408 .. Zero or more items to be handled when the condition is false.
1410 . The `!end` closing.
1428 !if {at < rep_count} 20 !end
1437 6d 65 6f 77 20 7a 6f 6f 6d 20 6d 65 6f 77 20 7a ┆ meow zoom meow z
1438 6f 6f 6d 20 6d 65 6f 77 20 7a 6f 6f 6d 20 6d 65 ┆ oom meow zoom me
1439 6f 77 20 6d 69 78 20 6d 65 6f 77 20 6d 69 78 20 ┆ ow mix meow mix
1440 6d 65 6f 77 20 6d 69 78 20 6d 65 6f 77 20 6d 69 ┆ meow mix meow mi
1441 78 20 6d 65 6f 77 20 6d 69 78 20 6d 65 6f 77 20 ┆ x meow mix meow
1454 !if {str_end - str_beg > 10}
1462 6d 00 65 00 6f 00 77 00 20 00 6d 00 69 00 78 00 ┆ m•e•o•w• •m•i•x•
1463 21 00 20 42 49 47 ┆ !• BIG
1467 === Repetition block
1469 A _repetition block_ represents the bytes of one or more items repeated
1470 a given number of times.
1472 A repetition block is:
1474 . The `!repeat` or `!r` opening.
1478 ** A <<const-int,positive constant integer>> which is the number of
1479 times to repeat the previous item.
1481 ** The ``pass:[{]`` prefix, a valid {py3} expression of which the
1482 evaluation result type is `int` or `bool` (automatically converted to
1483 `int`), and the ``pass:[}]`` suffix.
1485 For a repetition block at some source location{nbsp}__**L**__, this
1486 expression may contain:
1489 * The name of any <<label,label>> defined before{nbsp}__**L**__
1490 which isn't within a nested group.
1491 * The name of any <<variable-assignment,variable>> known
1495 The value of the special name `ICITTE` (`int` type) in this expression
1496 is the <<cur-offset,current offset>> (before handling the items to
1499 ** A valid {py3} name.
1501 For the name `__NAME__`, this is equivalent to the
1502 `pass:[{]__NAME__pass:[}]` form above.
1504 . Zero or more items.
1506 . The `!end` closing.
1508 You may also use a <<post-item-repetition,post-item repetition>> after
1509 some items. The form ``!repeat{nbsp}__X__{nbsp}__ITEMS__{nbsp}!end``
1510 is equivalent to ``(__ITEMS__){nbsp}pass:[*]{nbsp}__X__``.
1517 {end - ICITTE - 1 : 8}
1526 ff fe fd fc fb fa f9 f8 f7 f6 f5 f4 f3 f2 f1 f0 ┆ ••••••••••••••••
1527 ef ee ed ec eb ea e9 e8 e7 e6 e5 e4 e3 e2 e1 e0 ┆ ••••••••••••••••
1528 df de dd dc db da d9 d8 d7 d6 d5 d4 d3 d2 d1 d0 ┆ ••••••••••••••••
1529 cf ce cd cc cb ca c9 c8 c7 c6 c5 c4 c3 c2 c1 c0 ┆ ••••••••••••••••
1530 bf be bd bc bb ba b9 b8 b7 b6 b5 b4 b3 b2 b1 b0 ┆ ••••••••••••••••
1531 af ae ad ac ab aa a9 a8 a7 a6 a5 a4 a3 a2 a1 a0 ┆ ••••••••••••••••
1532 9f 9e 9d 9c 9b 9a 99 98 97 96 95 94 93 92 91 90 ┆ ••••••••••••••••
1533 8f 8e 8d 8c 8b 8a 89 88 87 86 85 84 83 82 81 80 ┆ ••••••••••••••••
1534 7f 7e 7d 7c 7b 7a 79 78 77 76 75 74 73 72 71 70 ┆ •~}|{zyxwvutsrqp
1535 6f 6e 6d 6c 6b 6a 69 68 67 66 65 64 63 62 61 60 ┆ onmlkjihgfedcba`
1536 5f 5e 5d 5c 5b 5a 59 58 57 56 55 54 53 52 51 50 ┆ _^]\[ZYXWVUTSRQP
1537 4f 4e 4d 4c 4b 4a 49 48 47 46 45 44 43 42 41 40 ┆ ONMLKJIHGFEDCBA@
1538 3f 3e 3d 3c 3b 3a 39 38 37 36 35 34 33 32 31 30 ┆ ?>=<;:9876543210
1539 2f 2e 2d 2c 2b 2a 29 28 27 26 25 24 23 22 21 20 ┆ /.-,+*)('&%$#"!
1540 1f 1e 1d 1c 1b 1a 19 18 17 16 15 14 13 12 11 10 ┆ ••••••••••••••••
1541 0f 0e 0d 0c 0b 0a 09 08 07 06 05 04 03 02 01 00 ┆ ••••••••••••••••
1560 11 22 !repeat times 33 !end
1571 aa bb cc dd ee ff ee ff ee ff ee ff ee ff 11 22 ┆ •••••••••••••••"
1572 33 ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ 3•••••••••••••••
1573 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1574 ff ee ff ee ff 11 22 33 33 ee ff ee ff ee ff ee ┆ ••••••"33•••••••
1575 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1576 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1577 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1578 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1579 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1580 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1581 ff ee ff ee ff ee ff ee ff ee ff ee ff 11 22 33 ┆ ••••••••••••••"3
1582 33 33 63 6f 75 63 6f 75 21 ┆ 33coucou!
1586 === Macro definition block
1588 A _macro definition block_ associates a name and parameter names to
1591 A macro definition block doesn't lead to generated bytes itself: a
1592 <<macro-expansion,macro expansion>> does so.
1594 A macro definition may only exist at the root level, that is, not within
1595 a <<group,group>>, a <<repetition-block,repetition block>>, a
1596 <<conditional-block,conditional block>>, or another
1597 <<macro-definition-block,macro definition block>>.
1599 All macro definitions must have unique names.
1601 A macro definition is:
1603 . The `!macro` or `!m` opening.
1605 . A valid {py3} name (the macro name).
1607 . The `(` parameter name list prefix.
1609 . A comma-separated list of zero or more unique parameter names,
1610 each one being a valid {py3} name.
1612 . The `)` parameter name list suffix.
1614 . Zero or more items except, recursively, a macro definition block.
1616 . The `!end` closing.
1621 {le} {ICITTE * 8 : 16}
1622 u16le"predict explode"
1629 !macro nail(rep, with_extra, val)
1633 {val + iter : uleb128}
1647 A _macro expansion_ expands the items of a defined
1648 <<macro-definition-block,macro>>.
1650 The macro to expand must be defined _before_ the expansion.
1652 The <<state,state>> before handling the first item of the chosen macro
1655 <<cur-offset,Current offset>>::
1658 <<cur-bo,Current byte order>>::
1662 The only available variables initially are the macro parameters.
1667 The state after having handled the last item of the chosen macro is:
1670 The one before handling the first item of the macro plus the size
1671 of the generated data of the macro expansion.
1673 IMPORTANT: This means <<current-offset-setting,current offset setting>>
1674 items within the expanded macro don't impact the final current offset.
1676 Current byte order::
1677 The one before handling the first item of the macro.
1680 The ones before handling the first item of the macro.
1683 The ones before handling the first item of the macro.
1685 A macro expansion is:
1689 . A valid {py3} name (the name of the macro to expand).
1691 . The `(` parameter value list prefix.
1693 . A comma-separated list of zero or more unique parameter values.
1695 The number of parameter values must match the number of parameter
1696 names of the definition of the chosen macro.
1698 A parameter value is one of:
1701 * A <<const-int,constant integer>>, possibly negative.
1703 * A constant floating point number.
1705 * The ``pass:[{]`` prefix, a valid {py3} expression of which the
1706 evaluation result type is `int` or `bool` (automatically converted to
1707 `int`), and the ``pass:[}]`` suffix.
1709 For a macro expansion at some source location{nbsp}__**L**__, this
1710 expression may contain:
1712 ** The name of any <<label,label>> defined before{nbsp}__**L**__
1713 which isn't within a nested group.
1714 ** The name of any <<variable-assignment,variable>> known
1718 The value of the special name `ICITTE` (`int` type) in this expression
1719 is the <<cur-offset,current offset>> (before handling the items of the
1722 * A valid {py3} name.
1724 For the name `__NAME__`, this is equivalent to the
1725 `pass:[{]__NAME__pass:[}]` form above.
1728 . The `)` parameter value list suffix.
1735 {le} {ICITTE * 8 : 16}
1736 u16le"predict explode"
1739 "hello [" m:bake() "] world"
1747 68 65 6c 6c 6f 20 5b 38 00 70 00 72 00 65 00 64 ┆ hello [8•p•r•e•d
1748 00 69 00 63 00 74 00 20 00 65 00 78 00 70 00 6c ┆ •i•c•t• •e•x•p•l
1749 00 6f 00 64 00 65 00 5d 20 77 6f 72 6c 64 70 01 ┆ •o•d•e•] worldp•
1750 70 00 72 00 65 00 64 00 69 00 63 00 74 00 20 00 ┆ p•r•e•d•i•c•t• •
1751 65 00 78 00 70 00 6c 00 6f 00 64 00 65 00 70 02 ┆ e•x•p•l•o•d•e•p•
1752 70 00 72 00 65 00 64 00 69 00 63 00 74 00 20 00 ┆ p•r•e•d•i•c•t• •
1753 65 00 78 00 70 00 6c 00 6f 00 64 00 65 00 70 03 ┆ e•x•p•l•o•d•e•p•
1754 70 00 72 00 65 00 64 00 69 00 63 00 74 00 20 00 ┆ p•r•e•d•i•c•t• •
1755 65 00 78 00 70 00 6c 00 6f 00 64 00 65 00 70 04 ┆ e•x•p•l•o•d•e•p•
1756 70 00 72 00 65 00 64 00 69 00 63 00 74 00 20 00 ┆ p•r•e•d•i•c•t• •
1757 65 00 78 00 70 00 6c 00 6f 00 64 00 65 00 70 05 ┆ e•x•p•l•o•d•e•p•
1758 70 00 72 00 65 00 64 00 69 00 63 00 74 00 20 00 ┆ p•r•e•d•i•c•t• •
1759 65 00 78 00 70 00 6c 00 6f 00 64 00 65 00 ┆ e•x•p•l•o•d•e•
1767 !macro A(val, is_be)
1777 !macro B(rep, is_be)
1781 m:A({iter * 3}, is_be)
1793 00 03 00 06 00 09 00 0c 00 0f 03 00 06 00 09 00
1801 !macro flt32be(val) {be} {val : 32} !end
1811 43 48 45 45 54 4f 53 c2 28 ae 14 3b b8 41 25 ┆ CHEETOS•(••;•A%
1815 === Post-item repetition
1817 A _post-item repetition_ represents the bytes of an item repeated a
1818 given number of times.
1820 A post-item repetition is:
1822 . One of those items:
1824 ** A <<byte-constant,byte constant>>.
1825 ** A <<literal-string,literal string>>.
1826 ** A <<fixed-length-number,fixed-length number>>.
1827 ** An <<leb128-integer,LEB128 integer>>.
1828 ** A <<macro-expansion,macro-expansion>>.
1829 ** A <<group,group>>.
1831 . The ``pass:[*]`` character.
1835 ** A positive integer (hexadecimal starting with `0x` or `0X` accepted)
1836 which is the number of times to repeat the previous item.
1838 ** The ``pass:[{]`` prefix, a valid {py3} expression of which the
1839 evaluation result type is `int` or `bool` (automatically converted to
1840 `int`), and the ``pass:[}]`` suffix.
1842 For a post-item repetition at some source location{nbsp}__**L**__, this
1843 expression may contain:
1846 * The name of any <<label,label>> defined before{nbsp}__**L**__
1847 which isn't within a nested group and
1848 which isn't part of the repeated item.
1849 * The name of any <<variable-assignment,variable>> known
1850 at{nbsp}__**L**__, which isn't part of its repeated item, and which
1854 The value of the special name `ICITTE` (`int` type) in this expression
1855 is the <<cur-offset,current offset>> (before handling the items to
1858 ** A valid {py3} name.
1860 For the name `__NAME__`, this is equivalent to the
1861 `pass:[{]__NAME__pass:[}]` form above.
1863 You may also use a <<repetition-block,repetition block>>. The form
1864 ``__ITEM__{nbsp}pass:[*]{nbsp}__X__`` is equivalent to
1865 ``!repeat{nbsp}__X__{nbsp}__ITEM__{nbsp}!end``.
1871 {end - ICITTE - 1 : 8} * 0x100 <end>
1877 ff fe fd fc fb fa f9 f8 f7 f6 f5 f4 f3 f2 f1 f0 ┆ ••••••••••••••••
1878 ef ee ed ec eb ea e9 e8 e7 e6 e5 e4 e3 e2 e1 e0 ┆ ••••••••••••••••
1879 df de dd dc db da d9 d8 d7 d6 d5 d4 d3 d2 d1 d0 ┆ ••••••••••••••••
1880 cf ce cd cc cb ca c9 c8 c7 c6 c5 c4 c3 c2 c1 c0 ┆ ••••••••••••••••
1881 bf be bd bc bb ba b9 b8 b7 b6 b5 b4 b3 b2 b1 b0 ┆ ••••••••••••••••
1882 af ae ad ac ab aa a9 a8 a7 a6 a5 a4 a3 a2 a1 a0 ┆ ••••••••••••••••
1883 9f 9e 9d 9c 9b 9a 99 98 97 96 95 94 93 92 91 90 ┆ ••••••••••••••••
1884 8f 8e 8d 8c 8b 8a 89 88 87 86 85 84 83 82 81 80 ┆ ••••••••••••••••
1885 7f 7e 7d 7c 7b 7a 79 78 77 76 75 74 73 72 71 70 ┆ •~}|{zyxwvutsrqp
1886 6f 6e 6d 6c 6b 6a 69 68 67 66 65 64 63 62 61 60 ┆ onmlkjihgfedcba`
1887 5f 5e 5d 5c 5b 5a 59 58 57 56 55 54 53 52 51 50 ┆ _^]\[ZYXWVUTSRQP
1888 4f 4e 4d 4c 4b 4a 49 48 47 46 45 44 43 42 41 40 ┆ ONMLKJIHGFEDCBA@
1889 3f 3e 3d 3c 3b 3a 39 38 37 36 35 34 33 32 31 30 ┆ ?>=<;:9876543210
1890 2f 2e 2d 2c 2b 2a 29 28 27 26 25 24 23 22 21 20 ┆ /.-,+*)('&%$#"!
1891 1f 1e 1d 1c 1b 1a 19 18 17 16 15 14 13 12 11 10 ┆ ••••••••••••••••
1892 0f 0e 0d 0c 0b 0a 09 08 07 06 05 04 03 02 01 00 ┆ ••••••••••••••••
1904 (ee ff) * {here + 1}
1914 aa bb cc dd ee ff ee ff ee ff ee ff ee ff 11 22 ┆ •••••••••••••••"
1915 33 ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ 3•••••••••••••••
1916 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1917 ff ee ff ee ff 11 22 33 33 ee ff ee ff ee ff ee ┆ ••••••"33•••••••
1918 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1919 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1920 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1921 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1922 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1923 ff ee ff ee ff ee ff ee ff ee ff ee ff ee ff ee ┆ ••••••••••••••••
1924 ff ee ff ee ff ee ff ee ff ee ff ee ff 11 22 33 ┆ ••••••••••••••"3
1925 33 33 63 6f 75 63 6f 75 21 ┆ 33coucou!
1929 == Command-line tool
1931 If you <<install-normand,installed>> the `normand` package, then you
1932 can use the `normand` command-line tool:
1935 $ normand <<< '"ma gang de malades"' | hexdump -C
1939 00000000 6d 61 20 67 61 6e 67 20 64 65 20 6d 61 6c 61 64 |ma gang de malad|
1943 If you copy the `normand.py` module to your own project, then you can
1944 run the module itself:
1947 $ python3 -m normand <<< '"ma gang de malades"' | hexdump -C
1951 00000000 6d 61 20 67 61 6e 67 20 64 65 20 6d 61 6c 61 64 |ma gang de malad|
1955 Without a path argument, the `normand` tool reads from the standard
1958 The `normand` tool prints the generated binary data to the standard
1961 Various options control the initial <<state,state>> of the processor:
1962 use the `--help` option to learn more.
1966 The whole `normand` package/module public API is:
1971 class ByteOrder(enum.Enum):
1983 def line_no(self) -> int:
1988 def col_no(self) -> int:
1992 # Parsing error message.
1993 class ParseErrorMessage:
1999 # Source text location.
2001 def text_location(self):
2006 class ParseError(RuntimeError):
2007 # Parsing error messages.
2009 # The first message is the most _specific_ one.
2015 # Variables dictionary type (for type hints).
2016 VariablesT = typing.Dict[str, typing.Union[int, float]]
2019 # Labels dictionary type (for type hints).
2020 LabelsT = typing.Dict[str, int]
2027 def data(self) -> bytearray:
2030 # Updated variable values.
2032 def variables(self) -> SymbolsT:
2035 # Updated main group label values.
2037 def labels(self) -> SymbolsT:
2042 def offset(self) -> int:
2047 def byte_order(self) -> typing.Optional[ByteOrder]:
2051 # Parses the `normand` input using the initial state defined by
2052 # `init_variables`, `init_labels`, `init_offset`, and `init_byte_order`,
2053 # and returns the corresponding parsing result.
2054 def parse(normand: str,
2055 init_variables: typing.Optional[SymbolsT] = None,
2056 init_labels: typing.Optional[SymbolsT] = None,
2057 init_offset: int = 0,
2058 init_byte_order: typing.Optional[ByteOrder] = None) -> ParseResult:
2062 The `normand` parameter is the actual <<learn-normand,Normand input>>
2063 while the other parameters control the initial <<state,state>>.
2065 The `parse()` function raises a `ParseError` instance should it fail to
2066 parse the `normand` string for any reason.
2070 Normand is a https://python-poetry.org/[Poetry] project.
2072 To develop it, install it through Poetry and enter the virtual
2078 $ normand <<< '"lol" * 10 0a'
2081 `normand.py` is processed by:
2083 * https://microsoft.github.io/pyright/[Pyright]
2084 * https://github.com/psf/black[Black]
2085 * https://pycqa.github.io/isort/[isort]
2089 Use https://docs.pytest.org/[pytest] to test Normand once the package is
2090 part of your virtual environment, for example:
2094 $ poetry run pip3 install pytest
2098 The `pytest` project is currently not a development dependency in
2099 `pyproject.toml` due to backward compatibiliy issues with
2102 In the `tests` directory, each `*.nt` file is a test. The file name
2103 prefix indicates what it's meant to test:
2106 Everything above the `---` line is the valid Normand input
2109 Everything below the `---` line is the expected data
2110 (whitespace-separated hexadecimal bytes).
2113 Everything above the `---` line is the invalid Normand input
2116 Everything below the `---` line is the expected error message having
2125 Normand uses https://review.lttng.org/admin/repos/normand,general[Gerrit]
2128 To report a bug, https://github.com/efficios/normand/issues/new[create a