From owner-freebsd-hackers@FreeBSD.ORG Sat Dec 13 08:21:22 2014 Return-Path: Delivered-To: freebsd-hackers@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 69B248BD; Sat, 13 Dec 2014 08:21:22 +0000 (UTC) Received: from mailout12.t-online.de (mailout12.t-online.de [194.25.134.22]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "mailout00.t-online.de", Issuer "TeleSec ServerPass DE-1" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 1711D9DB; Sat, 13 Dec 2014 08:21:21 +0000 (UTC) Received: from fwd13.aul.t-online.de (fwd13.aul.t-online.de [172.20.27.62]) by mailout12.t-online.de (Postfix) with SMTP id AB8F0304128; Sat, 13 Dec 2014 09:21:12 +0100 (CET) Received: from [192.168.119.11] (bN6MtsZBoh6Q6GsrbZ6uWxSB3eEUB6U8OCBeTQAP+gkr6ZSYVtW8SFYTlYPusdWZvX@[84.154.99.91]) by fwd13.t-online.de with (TLSv1.2:ECDHE-RSA-AES256-SHA encrypted) esmtp id 1Xzhwr-2ogjJY0; Sat, 13 Dec 2014 09:21:09 +0100 Message-ID: <548BF6EF.2090504@freebsd.org> Date: Sat, 13 Dec 2014 09:21:03 +0100 From: Stefan Esser User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:31.0) Gecko/20100101 Thunderbird/31.3.0 MIME-Version: 1.0 To: Phil Shafer Subject: Re: [Patch] updated: Add JSON and XML output to pciconf (libxo support - D1206) References: <201412101931.sBAJV7uk076028@idle.juniper.net> In-Reply-To: <201412101931.sBAJV7uk076028@idle.juniper.net> Content-Type: text/plain; charset=iso-8859-15 Content-Transfer-Encoding: 7bit X-ID: bN6MtsZBoh6Q6GsrbZ6uWxSB3eEUB6U8OCBeTQAP+gkr6ZSYVtW8SFYTlYPusdWZvX X-TOI-MSGID: 0778b85e-33ee-4700-be1a-149277f48d12 Cc: "freebsd-hackers@freebsd.org" X-BeenThere: freebsd-hackers@freebsd.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: Technical Discussions relating to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 13 Dec 2014 08:21:22 -0000 Am 10.12.2014 um 20:31 schrieb Phil Shafer: > Stefan Esser writes: >> It seems, that libxo/xo.h depends on stdio.h (or at least >> stdarg.h) for functions that use FILE or varargs. This is >> not mentioned in the respective man-pages for the affected >> functions (and I think it should be ...). > > I'll fix that. Hi Phil, one more nit: The man page for xo_open_container seems to be truncated (no "ADDITIONAL DOCUMENTATION", "SEE ALSO", ...). And I did not find any documenation of DTRT in the man pages, but only in the HTML docs (in a somewhat hidden place, since you need to know it is below "Representing Hierarchy" ...). >> Is there a description of the rules, which decide whether >> quotes are put around JSON formatted information elements. >> It seems, for example, that use of %d in format strings >> suppresses quotes, which was unexpected, if the format is >> e.g. "xyz%d" (which is a string, despite the %d ...). >> And formatted output that contains blanks within the field >> is probably also a string (even "%d %d", hmmm, but "%d.%d" >> might be a number ...). > > http://juniper.github.io/libxo/libxo-manual.html#the-quotes-modifier-q > > Quotes default to on for strings, off for others. Yes, that's what I had expected. But in fact I needed to put quite a few "q:" or "n:" to get the JSON output correctly quoted. I'll see that I create a file with a few test cases. >> But I have to admit, that I do not really know the rules for >> quotes around data fields in JSON. (E.g. must I write "true" >> to represent a string value of "true", or could I also use >> true without quotes to represent a truth value? What do >> parsers do if there are unquoted words or words separated >> by blanks?) > > JSON uses "true", "false", and "null" (without quotes) > as unquoted tokens. If you want a boolean, you'll need: > > xo_emit("{n:valid/%s}", valid ? "true" : "false"); Hmmm, but what will the "reader" of the JSON file expect? Is it good practice to have libxo output booleans instead of strings, if these are the only possible values? Will a JSON parser automatically convert them to strings, if an unquoted true or false is read and a strings is expected? (Sorry, I have bno experience with JSON parsers ...) >> Are there any plans for a versioning scheme for XO extended >> programs. E.g. if I need to change some of the elements or >> labels in pciconf, how do I include the information about the >> file schema being the old or the new one in an output file. >> I could f.i. just add an xo_emit(":e/schema-version/1") at >> the head of the file, to make the file format version explicit >> in the generated output ... > > No plans. In practice, your tags become an API, and changes > to that API require an attitude of "don't break your users". > Most users won't check versioning information. While it is probably true, that most users do not want to check for different format versions, I think there should be a canonical way to provide such information. I have thought about putting around the pciconf output, just to let people know, that the format is expected to change until I understand the semantics of all fields (e.g. in the PCIe (extended) capabilities section). > Please let me know what's unclear from the docs and I'll > try to improve them. Thanks, I'll do. Best regards, STefan