|
The interface described here allows the construction of custom
print(2) verbs and output routines. In essence, they provide access
to the workings of the formatted print code.
The print(2) suite maintains its state with a data structure called
Fmt. A typical call to print(2) or its relatives initializes a
Fmt structure, passes it to subsidiary routines to process the
output, and finishes by emitting any saved state recorded in the
Fmt. The details of the Fmt are unimportant to outside users,
except
insofar as the general design influences the interface. The Fmt
records whether the output is in runes or bytes, the verb being
processed, its precision and width, and buffering parameters.
Most important, it also records a flush routine that the library
will call if a buffer overflows. When printing to a file descriptor,
the
flush routine will emit saved characters and reset the buffer;
when printing to an allocated string, it will resize the string
to receive more output. The flush routine is nil when printing
to fixed–size buffers. User code need never provide a flush routine;
this is done internally by the library.
Custom output routines
To write a custom output routine, such as an error handler that
formats and prints custom error messages, the output sequence
can be run from outside the library using the routines described
here. There are two main cases: output to an open file descriptor
and output to a string.
To write to a file descriptor, call fmtfdinit to initialize the
local Fmt structure f, giving the file descriptor fd, the buffer
buf, and its size nbuf. Then call fmtprint or fmtvprint to generate
the output. These behave like fprint (see print(2)) or vfprint
except that the characters are buffered until fmtfdflush is called
and the return value is either 0 or –1. A typical example of this
sequence appears in the Examples section.
The same basic sequence applies when outputting to an allocated
string: call fmtstrinit to initialize the Fmt, then call fmtprint
and fmtvprint to generate the output. Finally, fmtstrflush will
return the allocated string, which should be freed after use.
To output to a rune string, use runefmtstrinit and runefmtstrflush.
Regardless of the output style or type, fmtprint or fmtvprint
generates the characters.
Custom format verbs
Fmtinstall is used to install custom verbs and flags labeled by
character c, which may be any non–zero Unicode character. Fn should
be declared as
Fp–>r is the flag or verb character to cause fn to be called. In
fn, fp–>width, fp–>prec are the width and precision, and fp–>flags the
decoded flags for the verb (see print(2) for a description of
these items). The standard flag values are: FmtSign (+), FmtLeft
(–), FmtSpace (' '), FmtSharp (#),
FmtComma (,), FmtLong (l), FmtShort (h), FmtUnsigned (u), and
FmtVLong (ll). The flag bits FmtWidth and FmtPrec identify whether
a width and precision were specified.
Fn is passed a pointer to the Fmt structure recording the state
of the output. If fp–>r is a verb (rather than a flag), fn should
use Fmt–>args to fetch its argument from the list, then format it,
and return zero. If fp–>r is a flag, fn should return one. All interpretation
of fp–>width, fp–>prec, and fp–>flags is
left up to the conversion routine. Fmtinstall returns 0 if the
installation succeeds, –1 if it fails.
Fmtprint and fmtvprint may be called to help prepare output in
custom conversion routines. These functions will preserve width,
precision, and flags. Both functions return 0 for success and
–1 for failure.
The functions dofmt and dorfmt are the underlying formatters;
they use the existing contents of Fmt and should be called only
by sophisticated conversion routines. These routines return the
number of characters (bytes of UTF or runes) produced.
Some internal functions may be useful to format primitive types.
They honor the width, precision and flags as described in print(2).
Fmtrune formats a single character r. Fmtstrcpy formats a string
s; fmtrunestrcpy formats a rune string s. Errfmt formats the system
error string. All these routines return zero for
successful execution. Conversion routines that call these functions
will work properly regardless of whether the output is bytes or
runes.
8c(1) describes the C directive #pragma varargck that can be used
to provide type–checking for custom print verbs and output routines.
|