Date: Sat, 13 Dec 2014 09:21:03 +0100 From: Stefan Esser <se@freebsd.org> To: Phil Shafer <phil@juniper.net> Cc: "freebsd-hackers@freebsd.org" <freebsd-hackers@freebsd.org> Subject: Re: [Patch] updated: Add JSON and XML output to pciconf (libxo support - D1206) Message-ID: <548BF6EF.2090504@freebsd.org> In-Reply-To: <201412101931.sBAJV7uk076028@idle.juniper.net> References: <201412101931.sBAJV7uk076028@idle.juniper.net>
next in thread | previous in thread | raw e-mail | index | archive | help
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 <experimental> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?548BF6EF.2090504>