This package offers both a portable {py3} module and a command-line
tool.
-WARNING: This version of Normand is 0.1, meaning both the Normand
+WARNING: This version of Normand is 0.4, meaning both the Normand
language and the module/CLI interface aren't stable.
ifdef::env-github[]
The value of a variable assignment is the evaluation of a valid {py3}
expression which may include label and variable names.
-Value encoding with a specific length (8{nbsp}bits to 64{nbsp}bits) and byte order::
+Fixed-length integer with a given length (8{nbsp}bits to 64{nbsp}bits) and byte order::
+
Input:
+
67 44 b2 00 2c 63 37 f8 ff ff
----
+
-The encoded value is the evaluation of a valid {py3} expression which
+The encoded integer is the evaluation of a valid {py3} expression which
+may include label and variable names.
+
+https://en.wikipedia.org/wiki/LEB128[LEB128] integer::
++
+Input:
++
+----
+aa bb cc {-1993 : sleb128} <meow> dd ee ff
+{meow * 199 : uleb128}
+----
++
+Output:
++
+----
+aa bb cc b7 70 dd ee ff e3 07
+----
++
+The encoded integer is the evaluation of a valid {py3} expression which
may include label and variable names.
Repetition::
|[[cur-offset]] Current offset
|
-The current offset has an effect on the value of
-<<label,labels>> and of the special `ICITTE` name in <<value,value>> and
+The current offset has an effect on the value of <<label,labels>> and of
+the special `ICITTE` name in <<fixed-length-integer,fixed-length
+integer>>, <<leb-128-integer,LEB128 integer>>, and
<<variable-assignment,variable assignment>> expression evaluation.
Each generated byte increments the current offset.
|[[cur-bo]] Current byte order
|
-The current byte order has an effect on the encoding of <<value,values>>.
+The current byte order has an effect on the encoding of
+<<fixed-length-integer,fixed-length integers>>.
A <<current-byte-order-setting,current byte order setting>> may change
the current byte order.
* A <<current-byte-order-setting,current byte order setting>> (big or
little endian).
-* A <<value,{py3} expression to be evaluated>> as an unsigned or signed
- integer to be encoded on one or more bytes using the current byte
- order.
+* A <<fixed-length-integer,fixed-length integer>> 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 <<current-offset-setting,current offset setting>>.
``pass:[{be}]``:: Set the current byte order to big endian.
``pass:[{le}]``:: Set the current byte order to little endian.
-=== Value
-
-A _value_ represents a fixed number of bytes encoding an unsigned or
-signed integer which is the result of evaluating a {py3} expression
-using the <<cur-bo,current byte order>>.
-
-For a value at some source location{nbsp}__**L**__, its {py3} expression
-may contain the name of any accessible <<label,label>>, including the
-name of a label defined after{nbsp}__**L**__, as well as the name of any
-<<variable-assignment,variable>> known at{nbsp}__**L**__.
-
-An accessible label is either:
-
-* Outside of the current <<group,group>>.
-* Within the same immediate group (not within a nested group).
+=== Fixed-length integer
-In the {py3} expression of a value, the value of the special name
-`ICITTE` is the <<cur-offset,current offset>> (before encoding the
-value).
+A _fixed-length integer_ represents a fixed number of bytes encoding an
+unsigned or signed integer which is the result of evaluating a {py3}
+expression using the <<cur-bo,current byte order>>.
-A value is:
+A fixed-length integer is:
. The ``pass:[{]`` prefix.
. A valid {py3} expression.
++
+For a fixed-length integer at some source location{nbsp}__**L**__, this
+expression may contain the name of any accessible <<label,label>> (not
+within a nested group), including the name of a label defined
+after{nbsp}__**L**__, as well as the name of any
+<<variable-assignment,variable>> known at{nbsp}__**L**__.
++
+The value of the special name `ICITTE` in this expression is the
+<<cur-offset,current offset>> (before encoding the integer).
. The `:` character.
----
====
+=== LEB128 integer
+
+An _LEB128 integer_ represents a variable number of bytes encoding an
+unsigned or signed integer which is the result of evaluating a {py3}
+expression following the https://en.wikipedia.org/wiki/LEB128[LEB128]
+format.
+
+An LEB128 integer is:
+
+. The ``pass:[{]`` prefix.
+
+. A valid {py3} expression.
++
+For an LEB128 integer at some source location{nbsp}__**L**__, this
+expression may contain:
++
+--
+* The name of any <<label,label>> defined before{nbsp}__**L**__.
+* The name of any <<variable-assignment,variable>> known at{nbsp}__**L**__
+ which doesn't, directly or indirectly, refer to a label
+ defined after{nbsp}__**L**__.
+--
++
+The value of the special name `ICITTE` in this expression is the
+<<cur-offset,current offset>> (before encoding the integer).
+
+. The `:` character.
+
+. One of:
++
+--
+[horizontal]
+`uleb128`:: Use the unsigned LEB128 format.
+`sleb128`:: Use the signed LEB128 format.
+--
+
+. The `}` suffix.
+
+====
+Input:
+
+----
+{624485 : uleb128}
+----
+
+Output:
+
+----
+e5 8e 26
+----
+====
+
+====
+Input:
+
+----
+aa bb cc dd
+<meow>
+ee ff
+{-981238311 + (meow * -23) : sleb128}
+"hello"
+----
+
+----
+aa bb cc dd ee ff fd fa 8d ac 7c 68 65 6c 6c 6f ┆ ••••••••••|hello
+----
+====
+
=== Current offset setting
This special item sets the <<cur-offset,_current offset_>>.
All the labels of a whole Normand input must have unique names.
-A label may not share the name of a <<variable-assignment,variable>>
+A label must not share the name of a <<variable-assignment,variable>>
name.
-A label name may not be `ICITTE` (see <<value>> and
-<<variable-assignment>> to learn more).
-
A label is:
. The `<` prefix.
-. A valid {py3} name which is not `ICITTE`.
+. A valid {py3} name which is not `ICITTE` (see
+ <<fixed-length-integer>>, <<leb128-integer>>, and
+ <<variable-assignment>> to learn more).
. The `>` suffix.
A _variable assignment_ associates a name to the integral result of an
evaluated {py3} expression.
-For a variable assignment at some source location{nbsp}__**L**__, its
-{py3} expression may contain the name of any accessible <<label,label>>,
-including the name of a label defined after{nbsp}__**L**__, as well as
-the name of any variable known at{nbsp}__**L**__.
-
-An accessible label is either:
-
-* Outside of the current <<group,group>>.
-* Within the same immediate group (not within a nested group).
-
-A variable name may not be `ICITTE`.
-
-In the {py3} expression of a variable assignment, the special name
-`ICITTE` is the <<cur-offset,current offset>>.
-
-A variable is:
+A variable assignment is:
. The ``pass:[{]`` prefix.
-. A valid {py3} name which is not `ICITTE`.
+. A valid {py3} name which is not `ICITTE` (see
+ <<fixed-length-integer>>, <<leb128-integer>>, and
+ <<variable-assignment>> to learn more).
. The `=` character.
. A valid {py3} expression.
++
+For a variable assignment at some source location{nbsp}__**L**__, this
+expression may contain the name of any accessible <<label,label>> (not
+within a nested group), including the name of a label defined
+after{nbsp}__**L**__, as well as the name of any
+<<variable-assignment,variable>> known at{nbsp}__**L**__.
++
+The value of the special name `ICITTE` in this expression is the
+<<cur-offset,current offset>>.
. The `}` suffix.
** The ``pass:[{]`` prefix, a valid {py3} expression, and the
``pass:[}]`` suffix.
-
-When using an expression, it can't refer, directly or indirectly, to a
-subsequent label name and to the reserved `ICITTE` name.
++
+For a repetition at some source location{nbsp}__**L**__, this expression
+may contain:
++
+--
+* The name of any <<label,label>> defined before{nbsp}__**L**__ and
+ which isn't part of its repeated item.
+* The name of any <<variable-assignment,variable>> known
+ at{nbsp}__**L**__, which isn't part of its repeated item, and which
+ doesn't, directly or indirectly, refer to a label defined
+ after{nbsp}__**L**__.
+--
++
+This expression must not contain the special name `ICITTE`.
====
Input:
projects / normand.git / blobdiff