[Patch] updated: Add JSON and XML output to pciconf (libxo support - D1206)

[Stefan Esser]

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