Document format string verification (queryf, sprintf, etc), and document HH\FormatString + how to implement it

[fredemmott]

[justinwray]

@fredemmott / All,

Is there any update on HH\FormatString that can be shared at this time?

[fredemmott]

It's not secret, we've just not had time to write proper documentation. I'll see if I can volunteer someone.

Short version:

• the typechecker can understand sprintf-like functions
• FormatString<T> is a string, but must be a literal string, not a variable, function return, or other expression
• T is an interface that defines the pattern

As for the format of these interfaces:

• a function named format_s() defines %s
• a function named format_upcase_s() defines %S (not format_S as function names are not case-sensitive in PHP, or in runtime in Hack`
• for characters that aren't valid in function names, use format_0xHH where HH is the ascii code in hex - eg format_0x25 defines %%
• there are zero or one parameters.
  • If there is one, one of the variadics is consumed - e.g. %% does not consume, but %s does
  • the parameter type becomes a type restriction on the variadic argument
  • parameter names are irrelevant
• functions return a string if they're the end of a format placeholder
• functions return another interface if there are more characters required - eg for %Ls (list of strings), the outermost interface has function format_upcase_l(): InnerInterface and InnerInterface has function format_s(string %s): string

These interfaces are only used for the format string magic - no object ever implements them.

Example interfaces:

• most printf-like things are FormatString<PlainSprintf>: https://github.com/facebook/hhvm/blob/7625626aa476421ff9c2aca91af8ea3fe4e16102/hphp/hack/hhi/printf.hhi#L41
• queryf() in the async mysql extension uses a FormatString<HH\SQLFormatter>: https://github.com/facebook/hhvm/blob/7625626aa476421ff9c2aca91af8ea3fe4e16102/hphp/hack/hhi/stdlib/builtins_async_mysql.hhi#L267

[RexJaeschke]

I've documented the format string verification aspects in the revised version of the Hack tutorial. I'm assuming the implementation aspects are not intended to be part of that tutorial.

[fredemmott]

Re-opening, do want the impelmentation/definition aspects documented somewhere