From nobody Mon Feb 9 04:45:00 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zoho.com; spf=pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 1490205431921163.80094149931267; Wed, 22 Mar 2017 10:57:11 -0700 (PDT) Received: from localhost ([::1]:52609 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cqkVS-0007DT-J8 for importer@patchew.org; Wed, 22 Mar 2017 13:57:10 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:52576) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cqkN8-0007tV-FS for qemu-devel@nongnu.org; Wed, 22 Mar 2017 13:48:36 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cqkN5-0001Jn-Ar for qemu-devel@nongnu.org; Wed, 22 Mar 2017 13:48:34 -0400 Received: from mx1.redhat.com ([209.132.183.28]:42876) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1cqkN5-0001Iy-2c for qemu-devel@nongnu.org; Wed, 22 Mar 2017 13:48:31 -0400 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id DD200C0094E6 for ; Wed, 22 Mar 2017 17:48:30 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-116-26.ams2.redhat.com [10.36.116.26]) by smtp.corp.redhat.com (Postfix) with ESMTPS id A86E97F38B for ; Wed, 22 Mar 2017 17:48:30 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 0FBCD113864C; Wed, 22 Mar 2017 18:48:28 +0100 (CET) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com DD200C0094E6 Authentication-Results: ext-mx08.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx08.extmail.prod.ext.phx2.redhat.com; spf=pass smtp.mailfrom=armbru@redhat.com DKIM-Filter: OpenDKIM Filter v2.11.0 mx1.redhat.com DD200C0094E6 From: Markus Armbruster To: qemu-devel@nongnu.org Date: Wed, 22 Mar 2017 18:48:13 +0100 Message-Id: <1490204908-26567-3-git-send-email-armbru@redhat.com> In-Reply-To: <1490204908-26567-1-git-send-email-armbru@redhat.com> References: <1490204908-26567-1-git-send-email-armbru@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.32]); Wed, 22 Mar 2017 17:48:31 +0000 (UTC) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PULL v2 for-2.9 02/17] keyval: Improve some comments X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Signed-off-by: Markus Armbruster Message-Id: <1490014548-15083-3-git-send-email-armbru@redhat.com> Reviewed-by: Eric Blake --- 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 =3D key-fragment . ... =3D val in key-vals - * R op key-fragment op ... =3D 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 =3D key-fragment '.' ... '=3D' val specifies a path from + * root to a leaf (left of '=3D'), and the leaf's value (right of + * '=3D'). * - * The equations must have a solution. Counter-example: a.b=3D1,a=3D2 - * doesn't have one, because R.a must be an object to satisfy a.b=3D1 - * and a string to satisfy a=3D2. + * 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=3D1,a=3D2 is + * not, because root.a must be an object to satisfy a.b=3D1 and a + * string to satisfy a=3D2. + * + * Array subscripts can occur in any order, but the set of + * subscripts must not have gaps. For instance, a.1=3Dv 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 @@ =20 /* * 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 *@end. * Else, fail if any characters follow. @@ -337,7 +351,8 @@ static QObject *keyval_listify(QDict *cur, GSList *key_= of_cur, Error **errp) } =20 /* - * 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 >=3D nelt in the previous loop, this loop * will run into the sentinel and report index @nelt missing. */ --=20 2.7.4