Re: [PATCH] Strbuf documentation: document most functions

["René Scharfe" <rene.scharfe@lsrfire.ath.cx>]

Miklos Vajna schrieb:
> Actually this is a bit of request for help, I haven't figured out what
> strbuf_expand() does [...]

It can be used to expand a format string containing placeholders.  To
that end, it parses the string and calls the specified function for
every percent sign found.

The callback function is given a pointer to the character after the '%'
and a pointer to the struct strbuf.  It is expected to add the expanded
version of the placeholder to the strbuf, e.g. to add a newline
character if the letter 'n' appears after a '%'.  The function returns
the length of the placeholder recognized and strbuf_expand skips over it.

All other characters (non-percent and not skipped ones) are copied
verbatim to the strbuf.  If the callback returned zero, meaning that the
placeholder is unknown, then the percent sign is copied, too.

In order to facilitate caching and to make it possible to give
parameters to the callback, strbuf_expand passes a context pointer,
which can be used by the programmer of the callback as she sees fit.

You can see it in action in pretty.c, where it expands --pretty=format:
placeholder strings.  The callback may be a bit heavy for a first
encounter, though. ;-)

René