@node Blobs
-@anchor{BLOB}
@cindex BLOB
@cindex chunk
@section Blobs
in a streaming way, when data may not fit in memory.
64-bit big-endian integer follows the BLOB tag, setting the following
-chunks payload size (+1). Then come one or more @ref{BIN} strings with
-the chunk-length payload. All of them, except for the last one, must
-have fixed chunk length payload. Last terminating string's payload must
-be shorter.
+chunks payload size (+1). Then come one or more @ref{Strings, BIN}
+strings with the chunk-length payload. All of them, except for the last
+one, must have fixed chunk length payload. Last terminating string's
+payload must be shorter.
Data format definition must specify exact chunk size expected to be
used, if it needs deterministic encoding.
@multitable {dec} {hex} {12345678} {len} {float256}
@headitem dec @tab hex @tab bin @tab vlen @tab description
-@item 000 @tab 00 @tab @code{00000000} @tab 0 @tab @ref{Containers, EOC}
+@item 000 @tab 00 @tab @code{00000000} @tab 0 @tab @ref{LIST, EOC}
@item 001 @tab 01 @tab @code{00000001} @tab 0 @tab @ref{Primitives, NIL}
@item 002 @tab 02 @tab @code{00000010} @tab 0 @tab @ref{Primitives, FALSE}
@item 003 @tab 03 @tab @code{00000011} @tab 0 @tab @ref{Primitives, TRUE}
@item 004 @tab 04 @tab @code{00000100} @tab 16 @tab @ref{UUID}
@item [...]
-@item 008 @tab 08 @tab @code{00001000} @tab 0 @tab @ref{Containers, LIST}
-@item 009 @tab 09 @tab @code{00001001} @tab 0 @tab @ref{Containers, MAP}
+@item 008 @tab 08 @tab @code{00001000} @tab 0 @tab @ref{LIST}
+@item 009 @tab 09 @tab @code{00001001} @tab 0 @tab @ref{MAP}
@item 010 @tab 0A @tab @code{00001010} @tab
@item 011 @tab 0B @tab @code{00001011} @tab 8+~ @tab @ref{Blobs, BLOB}
@item 012 @tab 0C @tab @code{00001100} @tab 1+~ @tab @ref{Integers, +INT}
@include encoding/float.texi
@include encoding/tai64.texi
@include encoding/magic.texi
-@include encoding/cont.texi
+@include encoding/list.texi
+@include encoding/map.texi
@include encoding/blob.texi
--- /dev/null
+@node LIST
+@cindex EOC
+@section LIST
+
+LIST contains a concatenation of items of arbitrary type, terminated by
+EOC atom.
+
+@verbatim
+LIST [ITEM0 || ITEM1 || ...] EOC
+@end verbatim
+
+Example representations:
+
+@multitable @columnfractions .5 .5
+
+@item LIST[] @tab @code{08 00}
+@item LIST[INT(123) FALSE] @tab @code{08 0C817B 02 00}
+
+@end multitable
-@node Containers
-@cindex containers
-@section Containers
-
-Containers do not have any explicit length, but are terminated by EOC
-(end of contents) tag.
-
-@anchor{LIST}
-@cindex LIST
-@cindex EOC
-LIST contains a concatenation of items of arbitrary type.
-
-@verbatim
-LIST [ITEM0 || ITEM1 || ...] EOC
-@end verbatim
-
-@anchor{MAP}
+@node MAP
@cindex MAP
+@section MAP
+
MAP contains concatenation of @ref{Strings, STR(key)}-value pairs. Keys
@strong{must} be non-empty, unique and length-first bytewise ascending ordered.
@multitable @columnfractions .5 .5
-@item LIST[] @tab @code{08 00}
-@item LIST[INT(123) FALSE] @tab @code{08 0C817B 02 00}
@item MAP[foo: LIST["bar"]] @tab @code{09 C3666F6F 08 C3626172 00 00}
@item SET[sig, dh] @tab @code{09 C26468 01 C3736967 01 00}
@end multitable
+
@node Primitives
-@anchor{NIL}
@cindex NIL
@cindex FALSE
@cindex TRUE
@node Strings
-@anchor{BIN}
@cindex BIN
@cindex STR
@section Strings
@multitable {dec} {hex} {12345678} {len} {float256}
@headitem dec @tab hex @tab bin @tab vlen @tab description
-@item 000 @tab 00 @tab @code{00000000} @tab 0 @tab @ref{Containers, EOC}
+@item 000 @tab 00 @tab @code{00000000} @tab 0 @tab @ref{LIST, EOC}
@item 001 @tab 01 @tab @code{00000001} @tab 0 @tab @ref{Primitives, NIL}
@item 002 @tab 02 @tab @code{00000010} @tab 0 @tab @ref{Primitives, FALSE}
@item 003 @tab 03 @tab @code{00000011} @tab 0 @tab @ref{Primitives, TRUE}
@item 005 @tab 05 @tab @code{00000101} @tab 0 @tab
@item 006 @tab 06 @tab @code{00000110} @tab 0 @tab
@item 007 @tab 07 @tab @code{00000111} @tab 0 @tab
-@item 008 @tab 08 @tab @code{00001000} @tab 0 @tab @ref{Containers, LIST}
-@item 009 @tab 09 @tab @code{00001001} @tab 0 @tab @ref{Containers, MAP}
+@item 008 @tab 08 @tab @code{00001000} @tab 0 @tab @ref{LIST}
+@item 009 @tab 09 @tab @code{00001001} @tab 0 @tab @ref{MAP}
@item 010 @tab 0A @tab @code{00001010} @tab 0 @tab
@item 011 @tab 0B @tab @code{00001011} @tab 8+~ @tab @ref{Blobs, BLOB}
@item 012 @tab 0C @tab @code{00001100} @tab 1+~ @tab @ref{Integers, +INT}
For being able to streamingly generate the serialised data, you have to
worry about @ref{MAP}'s keys ordering. Remember that it is length-first one.
-By default binary data is expected to be encoded as @ref{BIN}. If you
-expect to deal with huge amounts of data, then probably you should use
-the @ref{BLOB} type. Generally you have to differentiate field names for
-ordinary strings and blobs.
+By default binary data is expected to be encoded as @ref{Strings, BIN}.
+If you expect to deal with huge amounts of data, then probably you
+should use the @ref{Blobs, BLOB} type. Generally you have to
+differentiate field names for ordinary strings and blobs.
For relatively small structures it could be wise to use reasonably short
key names. However it may be difficult and not obvious to keep the
If you really desire more compact encoding, even agree to use schema
definitions, then think about replacing MAPs with @ref{LIST}s. Non-present
-values can be indicated by @ref{NIL} tag.
+values can be indicated by @ref{Primitives, NIL} tag.