[FFmpeg-devel] [RFC] Shaping the AVTextFormat API Surface

[softworkz .]

Hi Stefano, Andreas, Nicolas
and of course, anybody who's interested in the AVTextFormat APIs,


let me start by saying that I have no intention to rush the 
publicization of those APIs. I think there's still a way to go.
But it's also true that when you don't have a clear understanding
of where you actually want to go, you'll hardly arrive there.

At the implementation level, I sensed that "you" ("FFmpeg")
are following some principles which are somewhat contradictive to 
those that I'm usually adhering to (e.g. "parameter validation
being a responsibility of the call site, crashing otherwise 
being acceptable"). Nonetheless, I'm the one who has to adapt,
and I'm not going to question that.

I'm addressing this to the three of you, due to your review 
comments and while I wouldn't call them contradictive, these
are heading into slightly different directions (removing 
checks altogether, replacing with assertions or printing a log
message in cases).
The one personal thought that I'd like to add, is that I 
think that parameter treatment (which checks to apply
or not) should depend on the access level of a specific API,
whether it's public, internal or private. That's something
where we don't have a plan for yet.

The AVTextFormatContext structure is all open at the moment,
means it gives everybody access to everything:

- You can call the text format api functions
- You can access the section definitions, the BPrint buffers
  and all other state and config values
- You can access and invoke the AVTextFormatter directly via
  its registered functions
- You can access AVTextWriterContext and the writers
  directly, again allowing direct invocation of their 
  functions

I did that intentionally to avoid any blockage during 
migration and also for being in a position later (=now)
where everything remains doable. 
Now that we've approached at this point, it would probably
be good to come to a clearer picture of the intended 
directions for the API.
Based on that, it should be easier to determine consistent
patterns for parameter validation for each category of API
functions - then I can apply that once and for all, 
cleanly and consistently everywhere.


This is how I'd categorize the current functions:


AVTextFormatter Implementations

- print_section_header
- print_section_footer
- print_integer
- print_string

(default, compact, csv, json, xml, ini, etc.)


AVTextWriter Implementations

- writer_w8
- writer_put_str
- writer_printf

(avio, stdout, buffer)
        

TextFormat API

- avtext_context_open
- avtext_context_close
- avtext_print_section_header
- avtext_print_section_footer
- avtext_print_integer
- avtext_print_integer_flags
- avtext_print_string
- avtext_print_unit_int
- avtext_print_rational
- avtext_print_time
- avtext_print_ts
- avtext_print_data
- avtext_print_data_hash
- avtext_print_integers
- avtext_get_formatter_by_name


TextWriter API

- avtextwriter_context_open
- avtextwriter_context_close
- avtextwriter_create_stdout
- avtextwriter_create_avio
- avtextwriter_create_file
- avtextwriter_create_buffer


Please let me know what you think,
thanks,
sw