.Dd Aug 19, 2012
.Dt XPRINTF 5
.Os Darwin
.Sh NAME
.Nm xprintf
.Nd extensible printf
.Sh SYNOPSIS
.In printf.h
.Ft "typedef int"
.Fn printf_arginfo_function "const struct printf_info *info" "size_t n" "int *argtypes"
.Ft "typedef int"
.Fn printf_function "FILE *stream" "const struct printf_info *info" "const void *const *args"
.Sh DESCRIPTION
The standard
.Xr printf 3
family of routines provides a convenient way to convert one or more arguments
to various forms for output, under the control of a format string.
The format string may contain any number of conversion specifications, which
start with the
.Sq Li %
character and end with a conversion specifier character (like
.Sq Li d
or
.Sq Li f ) ,
with conversion flag characters in-between.
.Pp
Extensible printf is an enhancement that allows adding new (user-defined)
conversion specifiers, or modifying/removing existing ones.
The implementation of extensible printf in Mac OS X is derived from the
FreeBSD version, which is based on the one in GNU libc (GLIBC).
Documentation for the GLIBC version is available at:
.Pp
.Li http://www.gnu.org/software/libc/manual/html_node/Customizing-Printf.html
.Pp
The main problem with the usual forms of extensible printf is that
changes to
.Xr printf 3
are program-wide.
But this is unsafe, since frameworks,
libraries or some other thread could change printf behavior in ways
unexpected by the main program, or the latter could unexpectedly affect the
former.
.Pp
So instead, the implementation used in Mac OS X makes
changes to conversion specifiers within printf domains,
which are independent structures containing the specifier definitions.
These domains are created as described in
.Xr xprintf_domain 3 ,
and once set up, it can be passed to a
.Xr xprintf 3
variant along with the format string and arguments to generate output.
The standard
.Xr printf 3
behavior is never affected.
.Pp
To define a new conversion specifier, two function typedefs are defined, and
the user must provide two functions based on these typedefs.
These functions will get called from extensible printf while processing
the corresponding conversion specification.
.Pp
During the first of three phases of extensible printf processing, the format
string is parsed, and for each conversion specification, a
.Vt struct printf_info
is created, containing the option flags specified in the
conversion specification as well as other settings.
Important fields in
.Vt struct printf_info
are:
.Bl -tag -width ".Va is_long_double"
.It Va alt
Boolean value whether the
.Sq Li #
flag was specified.
.It Va context
A
.Vt void *
pointer to arbitrary data specified in the original call to
.Xr register_printf_domain_function 3 .
.It Va group
Boolean value whether the
.Sq Li '
flag was specified.
.It Va is_char
Boolean value whether the
.Sq Li hh
flag was specified.
.It Va is_intmax
Boolean value whether the
.Sq Li j
flag was specified.
.It Va is_long
Boolean value whether the
.Sq Li l
flag was specified.
.It Va is_long_double
Boolean value whether the
.Sq Li L
or
.Sq Li ll
flags were specified.
.It Va is_ptrdiff
Boolean value whether the
.Sq Li t
flag was specified.
.It Va is_quad
Boolean value whether the
.Sq Li q
flag was specified.
.It Va is_short
Boolean value whether the
.Sq Li h
flag was specified.
.It Va is_size
Boolean value whether the
.Sq Li z
flag was specified.
.It Va is_vec
Boolean value whether the
.Sq Li v
flag was specified.
.It Va left
Boolean value whether the
.Sq Li -
flag was specified.
.It Va loc
The extended locale (see
.Xr xlocale 3 )
specified by the extensible printf caller (never
.Dv NULL ) .
.It Va pad
The padding character; either
.Sq Li 0
or space.
.It Va prec
The value of the optional precision.
-1 means the precision was unspecified.
.It Va showsign
Boolean value whether the
.Sq Li +
flag was specified.
.It Va signchar
The sign character, either
.Sq Li + ,
space or zero if none.
.It Va space
Boolean value whether the space flag was specified.
.It Va spec
The specifier character itself.
.It Va vsep
The separator character between vector items (using the
.Sq Li v
flag).
Can be any one of the four characters
.Dq Li ,:;_
or
.Sq Li X
if no separator character was specified (meaning that a space is used as the
separator, unless the specifier is
.Sq Li c ,
in which case no separator is used).
.It Va width
The value of the minimum field width (defaults to zero).
.El
.Pp
All other structure fields are either unused or private (and shouldn't be
used).
.Pp
This
.Vt struct printf_info
structure is then passed to the corresponding
.Nm printf_arginfo_function
callback function.
The callback function should return the number of consecutive arguments the
specifier handles, including zero (the maximum number of consecutive arguments
a single specifier can handle is
.Dv __PRINTFMAXARG ,
which is currently set to 2, but could be increased in the future if there is
need).
.Pp
The callback function is also passed an integer array and the length of that
array; the length will typically be
.Dv __PRINTFMAXARG .
The function should fill out the array up to the number of arguments it expects,
using the following values:
.Bl -tag -width ".Dv PA_POINTER"
.It Dv PA_CHAR
The argument type is an
.Vt int
cast to a
.Vt char .
.It Dv PA_DOUBLE
The argument type is a
.Vt double .
OR-ing
.Dv PA_DOUBLE
with
.Dv PA_FLAG_LONG_DOUBLE
specifies a
.Vt "long double"
type.
.It Dv PA_FLOAT
(Defined but unused; best to avoid, since
.Vt float
is automatically promoted to
.Vt double
anyways.)
.It Dv PA_INT
The argument type is
.Vt int
(either signed or unsigned).
The size can be adjusted by OR-ing the following values to
.Dv PA_INT :
.Bl -tag -width ".Dv PA_FLAG_LONG_LONG"
.It Dv PA_FLAG_INTMAX
The integer is the size of a
.Vt intmax_t .
.It Dv PA_FLAG_LONG
The integer is the size of a
.Vt long .
.It Dv PA_FLAG_LONG_LONG
The integer is the size of a
.Vt "long long" .
.It Dv PA_FLAG_PTRDIFF
The integer is the size of a
.Vt ptrdiff_t .
.It Dv PA_FLAG_QUAD
The integer is the size of a
.Vt quad_t
(deprecated).
.It Dv PA_FLAG_SHORT
The integer is the size of a
.Vt short .
.It Dv PA_FLAG_SIZE
The integer is the size of a
.Vt size_t .
.El
.It Dv PA_POINTER
The argument type is a pointer type, cast to a
.Vt "void *" .
.It Dv PA_STRING
The argument type is a null-terminated character string
.Vt ( "char *" ) .
.It Dv PA_VECTOR
The argument type is an AltiVec or SSE vector (16 bytes).
.It Dv PA_WCHAR
The argument type is a
.Vt wchar_t .
.It Dv PA_WSTRING
The argument type is a null-terminated wide character string
.Vt ( "wchar_t *" ) .
.El
.Pp
After the
.Nm printf_arginfo_function
returns, phase 2 of extensible printf processing involves converting the
argument according to the types specified by the returned type array.
Note that positional arguments are dealt with here as well.
.Pp
Then in phase 3, output is generated, either from the text in-between the
conversion specifications, or by calling the so-called rendering functions
associated with each conversion specifier (with typedef
.Nm printf_function ) .
The rendering function is passed the same
.Vt struct printf_info
structure, as well as an array of pointers to each of the arguments converted
in phase 2 that it is responsible for.
The callback should write its output to the provided output
stdio stream, and then return the number of characters written.
.Sh EXAMPLE
Here is an example that demonstrates many of the features of extensible printf:
.Bd -literal
#include <stdio.h>
#include <stdlib.h>
#include <printf.h>
#include <locale.h>
#include <xlocale.h>
#include <err.h>

