This package offers both a portable {py3} module and a command-line
tool.
-WARNING: This version of Normand is 0.18, meaning both the Normand
+WARNING: This version of Normand is 0.19, meaning both the Normand
language and the module/CLI interface aren't stable.
ifdef::env-github[]
aa bb f7 a7 32 da
----
-UTF-8, UTF-16, and UTF-32 literal strings::
+Strings::
+
Input:
+
----
"hello world!" 00
u16le"stress\nverdict 🤣"
+s:latin3{hex(ICITTE)}
----
+
Output:
----
68 65 6c 6c 6f 20 77 6f 72 6c 64 21 00 73 00 74 ┆ hello world!•s•t
00 72 00 65 00 73 00 73 00 0a 00 76 00 65 00 72 ┆ •r•e•s•s•••v•e•r
-00 64 00 69 00 63 00 74 00 20 00 3e d8 23 dd ┆ •d•i•c•t• •>•#•
+00 64 00 69 00 63 00 74 00 20 00 3e d8 23 dd 30 ┆ •d•i•c•t• •>•#•0
+78 32 66 ┆ x2f
----
Labels: special variables holding the offset where they're defined::
|
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>>,
+number>>, <<leb-128-integer,LEB128 integer>>, <<string,string>>,
<<filling,filling>>, <<variable-assignment,variable assignment>>,
<<conditional-block,conditional block>>, <<repetition-block,repetition
block>>, <<macro-expansion,macro expansion>>, and
|<<variable-assignment,Variables>>
|Mapping of variable names to integral or floating point number values.
|`init_variables` parameter of the `parse()` function.
-|One or more `--var` options.
+|One or more `--var` or `--var-str` options.
|===
The available items are:
* A <<byte-constant,constant integer>> representing one or more
constant bytes.
-* A <<literal-string,literal string>> representing a sequence of bytes
- encoding UTF-8, UTF-16, or UTF-32 data.
+* A <<literal-string,literal string>> representing a constant sequence
+ of bytes encoding UTF-8, UTF-16, UTF-32, or Latin-1 to Latin-10 data.
* A <<current-byte-order-setting,current byte order setting>> (big or
little endian).
* An <<leb128-integer,LEB128 integer>> of which the value is the result
of a {py3} expression.
+* A <<string,string>> representing a sequence of bytes encoding UTF-8,
+ UTF-16, UTF-32, or Latin-1 to Latin-10 data, and of which the value is
+ the result of a {py3} expression.
+
* A <<current-offset-setting,current offset setting>>.
* A <<current-offset-alignment,current offset alignment>>.
=== Literal string
-A _literal string_ represents the UTF-8-, UTF-16-, or UTF-32-encoded
-bytes of a string.
+A _literal string_ represents the encoded bytes of a literal string
+using the UTF-8, UTF-16, UTF-32, or Latin-1 to Latin-10 encoding.
The string to encode isn't implicitly null-terminated: use `\0` at the
end of the string to add a null character.
A literal string is:
-. **Optional**: one of the following encodings instead of UTF-8:
+. **Optional**: one of the following encodings instead of the default
+ UTF-8:
+
--
[horizontal]
-`u16be`:: UTF-16BE.
-`u16le`:: UTF-16LE.
-`u32be`:: UTF-32BE.
-`u32le`:: UTF-32LE.
+`s:u8`::
+`u8`::
+ UTF-8.
+
+`s:u16be`::
+`u16be`::
+ UTF-16BE.
+
+`s:u16le`::
+`u16le`::
+ UTF-16LE.
+
+`s:u32be`::
+`u32be`::
+ UTF-32BE.
+
+`s:u32le`::
+`u32le`::
+ UTF-32LE.
+
+`s:latin1`::
+ ISO/IEC 8859-1.
+
+`s:latin2`::
+ ISO/IEC 8859-2.
+
+`s:latin3`::
+ ISO/IEC 8859-3.
+
+`s:latin4`::
+ ISO/IEC 8859-4.
+
+`s:latin5`::
+ ISO/IEC 8859-9.
+
+`s:latin6`::
+ ISO/IEC 8859-10.
+
+`s:latin7`::
+ ISO/IEC 8859-13.
+
+`s:latin8`::
+ ISO/IEC 8859-14.
+
+`s:latin9`::
+ ISO/IEC 8859-15.
+
+`s:latin10`::
+ ISO/IEC 8859-16.
--
. The ``pass:["]`` prefix.
Input:
----
-u32be "\"illusion is the first\nof all pleasures\" 🦉"
+s:u32be "\"illusion is the first\nof all pleasures\" 🦉"
----
Output:
----
====
+====
+Input:
+
+----
+s:latin1 "Paul Piché"
+----
+
+Output:
+
+----
+50 61 75 6c 20 50 69 63 68 e9 ┆ Paul Pich•
+----
+====
+
=== Current byte order setting
This special item sets the <<cur-bo,_current byte order_>>.
----
====
+=== String
+
+A _string_ represents a variable number of bytes encoding a string which
+is the result of evaluating a {py3} expression using the UTF-8, UTF-16,
+UTF-32, or Latin-1 to Latin-10 encoding.
+
+A string has two possible forms:
+
+Encoding prefix form:: {empty}
++
+. An encoding amongst:
++
+--
+[horizontal]
+`s:u8`::
+`u8`::
+ UTF-8.
+
+`s:u16be`::
+`u16be`::
+ UTF-16BE.
+
+`s:u16le`::
+`u16le`::
+ UTF-16LE.
+
+`s:u32be`::
+`u32be`::
+ UTF-32BE.
+
+`s:u32le`::
+`u32le`::
+ UTF-32LE.
+
+`s:latin1`::
+ ISO/IEC 8859-1.
+
+`s:latin2`::
+ ISO/IEC 8859-2.
+
+`s:latin3`::
+ ISO/IEC 8859-3.
+
+`s:latin4`::
+ ISO/IEC 8859-4.
+
+`s:latin5`::
+ ISO/IEC 8859-9.
+
+`s:latin6`::
+ ISO/IEC 8859-10.
+
+`s:latin7`::
+ ISO/IEC 8859-13.
+
+`s:latin8`::
+ ISO/IEC 8859-14.
+
+`s:latin9`::
+ ISO/IEC 8859-15.
+
+`s:latin10`::
+ ISO/IEC 8859-16.
+--
+
+. The ``pass:[{]`` prefix.
+
+. A valid {py3} expression of which the evaluation result type
+ is `bool`, `int`, `float`, or `str` (the first three automatically
+ converted to `str`).
++
+For a string at some source location{nbsp}__**L**__, this expression may
+contain:
++
+--
+* The name of any <<label,label>> defined before{nbsp}__**L**__
+ which isn't within a nested group.
+* The name of any <<variable-assignment,variable>> known
+ at{nbsp}__**L**__.
+--
++
+The value of the special name `ICITTE` (`int` type) in this expression
+is the <<cur-offset,current offset>> (before encoding the string).
+
+. The `}` suffix.
+
+Encoding suffix form:: {empty}
++
+. The ``pass:[{]`` prefix.
+
+. A valid {py3} expression of which the evaluation result type
+ is `bool`, `int`, `float`, or `str` (the first three automatically
+ converted to `str`).
++
+For a string at some source location{nbsp}__**L**__, this expression may
+contain:
++
+--
+* The name of any <<label,label>> defined before{nbsp}__**L**__
+ which isn't within a nested group.
+* The name of any <<variable-assignment,variable>> known
+ at{nbsp}__**L**__.
+--
++
+The value of the special name `ICITTE` (`int` type) in this expression
+is the <<cur-offset,current offset>> (before encoding the string).
+
+. The `:` character.
+
+. A string encoding amongst:
++
+--
+[horizontal]
+`s:u8`::
+ UTF-8.
+
+`s:u16be`::
+ UTF-16BE.
+
+`s:u16le`::
+ UTF-16LE.
+
+`s:u32be`::
+ UTF-32BE.
+
+`s:u32le`::
+ UTF-32LE.
+
+`s:latin1`::
+ ISO/IEC 8859-1.
+
+`s:latin2`::
+ ISO/IEC 8859-2.
+
+`s:latin3`::
+ ISO/IEC 8859-3.
+
+`s:latin4`::
+ ISO/IEC 8859-4.
+
+`s:latin5`::
+ ISO/IEC 8859-9.
+
+`s:latin6`::
+ ISO/IEC 8859-10.
+
+`s:latin7`::
+ ISO/IEC 8859-13.
+
+`s:latin8`::
+ ISO/IEC 8859-14.
+
+`s:latin9`::
+ ISO/IEC 8859-15.
+
+`s:latin10`::
+ ISO/IEC 8859-16.
+--
+
+. The `}` suffix.
+
+====
+Input:
+
+----
+{iter = 1}
+
+!repeat 10
+ {iter : s:u8} " "
+ {iter = iter + 1}
+!end
+----
+
+Output:
+
+----
+31 20 32 20 33 20 34 20 35 20 36 20 37 20 38 20 ┆ 1 2 3 4 5 6 7 8
+39 20 31 30 20 ┆ 9 10
+----
+====
+
+====
+Input:
+
+----
+{meow = 'salut jérémie'}
+{meow.upper() : s:latin1}
+----
+
+Output:
+
+----
+53 41 4c 55 54 20 4a c9 52 c9 4d 49 45 ┆ SALUT J•R•MIE
+----
+====
+
=== Current offset setting
This special item sets the <<cur-offset,_current offset_>>.
. The `=` character.
-. A valid {py3} expression of which the evaluation result type
- is `int`, `float`, or `bool` (automatically converted to `int`).
+. A valid {py3} expression of which the evaluation result type is `int`,
+ `float`, or `bool` (automatically converted to `int`), or `str`.
+
For a variable assignment at some source location{nbsp}__**L**__, this
expression may contain:
** A <<literal-string,literal string>>.
** A <<fixed-length-number,fixed-length number>>.
** An <<leb128-integer,LEB128 integer>>.
+** A <<string,string>>.
** A <<macro-expansion,macro-expansion>>.
** A <<group,group>>.