Support for annotations in the new UNOIDL format

...used for now to transport @deprecated information.

Also, improve Idx-String (formerly Idx-Name, but also used for UTF-8 annotations
now) format, using the 0x80000000 for the indirection rather than the base case.
(And the README erroneously used "Offset of" Idx-String all over the place.)

Change-Id: I7003b1558ab536a11a9af308f9b16a7ef8840792

1 files changed, 79 insertions, 41 deletions

diff --git a/unoidl/README b/unoidl/README
index 5daff7a618c2..84246e9db876 100644
--- a/unoidl/README
+++ b/unoidl/README
@@ -27,6 +27,18 @@ quantities are stored LSB first, without alignment requirements.  Offsets are
 considered a limitation in practice (and avoids unnecessary bloat compared to
 64 bit offsets).
 
+Annotations can be added for (non-module) entities and certain parts of such
+entities (e.g., both for an interface type definition and for a direct method of
+an interface type definition; the idea is that it can be added for direct parts
+that forma a "many-to-one" relationship; there is a tradeoff between generality
+of concept and size of representation, esp. for the C++ representation types in
+namespace unoidl) and consist of arbitrary sequences of name/value strings.
+Each name/value string is encoded as a single UTF-8 string containing a name (an
+arbitrary sequence of Unicode code points not containing U+003D EQUALS SIGN),
+optionally followed by U+003D EQUALS SIGN and a value (an abritrary sequence of
+Unicode code points).  The only annotation name currently in use is "deprecated"
+(without a value).
+
 The following definitions are used throughout:
 
 * UInt16: 2-byte value, LSB first
@@ -34,10 +46,12 @@ The following definitions are used throughout:
 * UInt64: 8-byte value, LSB first
 * Offset: UInt32 value, counting bytes from start of file
 * NUL-Name: zero or more non-NUL US-ASCII bytes followed by a NUL byte
-* Len-Name: UInt32 number of characters, with 0x80000000 bit 1, followed by that
-   many (- 0x80000000) US-ASCII bytes
-* Idx-Name: either an Offset (with 0x80000000 bit 0) of a Len-Name, or a
-   Len-Name
+* Len-String: UInt32 number of characters, with 0x80000000 bit 0, followed by
+   that many US-ASCII (for UNOIDL related names) resp. UTF-8 (for annotations)
+   bytes
+* Idx-String: either an Offset (with 0x80000000 bit 1) of a Len-String, or a
+   Len-String
+* Annotations: UInt32 number N of annotations followed by N * Idx-String
 * Entry: Offset of NUL-Name followed by Offset of payload
 * Map: zero or more Entries
 
@@ -68,7 +82,7 @@ Layout of per-entry payload in the root or a module Map:
 
 ** otherwise:
 *** 0x80 bit: 1 if published
-*** 0x40 bit: 1 if deprecated
+*** 0x40 bit: 1 if annotated
 *** 0x20 bit: flag (may only be 1 for certain kinds, see below)
 *** remaining bits:
 
@@ -76,67 +90,77 @@ Layout of per-entry payload in the root or a module Map:
 ***** followed by:
 ****** UInt32 number N1 of members
 ****** N1 * tuple of:
-******* Offset of Idx-Name
+******* Idx-String
 ******* UInt32
+******* if annotated: Annotations
 
 **** 2: plain struct type (with base if flag is 1)
 ***** followed by:
-****** if "with base": Offset of Idx-Name
+****** if "with base": Idx-String
 ****** UInt32 number N1 of direct members
 ****** N1 * tuple of:
-******* Offset of Idx-Name name
-******* Offset of Idx-Name type
+******* Idx-String name
+******* Idx-String type
+******* if annotated: Annotations
 
 **** 3: polymorphic struct type template
 ***** followed by:
 ****** UInt32 number N1 of type parameters
-****** N1 * Offset of Idx-Name
+****** N1 * Idx-String
 ****** UInt32 number N2 of members
 ****** N2 * tuple of:
 ******* kind byte: 0x01 bit is 1 if parameterized type
-******* Offset of Idx-Name name
-******* Offset of Idx-Name type
+******* Idx-String name
+******* Idx-String type
+******* if annotated: Annotations
 
 **** 4: exception type (with base if flag is 1)
 ***** followed by:
-****** if "with base": Offset of Idx-Name
+****** if "with base": Idx-String
 ****** UInt32 number N1 of direct members
 ****** N1 * tuple of:
-******* Offset of Idx-Name name
-******* Offset of Idx-Name type
+******* Idx-String name
+******* Idx-String type
+******* if annotated: Annotations
 
 **** 5: interface type
 ***** followed by:
 ****** UInt32 number N1 of direct mandatory bases
