Add the directive form of a repetition (`!repeat`)

This patch introduces the first directive amongst other ones I'd like to
add later.

`!repeat` is equivalent to what's now called the post-item repetition
form:

    aa (bb cc dd) * 3 ee ff

    aa
    !repeat 3
      bb cc dd
    !end
    ff

`!repeat` (or the shorter `!r` alias) accepts exactly what's accepted
after a `*`: a constant integer, an expression, and (new) a name.

Obviously, the `!` symbol isn't considered a comment anymore.

See `README.adoc` and the new tests to learn more.

This patch also:

* Makes it legal to refer to the special `ICITTE` name within a
  repetition count expression.

  It's less natural for the post-item form, but it works nevertheless.

* Decouples the variables and labels dictionary types as `VariablesT`
  and `LabelsT`. Indeed, a variable value is (for the moment) an `int`
  or `float` instance, while a label value is always an integer (because
  it's an offset snapshot).

Change-Id: I77cd4c9f29639082612534940c48964a61e51392
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

README.adoc: "an current offset" -> "a current offset"

Change-Id: If7bc2a399d99d06be98bafc12d3d7f9808e0e2b5
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Add offset alignment support

This patch adds a new item which is meant to update the current offset
so that it satisfies a given alignment.

The form is:

    @32
    @64~39
    @16~0xcc

What follows `@` is the alignment value in bits (any multiple of eight
greater than zero). The optional part starting with `~` is the value of
the padding bytes to add to satisfy the alignment requirement.

See the new tests and the `README.adoc` examples to learn more.

`@` used to be an insignificant symbol, but it's not anymore (not
consider as a comment).

Also fixing missing repr() calls at some places.

Change-Id: I9f5ac1da6988c060391640bf2784567a76e9fc48
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

tests/test_api.py: apply Black and Pyright

Change-Id: I5f15a309a0ff0c79717f46461fb3b4aaca7af5b0
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Fix: normand.py: update `SymbolsT` to accept `float` value

Change-Id: I3cc65f7452458c9ebdb03e1ef8c615af279fcbb3
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Add basic API tests

Change-Id: I4c1aeac08e7da9b350b1a49baf460969a1e67a06
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Fix: normand.py: accept floating point number variable

Change-Id: I6681cedabaaf458245bfa72495c7619960d260da
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Add fixed-length floating point number support

This patch adds support to encode binary32 and binary64 (as per
IEEE 754-2008) floating point numbers, big and little endian.

The Normand form is the same as a fixed-length integer:

    { 32.87 : 32 }

The type of the result of the evaluation determines how to encode it:
integer or floating point number.

Some "fixed-length integer" terms are changed to "fixed-length number"
when they're meant to be general.

With this patch, you may also assign a variable to a floating point
number value. However, the result type of an LEB128 integer or
repetition count expression must still be `int`.

Change-Id: Ic13ed747276a365ed2fd8854545ab2b0e1c343a0
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

README.adoc: add missing "Output:" paragraph

Change-Id: If49b43a25eb9681e30f4cdbe1862679866cc8422
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

README.adoc: use the correct `python3-api` section ID

Change-Id: Ic1d24284a71e19e075ab7b66e22c75290a1aed19
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Rename `normand.VarsT` to `normand.SymbolsT`

This term is more general and applies to both labels and variables.

Change-Id: Iad4d72fa1cf26b934d04ebd014acf51b6881c817
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Add LEB128 integer support

This patch adds unsigned and signed LEB128 [1] integer support with the
following Normand format:

    {my_val : uleb128}
    {my_val : sleb128}

LEB128 is a popular variable-length integer encoding which has
CTF 2 [2], Android, HP, DWARF, WebAssembly, the xz format, and many more
as its users.

To avoid any confusion, the term "value" in the Normand project is
renamed to "fixed-length integer" (`README.adoc`, test names, and the
code itself).

The challenge for a LEB128 item is similar to a repetition with an
expression: you don't know the final length when parsing because it can
depend on preceding labels and variables. Therefore the repetition item
validation and handling code is reused.

The new test files with names containing `-byte` were randomly generated
using the `leb128` package, therefore Normand agrees with another LEB128
implementation.

[1]: https://en.wikipedia.org/wiki/LEB128
[2]: https://diamon.org/ctf/

Change-Id: Ieac783dcdd093e1b5c70396a12fc2b568c9885bb
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Add initial tests

The tests are meant to be run by pytest (just run `pytest` in the root
or `tests` directory once Normand is installed).

Each `.nt` file is a test, its prefix indicating the expectation:

`pass-`:
    Everything above the `---` line is the valid Normand input
    to test.

    Everything below the `---` line is the expected data
    (whitespace-separated hexadecimal bytes).

`fail-`:
    Everything above the `---` line is the invalid Normand input
    to test.

    Everything below the `---` line is the expected error message
    having this form:

        LINE:COL - MESSAGE

Change-Id: I65c0276f418c252735f75e583023772194b9eb4a
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Add variable repetition count support

This patch makes it possible to do this:

    {meow = 23}
    aa <lbl> bb (cc dd) * {9 * meow + lbl} ff

The repetition count expression cannot refer to a "future" label name,
to an inner label name, or to any variable of which the value was
computed using, directly or indirectly, one of those labels.

For example, this is invalid:

    aa
    {meow = mix}
    {zoom = meow}
    bb * {zoom}
    <mix>

However this is valid:

    aa
    {meow = mix}
    {zoom = meow}
    {meow = 23}
    bb * {meow}
    <mix>

An interesting side effect of this feature is to make Normand support
conditional sections by using zero vs. one repetition:

    (
      <beg>
      aa bb cc dd
      <end>
      {include = int(beg >= 4 * (end - beg))}
      (11 22 33 44) * {include}
    ) * 10

Result:

    aa bb cc dd aa bb cc dd  aa bb cc dd aa bb cc dd  ┆ ••••••••••••••••
    aa bb cc dd 11 22 33 44  aa bb cc dd 11 22 33 44  ┆ •••••"3D•••••"3D
    aa bb cc dd 11 22 33 44  aa bb cc dd 11 22 33 44  ┆ •••••"3D•••••"3D
    aa bb cc dd 11 22 33 44  aa bb cc dd 11 22 33 44  ┆ •••••"3D•••••"3D

This becomes interesting with externally-provided variables, for
example:

    aa bb cc dd
    (beef) * {has_beef}
    "salut"

You may include or exclude the `be ef` bytes with `--var=has_beef=1` and
`--var=has_beef=0` (or the equivalent API way).

Also update the `README.adoc` usage and examples.

Change-Id: I8cd8aa7078cbe48038b00c541aa40a067c9f79bf
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Fix: _dict_from_arg(): actually fill the dictionary

Change-Id: Ib86c8df44986eeec5b45908bce2d15c44d053d99
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

normand.py: add comment about the portable module

Change-Id: I8e7792f0864bdb0c7786eabcc0a46e00122734b7
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Make text locations of some items and errors more precise

Using the text location before parsing the item instead of after it
feels more natural.

Change-Id: I0390d3885bf388e1d3ac37e8520ca1894de8474b
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Fix: parse a 0-item repetition

Change-Id: I89d3d01db51a78a0ff543650d95486208eb91d26
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Add `.gitreview`

Change-Id: I4e21512c102ab4d4f150fce2a789da330295f11e
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

README.adoc: add logo

Change-Id: I039e3a475101c79699891687c7843936f2c456ff
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

README.adoc: remove redundant internal links

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

README.adoc: make it work offline too

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

The earliest commit (also Normand 0.1.0)

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>