/* The Coordinate type */
typedef struct {
    double x;
    double y;
} Coordinate;

#define L	(1 << 0)
#define P	(1 << 1)

/* The renderer callback for Coordinate */
static int
print_coordinate (FILE *stream, const struct printf_info *info,
    const void *const *args)
{
    const Coordinate *c;
    int width, ret, which = 0;
    char fmt[32];
    char *bp, *cp, *ep;
    /* The optional coordinate labels */
    const char **labels = (const char **)info->context;

    /* Get the argument pointer to a Coordinate */
    c = *((const Coordinate **) (args[0]));

    /* Set up the format string */
    cp = fmt;
    if(info->alt) *cp++ = '(';
    bp = cp;
    if(labels) {
	which |= L;
	*cp++ = '%';
	*cp++ = 's';
    }
    *cp++ = '%';
    if(info->group) *cp++ = '\e'';
    *cp++ = '*';
    if(info->prec >= 0) {
	which |= P;
	*cp++ = '.';
	*cp++ = '*';
    }
    *cp++ = 'l';
    *cp++ = 'f';
    ep = cp;
    if(info->alt) *cp++ = ',';
    *cp++ = ' ';
    while(bp < ep) *cp++ = *bp++;
    if(info->alt) *cp++ = ')';
    *cp = 0;

    width = info->left ? -info->width : info->width;

    /* Output to the given stream */
    switch(which) {
    case 0:
	ret = fprintf_l(stream, info->loc, fmt, width, c->x, width, c->y);
	break;
    case L:
	ret = fprintf_l(stream, info->loc, fmt, labels[0], width, c->x,
			labels[1], width, c->y);
	break;
    case P:
	ret = fprintf_l(stream, info->loc, fmt, width, info->prec, c->x,
			width, info->prec, c->y);
	break;
    case (L | P):
	ret = fprintf_l(stream, info->loc, fmt, labels[0], width,
			info->prec, c->x, labels[1], width, info->prec,
			c->y);
	break;
    }

    return ret;
}