-****** N1 * Offset of Idx-Name
+****** N1 * tuple of:
+******* Idx-String
+******* if annotated: Annotations
 ****** UInt32 number N2 of direct optional bases
-****** N2 * Offset of Idx-Name
+****** N2 * tuple of:
+******* Idx-String
+******* if annotated: Annotations
 ****** UInt32 number N3 of direct attributes
 ****** N3 * tuple of:
 ******* kind byte:
 ******** 0x02 bit: 1 if read-only
 ******** 0x01 bit: 1 if bound
-******* Offset of Idx-Name name
-******* Offset of Idx-Name type
+******* Idx-String name
+******* Idx-String type
 ******* UInt32 number N4 of get exceptions
-******* N4 * Offset of Idx-Name
+******* N4 * Idx-String
 ******* UInt32 number N5 of set exceptions
-******* N5 * Offset of Idx-Name
+******* N5 * Idx-String
+******* if annotated: Annotations
 ****** UInt32 number N6 of direct methods
 ****** N6 * tuple of:
-******* Offset of Idx-Name name
-******* Offset of Idx-Name return type
+******* Idx-String name
+******* Idx-String return type
 ******* UInt32 number N7 of parameters
 ******* N7 * tuple of:
 ******** direction byte: 0 for in, 1 for out, 2 for in-out
-******** Offset of Idx-Name name
-******** Offset of Idx-Name type
+******** Idx-String name
+******** Idx-String type
 ******* UInt32 number N8 of exceptions
-******* N8 * Offset of Idx-Name
+******* N8 * Idx-String
+******* if annotated: Annotations
 
 **** 6: typedef
 ***** followed by:
-****** Offset of Idx-Name
+****** Idx-String
 
 **** 7: constant group
 ***** followed by:
@@ -145,29 +169,38 @@ Layout of per-entry payload in the root or a module Map:
 
 **** 8: single-interface--based service (with default constructor if flag is 1)
 ***** followed by:
-****** Offset of Idx-Name
+****** Idx-String
 ****** if not "with default constructor":
 ******* UInt32 number N1 of constructors
 ******* N1 * tuple of:
-******** Offset of Idx-Name
+******** Idx-String
 ******** UInt32 number N2 of parameters
 ******** N2 * tuple of
 ********* kind byte: 0x04 bit is 1 if rest parameter
-********* Offset of Idx-Name name
-********* Offset of Idx-Name type
+********* Idx-String name
+********* Idx-String type
 ******** UInt32 number N3 of exceptions
-******** N3 * Offset of Idx-Name
+******** N3 * Idx-String
+******** if annotated: Annotations
 
 **** 9: accumulation-based service
 ***** followed by:
 ****** UInt32 number N1 of direct mandatory base services
-****** N1 * Offset of Idx-Name
+****** N1 * tuple of:
+******* Idx-String
+******* if annotated: Annotations
 ****** UInt32 number N2 of direct optional base services
-****** N2 * Offset of Idx-Name
+****** N2 * tuple of:
+******* Idx-String
+******* if annotated: Annotations
 ****** UInt32 number N3 of direct mandatory base interfaces
-****** N3 * Offset of Idx-Name
+****** N3 * tuple of:
+******* Idx-String
+******* if annotated: Annotations
 ****** UInt32 number N4 of direct optional base interfaces
-****** N4 * Offset of Idx-Name
+****** N4 * tuple of:
+******* Idx-String
+******* if annotated: Annotations
 ****** UInt32 number N5 of direct properties
 ****** N5 * tuple of:
 ******* UInt16 kind:
@@ -180,21 +213,24 @@ Layout of per-entry payload in the root or a module Map:
 ******** 0x0004 bit: 1 if constrained
 ******** 0x0002 bit: 1 if bound
 ******** 0x0001 bit: 1 if maybevoid
-******* Offset of Idx-Name name
-******* Offset of Idx-Name type
+******* Idx-String name
+******* Idx-String type
+******* if annotated: Annotations
 
 **** 10: interface-based singleton
 ***** followed by:
-****** Offset of Idx-Name
+****** Idx-String
 
 **** 11: service-based singleton
 ***** followed by:
-****** Offset of Idx-Name
+****** Idx-String
+
+*** if annotated, followed by: Annotations
 
 Layout of per-entry payload in a constant group Map:
 
 * kind byte:
-** 0x80 bit: 1 if deprecated
+** 0x80 bit: 1 if annotated
 ** remaining bits:
 
 *** 0: BOOLEAN
@@ -228,3 +264,5 @@ Layout of per-entry payload in a constant group Map:
 *** 9: DOUBLE
 **** followed by 8-byte value, representing values in ISO 60599 binary64 format,
       LSB first
+
+* if annotated, followed by: Annotations