[waffle] [wflinfo] [RFC] platform-specific info from wflinfo

[Jordan Justen]

On 2015-02-20 12:58:07, Chad Versace wrote:
> On 02/17/2015 11:30 PM, Jordan Justen wrote:
> > On 2015-02-10 12:09:05, Chad Versace wrote:
> >> I prefer "core" too. Not for the sake of less code, but because I like
> >> the idea of it being available as core API.
> > 
> > This surprised me a bit. I wouldn't think of the waffle library
> > wanting to embed a bunch of strings to fulfill such an API.
> 
> Embedding string? I don't understand. Your proposal needs embedded
> strings too: the strings for the key values.
> 
> If Waffle provides the display info in one big string or in a sequence
> of little strings, as you propose, the same key strings need to be
> embedded into the library. Am I missing something?

You are correct.

While, I was somewhat surpised about adding it to the waffle API, my
idea was not an attempt to limit the string or code data added to
waffle library to support this. It was just a discussion of what a
good API might look like if we did add it.

> > Anyway... how about this:
> > 
> > char**
> > waffle_display_info_strings(struct waffle_display *self, bool verbose);
> > 
> > The returned array of strings could have this property:
> > 
> > First look for a key string pointer. If it is NULL, then you are done.
> > If you find non-NULL key string pointer then search for 0 or more
> > non-NULL value string pointers. When a NULL pointer is seen, go back
> > to looking for a key string pointer.
> > 
> > I've attached an example program that sort of emulates wflinfo...
> > 
> > This would allow the consumer to use comma separation and/or line
> > breaks as desired.
> 
> For the sake of apps who want to dump the info to a log file or to
> the console and get on
> with their lives, I think the default output format should be a
> single, giant string. But, as we're discovering in this conversation,
> a single giant string might not be appropriate as a one-size-fits-all format.
> I believe we can have it both ways, though, by adding some optional parameters
> to the API.
> 
>   void*
>   waffle_display_get_info(struct waffle_display *dpy,
>                           enum waffle_display_info_format format,
>                           uint32_t flags);
> 
> Then we have the ability to define API like this:
> 
>    // Returns a single, string suitable for log output. The return value
>    // must be cast to `char*`. One valid flag is currently defined for this
>    // format, WAFFLE_DISPLAY_INFO_VERBOSE_BIT.
>    waffle_display_get_info(dpy, WAFFLE_DISPLAY_INFO_FORMAT_SIMPLE, 0)
> 
>    // Returns Jordan array of strings. The return value must be cast to `char**`.
>    // One valid flag is currently defined for this format,
>    // WAFFLE_DISPLAY_INFO_VERBOSE_BIT.
>    waffle_display_get_info(dpy, WAFFLE_DISPLAY_INFO_FORMAT_JORDAN, 0);
>    
>    // Returns a JSON string. The return valud must be cast to `char*`. Two
>    // flags are currently defined for this format: WAFFLE_DISPLAY_INFO_VERBOSE_BIT
>    // and WAFFLE_DISPLAY_INFO_INDENT_BIT.
>    waffle_display_get_info(dpy, WAFFLE_DISPLAY_INFO_FORMAT_JSON, 0);
> 
> Of course, the "simple" and "jordan" formats will be the first ones implemented.
> People can implement other formats in the future. (The JSON format, I'm just
> using that as a hypothetical example.)
> 
> Do you think this is a good compromise between usability and extensibility? Does
> my proposal lack some important knob you think is needed? Or is my proposal just
> overall a bad idea?

My idea was just to define a one-time API that left presentation of
the strings to the user of the library. Therefore, the Core API
wouldn't ever need to change past that point. It was also an attempt
to make it fairly easy to iterate through the results.

One example of trouble we might get into could be
WAFFLE_DISPLAY_INFO_FORMAT_GLXINFO. Meaning we try to comma separate
and break lines.

Except, we wouldn't know the best line length to use for breaking
lines. In that case it more likely the application could best format
it. (Assuming it was able to read the console text resolution.)

But, I have to admit, your idea probably would be pretty helpful to
some applications. For example, JSON would probably be used by piglit.

Assuming you don't think the string pointers output is too horribly
complex to document, then this seems like a good set to consider:
* WAFFLE_DISPLAY_INFO_FORMAT_STRING_POINTERS
* WAFFLE_DISPLAY_INFO_FORMAT_TEXT
* WAFFLE_DISPLAY_INFO_FORMAT_JSON
* WAFFLE_DISPLAY_INFO_FORMAT_XML
* WAFFLE_DISPLAY_INFO_FORMAT_CSV (Eh, I'm not sure I like this one.)

The last 4 would be easy to implement based on the first.

This set seems like enough where we could avoid the need to add any
more formats.

-Jordan