[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PULL v2 for-2.9 02/17] keyval: Improve some comments
From: |
Markus Armbruster |
Subject: |
[Qemu-devel] [PULL v2 for-2.9 02/17] keyval: Improve some comments |
Date: |
Wed, 22 Mar 2017 18:48:13 +0100 |
Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>
Reviewed-by: Eric Blake <address@hidden>
---
util/keyval.c | 47 +++++++++++++++++++++++++++++++----------------
1 file changed, 31 insertions(+), 16 deletions(-)
diff --git a/util/keyval.c b/util/keyval.c
index f646b36..46cd540 100644
--- a/util/keyval.c
+++ b/util/keyval.c
@@ -21,22 +21,36 @@
*
* Semantics defined by reduction to JSON:
*
- * key-vals is a tree of objects and arrays rooted at object R
- * where for each key-val = key-fragment . ... = val in key-vals
- * R op key-fragment op ... = val'
- * where (left-associative) op is
- * array subscript L[key-fragment] for numeric key-fragment
- * member reference L.key-fragment otherwise
- * val' is val with ',,' replaced by ','
- * and only R may be empty.
+ * key-vals specifies a JSON object, i.e. a tree whose root is an
+ * object, inner nodes other than the root are objects or arrays,
+ * and leaves are strings.
*
- * Duplicate keys are permitted; all but the last one are ignored.
+ * Each key-val = key-fragment '.' ... '=' val specifies a path from
+ * root to a leaf (left of '='), and the leaf's value (right of
+ * '=').
*
- * The equations must have a solution. Counter-example: a.b=1,a=2
- * doesn't have one, because R.a must be an object to satisfy a.b=1
- * and a string to satisfy a=2.
+ * A path from the root is defined recursively:
+ * L '.' key-fragment is a child of the node denoted by path L
+ * key-fragment is a child of the tree root
+ * If key-fragment is numeric, the parent is an array and the child
+ * is its key-fragment-th member, counting from zero.
+ * Else, the parent is an object, and the child is its member named
+ * key-fragment.
*
- * Key-fragments must be valid QAPI names or consist only of digits.
+ * This constrains inner nodes to be either array or object. The
+ * constraints must be satisfiable. Counter-example: a.b=1,a=2 is
+ * not, because root.a must be an object to satisfy a.b=1 and a
+ * string to satisfy a=2.
+ *
+ * Array subscripts can occur in any order, but the set of
+ * subscripts must not have gaps. For instance, a.1=v is not okay,
+ * because root.a[0] is missing.
+ *
+ * If multiple key-val denote the same leaf, the last one determines
+ * the value.
+ *
+ * Key-fragments must be valid QAPI names or consist only of decimal
+ * digits.
*
* The length of any key-fragment must be between 1 and 127.
*
@@ -64,8 +78,8 @@
/*
* Convert @key to a list index.
- * Convert all leading digits to a (non-negative) number, capped at
- * INT_MAX.
+ * Convert all leading decimal digits to a (non-negative) number,
+ * capped at INT_MAX.
* If @end is non-null, assign a pointer to the first character after
* the number to address@hidden
* Else, fail if any characters follow.
@@ -337,7 +351,8 @@ static QObject *keyval_listify(QDict *cur, GSList
*key_of_cur, Error **errp)
}
/*
- * Make a list from @elt[], reporting any missing elements.
+ * Make a list from @elt[], reporting the first missing element,
+ * if any.
* If we dropped an index >= nelt in the previous loop, this loop
* will run into the sentinel and report index @nelt missing.
*/
--
2.7.4
- [Qemu-devel] [PULL v2 for-2.9 00/17] QAPI patches for 2017-03-22, Markus Armbruster, 2017/03/22
- [Qemu-devel] [PULL v2 for-2.9 11/17] qapi2texi: Fix translation of *strong* and _emphasized_, Markus Armbruster, 2017/03/22
- [Qemu-devel] [PULL v2 for-2.9 09/17] tests/qapi-schema: Make test-qapi.py print docs again, Markus Armbruster, 2017/03/22
- [Qemu-devel] [PULL v2 for-2.9 07/17] qapi2texi: Fix to actually fail when 'doc-required' is false, Markus Armbruster, 2017/03/22
- [Qemu-devel] [PULL v2 for-2.9 12/17] qapi: Fix string input visitor regression for empty lists, Markus Armbruster, 2017/03/22
- [Qemu-devel] [PULL v2 for-2.9 02/17] keyval: Improve some comments,
Markus Armbruster <=
- [Qemu-devel] [PULL v2 for-2.9 03/17] test-keyval: Cover alternate and 'any' type, Markus Armbruster, 2017/03/22
- [Qemu-devel] [PULL v2 for-2.9 14/17] test-qobject-input-visitor: Cover visit_type_uint64(), Markus Armbruster, 2017/03/22
- [Qemu-devel] [PULL v2 for-2.9 08/17] qapi: Drop unused QAPIDoc member optional, Markus Armbruster, 2017/03/22
- [Qemu-devel] [PULL v2 for-2.9 01/17] test-keyval: Tweaks to improve list coverage, Markus Armbruster, 2017/03/22
- [Qemu-devel] [PULL v2 for-2.9 04/17] keyval: Document issues with 'any' and alternate types, Markus Armbruster, 2017/03/22
- [Qemu-devel] [PULL v2 for-2.9 06/17] qapi: Drop excessive Make dependencies on qapi2texi.py, Markus Armbruster, 2017/03/22
- [Qemu-devel] [PULL v2 for-2.9 13/17] Revert "hostmem: fix QEMU crash by 'info memdev'", Markus Armbruster, 2017/03/22
- [Qemu-devel] [PULL v2 for-2.9 17/17] qapi: Fix QemuOpts visitor regression on unvisited input, Markus Armbruster, 2017/03/22