+// SPDX-FileCopyrightText: 2023 Philippe Proulx <eeppeliteloop@gmail.com>
+// SPDX-License-Identifier: CC-BY-SA-4.0
+
// Show ToC at a specific location for a GitHub rendering
ifdef::env-github[]
:toc: macro
This package offers both a portable {py3} module and a command-line
tool.
-WARNING: This version of Normand is 0.22, meaning both the Normand
+WARNING: This version of Normand is 0.23, meaning both the Normand
language and the module/CLI interface aren't stable.
ifdef::env-github[]
{strength = 4}
!be 67 <lbl> 44 $178 [(end - lbl) * 8 + strength : 16] $99 <end>
!le [-1993 : 32]
-[-3.141593 : 64]
+[-3.141593 : 64be]
----
+
Output:
+
----
-67 44 b2 00 2c 63 37 f8 ff ff 7f bd c2 82 fb 21
-09 c0
+67 44 b2 00 2c 63 37 f8 ff ff c0 09 21 fb 82 c2
+bd 7f
----
+
The encoded number is the evaluation of a valid {py3} expression which
function and the <<command-line-tool,command-line tool>>).
`normand.py` has _no external dependencies_, but if you're using
-Python{nbsp}3.4, you'll need a local copy of the standard `typing`
-module.
+Python{nbsp}3.4 or Python{nbsp}3.5, you'll need a local copy of the
+standard `typing` module.
====
== Design goals
Compare the following Normand input and some hypothetical XML
equivalent, for example:
+
-.Actual normand input.
+.Actual Normand input.
----
ff dd 01 ab $192 $-128 %1101:0011
|
The current offset has an effect on the value of <<label,labels>> and of
the special `ICITTE` name in <<fixed-length-number,fixed-length
-number>>, <<leb-128-integer,LEB128 integer>>, <<string,string>>,
+number>>, <<leb128-integer,LEB128 integer>>, <<string,string>>,
<<filling,filling>>, <<variable-assignment,variable assignment>>,
<<conditional-block,conditional block>>, <<repetition-block,repetition
block>>, <<macro-expansion,macro expansion>>, and
|[[cur-bo]] Current byte order
|
-The current byte order has an effect on the encoding of
+The current byte order can have an effect on the encoding of
<<fixed-length-number,fixed-length numbers>>.
A <<current-byte-order-setting,current byte order setting>> may change
little endian).
* A <<fixed-length-number,fixed-length number>> (integer or
- floating point) using the <<cur-bo,current byte order>> and of which
- the value is the result of a {py3} expression.
+ floating point), possibly using the <<cur-bo,current byte order>>, and
+ of which the value is the result of a {py3} expression.
* An <<leb128-integer,LEB128 integer>> of which the value is the result
of a {py3} expression.
* A floating point number
(https://standards.ieee.org/standard/754-2008.html[IEEE{nbsp}754-2008]).
+
-The available length are 32 (_binary32_) and 64 (_binary64_).
+The available lengths are 32 (_binary32_) and 64 (_binary64_).
+
+The value is the result of evaluating a {py3} expression.
-The value is the result of evaluating a {py3} expression using the
-<<cur-bo,current byte order>>.
+The byte order to use to encode the value is either directly specified
+or is the <<cur-bo,current byte order>>.
A fixed-length number is:
`32` and `64`.
--
+. **Optional**: a suffix of the previous encoding length, without
+ any whitespace, amongst:
++
+--
+[horizontal]
+`be`:: Encode in big endian.
+`le`:: Encode in little endian.
+--
++
+Without this suffix, the encoding byte order is the <<cur-bo,current
+byte order>> which must be defined if the encoding length is greater
+than eight.
+
. The `]` suffix.
====
Input:
----
-!le [345:16]
-!be [-0xabcd:32]
+[345:16le]
+[-0xabcd:32be]
----
Output:
Input:
----
-!le
-[2 * 0.0529 : 32]
+[2 * 0.0529 : 32le]
----
Output:
* https://github.com/psf/black[Black]
* https://pycqa.github.io/isort/[isort]
+Licensing and copyright follows the
+https://reuse.software/tutorial/[REUSE] specification and is checked
+with the https://github.com/fsfe/reuse-tool[reuse tool].
+
=== Testing
Use https://docs.pytest.org/[pytest] to test Normand once the package is