mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

keyval: Improve some comments

Browse Source 
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <1490014548-15083-3-git-send-email-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
This commit is contained in:
Markus Armbruster 2017-03-20 13:55:45 +01:00
parent b2cd5b925c
commit fae425d74f
1 changed files with 31 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
util/keyval.c
View File

@ -21,22 +21,36 @@
* *
* Semantics defined by reduction to JSON: * Semantics defined by reduction to JSON:
* *
* key-vals is a tree of objects and arrays rooted at object R * key-vals specifies a JSON object, i.e. a tree whose root is an
* where for each key-val = key-fragment . ... = val in key-vals * object, inner nodes other than the root are objects or arrays,
* R op key-fragment op ... = val' * and leaves are strings.
* 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.
* *
* 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 * A path from the root is defined recursively:
* doesn't have one, because R.a must be an object to satisfy a.b=1 * L '.' key-fragment is a child of the node denoted by path L
* and a string to satisfy a=2. * 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. * The length of any key-fragment must be between 1 and 127.
* *
@ -64,8 +78,8 @@
/* /*
* Convert @key to a list index. * Convert @key to a list index.
* Convert all leading digits to a (non-negative) number, capped at * Convert all leading decimal digits to a (non-negative) number,
* INT_MAX. * capped at INT_MAX.
* If @end is non-null, assign a pointer to the first character after * If @end is non-null, assign a pointer to the first character after
* the number to *@end. * the number to *@end.
* Else, fail if any characters follow. * 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 * If we dropped an index >= nelt in the previous loop, this loop
* will run into the sentinel and report index @nelt missing. * will run into the sentinel and report index @nelt missing.
*/ */