libpipecolors/pcprintf.3

.\" Copyright (c) 2015 Eric Wheeler (eric@rewiv.com)
.\"
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, see
.\" <http://www.gnu.org/licenses/>.
.\" %%%LICENSE_END
.\"
.\" 2015-07-06 eric@rewiv.com \- initial program
.\"
.TH pcprintf 3 2015-07-06 "LIBPIPECOLORS" "Using pcprintf to print colors"
.SH NAME
pcprintf,
pcsprintf \- convert pipecode (|10) to ansi colors
.SH SYNOPSIS
.B #include <pipecolors.h>
.sp
.B using namespace pipecolors;
.sp
.BI "int pcprintf(const char * " format ", ...);"
.br
.BI "int pcsprintf(char * " str ", const char * " format ", ...);"
.sp
.in -4n
.ad
.SH DESCRIPTION
The functions in the
.BR pcprintf ()
family produce output according to a
.I format
as described below.
.PP
.SS pcprintf ()
This function parses input exactly like
.BR printf (3)
the only difference is that it converts old renegade bbs style pipecodes (|10) to ansi sequences.

See NOTES.
.PP
.SS pcsprintf ()
This function parses input exactly like
.BR sprintf (3)
the only difference is that it converts old renegade bbs style pipecodes (|10) to ansi sequences.

See NOTES.
.SS Return value
Upon successful return, these functions return the number of characters
printed (excluding the null byte used to end output to strings and
.I including
the ansi color code e.g. \fBx1b[0;39m\fR).

If an output error is encountered, a negative value is returned.
.SS Format of the format string

See
.BR printf (3)

.SS The flag characters
See
.BR printf (3)

.SH CONFORMING TO
The
.BR pcprintf (),
and
.BR pcsprintf ()
functions conform to C99 as they essentially wrap
.BR printf (3)
and
.BR sprintf (3)
.
.SH NOTES
.BR pcprintf ()
and
.BR pcsprintf ()
use
.BR vasprintf (3)
to automatically allocate buffer memory.

.SH BUGS
See
.BR printf (3)

.SH EXAMPLE
.nf
#include <\fBcstdio\fR>
#include <\fBiostream\fR>
#include <\fBpipecolors.h\fR>

using \fBnamespace\fR pipecolors;

\fBint\fR main(\fBvoid\fR) {

   \fBint\fR num = 5;
   \fBconst char*\fR str = "My number is";
   pcprintf("|02%s |10%d|39\\n", str, num);

   \fBreturn\fR 0;
}

\fBOutput\fR "\fB[ESC]\fRx1b[0;32mMy number is \fB[ESC]\fRx1b[0;92m5\fB[ESC]\fRx1b[0;39m";
.P
This would print \fBMy Number is\fR in dark green and \fI5\fR in light green.
The final code \fB|39\fR resets to the default color.
.fi
.SH SEE ALSO
.BR libpipecolors (7),
.BR printf (3),
.BR sprintf (3),
.BR vprintf (3),
.BR vsprintf (3),
.BR asprintf (3),
.BR vasprintf (3)