/* The arginfo callback for Coordinate */
static int
coordinate_arginfo (const struct printf_info *info, size_t n,
		    int *argtypes)
{
  /* We always take exactly one argument and this is a pointer to the
     structure.. */
  if (n > 0)
    argtypes[0] = PA_POINTER;
  return 1;
}

int
main (void)
{
    Coordinate mycoordinate = {12345.6789, 3.141593};
    printf_domain_t domain;
    locale_t loc;
    const char *labels[] = {"x=", "y="};

    /* Set up a domain to add support for Coordinate conversion */
    domain = new_printf_domain();
    if(!domain)
	err(1, "new_printf_domain");
    /* Set up an extended locale to test locale support */
    loc = newlocale(LC_ALL_MASK, "uk_UA.UTF-8", NULL);
    if(!loc)
	err(1, "newlocale");

    /* Register the callbacks for Coordinates in the domain */
    register_printf_domain_function (domain, 'C', print_coordinate,
				     coordinate_arginfo, NULL);

    /* Print the coordinate using the current locale (C). */
    xprintf(domain, NULL, "|%'C|\en", &mycoordinate);
    xprintf(domain, NULL, "|%'14C|\en", &mycoordinate);
    xprintf(domain, NULL, "|%'-14.2C|\en", &mycoordinate);
    xprintf(domain, NULL, "|%'#C|\en", &mycoordinate);
    xprintf(domain, NULL, "|%'#14C|\en", &mycoordinate);
    xprintf(domain, NULL, "|%'#-14.2C|\en", &mycoordinate);

    printf("-------------\en");
    /* Reregister the callbacks, specifying coordinate labels
     * and setting the global locale (notice thousands separator) */
    register_printf_domain_function (domain, 'C', print_coordinate,
				     coordinate_arginfo, labels);
    if(setlocale(LC_ALL, "en_US.UTF-8") == NULL)
	errx(1, "setlocale");

    /* Reprint with labels */
    xprintf(domain, NULL, "|%'C|\en", &mycoordinate);
    xprintf(domain, NULL, "|%'14C|\en", &mycoordinate);
    xprintf(domain, NULL, "|%'-14.2C|\en", &mycoordinate);
    xprintf(domain, NULL, "|%'#C|\en", &mycoordinate);
    xprintf(domain, NULL, "|%'#14C|\en", &mycoordinate);
    xprintf(domain, NULL, "|%'#-14.2C|\en", &mycoordinate);

    printf("-------------\en");
    /* Now print with the test locale (notice decimal point and
     * thousands separator) */
    xprintf(domain, loc, "|%'C|\en", &mycoordinate);
    xprintf(domain, loc, "|%'14C|\en", &mycoordinate);
    xprintf(domain, loc, "|%'-14.2C|\en", &mycoordinate);
    xprintf(domain, loc, "|%'#C|\en", &mycoordinate);
    xprintf(domain, loc, "|%'#14C|\en", &mycoordinate);
    xprintf(domain, loc, "|%'#-14.2C|\en", &mycoordinate);

    return 0;
}
.Ed
.Pp
This example defines a Coordinate type, that consists of a pair of doubles.
We create a conversion specifier that displays a Coordinate type, either just
as two floating point numbers, or with the
.Sq Li #
(alternate form) flag, as parenthesized numbers separated by a comma.
Note the use of
.Nm printf_l
to do the actual output; this is using regular printf from within an extensible
printf renderer callback.
The use of
.Nm printf_l
also insures correct handling of extended locales.
.Pp
The output of the programs looks like:
.Bd -literal
|12345.678900 3.141593|
|  12345.678900       3.141593|
|12345.68       3.14          |
|(12345.678900, 3.141593)|
|(  12345.678900,       3.141593)|
|(12345.68      , 3.14          )|
-------------
|x=12,345.678900 y=3.141593|
|x= 12,345.678900 y=      3.141593|
|x=12,345.68      y=3.14          |
|(x=12,345.678900, y=3.141593)|
|(x= 12,345.678900, y=      3.141593)|
|(x=12,345.68     , y=3.14          )|
-------------
|x=12 345,678900 y=3,141593|
|x= 12 345,678900 y=      3,141593|
|x=12 345,68      y=3,14          |
|(x=12 345,678900, y=3,141593)|
|(x= 12 345,678900, y=      3,141593)|
|(x=12 345,68     , y=3,14          )|
.Ed
.Pp
Notice:
.Bl -bullet
.It
Field width, precision and left adjustment are applied to each of the numbers.
.It
The alternate form, using parenthesized numbers separated by a comma.
.It
In the second group of six, the thousands separator corresponds to the
global locale setting
.Pq Li en_US.UTF-8 .
.It
The second and third group have a label for each number, provide through
the user-defined context argument.
.It
The third group has the decimal point and thousands separator of the extended
locale argument
.Pq Li uk_UA.UTF-8 .
.El
.Sh PERFORMANCE
Because of the three phase processing of extensible printf, as well as the
use of two callbacks for each conversion specifier, performance is
considerably slower than the one pass, highly optimized regular
.Xr printf 3 .
Recursive use of
.Xr printf 3
from within an extensible printf renderer callback
(as in the
.Sx EXAMPLE
above) adds additional overhead.
.Pp
To ameliorate some of this slowness, the concept of separate compilation
and execution phases has be added to extensible printf.
The functions in
.Xr xprintf_comp 3
allow the creation of pre-compiled extensible printf structures (performing
phase one of extensible printf processing).
These pre-compiled structures can then be passed to the printf variants in
.Xr xprintf_exec 3
to produce the actual output (performing phases 2 and 3).
The compilation phase need only be done once, while execution can be performed
any number of times.
.Pp
A simple example of use is:
.Bd -literal
    printf_comp_t pc = new_printf_comp(domain, loc, "%d: %C\en");
    for(i = 0; i = sizeof(coords) / sizeof(*coords); i++) {
	xprintf_exec(pc, i, &coords[i]);
    }
    free_printf_comp(pc);
.Ed
.Pp
Here,
.Va coords
is a array containing
.Vt Coordinate
structures that are to be printed and the
.Va domain
and
.Va loc
variables are as from
.Sx EXAMPLE
above.
(Error checking on the return value from
.Fn new_printf_comp
is not shown).
.Sh SEE ALSO
.Xr printf 3 ,
.Xr xlocale 3 ,
.Xr xprintf 3 ,
.Xr xprintf_comp 3 ,
.Xr xprintf_domain 3 ,
.Xr xprintf_exec 3