openrc/man/einfo.3

.\" Copyright 2007-2008 Roy Marples
.\" All rights reserved
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd Feb 22, 2008
.Dt EINFO 3 SMM
.Os OpenRC
.Sh NAME
.Nm einfo , ewarn , eerror , ebegin ,
.Nm einfon , ewarnn , eerrorn , ebeginn ,
.Nm einfov , ewarnv , ebeginv ,
.Nm einfovn , ewarnvn , ebeginvn ,
.Nm ewarnx , eerrorx ,
.Nm eend , ewend ,
.Nm eendv , ewendv ,
.Nm ebracket ,
.Nm eindent , eoutdent ,
.Nm eindentv , eoutdentv ,
.Nm eprefix
.Nd colorful informational output
.Sh LIBRARY
Enhanced Informatation output library (libeinfo, -leinfo)
.Sh SYNOPSIS
.In einfo.h
.Ft int Fn einfo "const char * restrict format" ...
.Ft int Fn ewarn "const char * restrict format" ...
.Ft int Fn eerror "const char * restrict format" ...
.Ft int Fn ebegin "const char * restrict format" ...
.Ft int Fn einfon "const char * restrict format" ...
.Ft int Fn ewarnn "const char * restrict format" ...
.Ft int Fn eerrorn "const char * restrict format" ...
.Ft int Fn ebeginn "const char * restrict format" ...
.Ft int Fn einfov "const char * restrict format" ...
.Ft int Fn ewarnv "const char * restrict format" ...
.Ft int Fn ebeginv "const char * restrict format" ...
.Ft int Fn einfovn "const char * restrict format" ...
.Ft int Fn ewarnvn "const char * restrict format" ...
.Ft int Fn ebeginvn "const char * restrict format" ...
.Ft int Fn ewarnx "const char * restrict format" ...
.Ft int Fn eerrorx "const char * restrict format" ...
.Ft int Fn eend "int retval" "const char * restrict format" ...
.Ft int Fn ewend "int retval" "const char * restrict format" ...
.Ft int Fn eendv "int retval" "const char * restrict format" ...
.Ft int Fn ewendv "int retval" "const char * restrict format" ...
.Ft void Fn ebracket "int col" "einfo_color_t color" "const char * restrict msg"
.Ft void Fn eindent void
.Ft void Fn eoutdent void
.Ft void Fn eindentv void
.Ft void Fn eoutdentv void
.Ft void Fn eprefix "const char * prefix"
.Sh DESCRIPTION
The
.Fn einfo
family of functions provide a simple informational output that is colorised.
Basically
.Fn einfo ,
.Fn ewarn
and
.Fn eerror
behave exactly like
.Fn printf
but prefix the output with a colored *. The function called denotes the color
used with
.Fn einfo
being green,
.Fn ewarn
being yellow and
.Fn eerror
being red.
einfo goes to stdout and the others go to stderr.
The number of real characters printed is returned.
.Fn ebegin
is identical to
.Fn einfo
except that 3 dots are appended to the output.
.Pp
.Fn einfov ,
.Fn ewarnv
and
.Fn ebeginv
work the same way to
.Fn einfo ,
.Fn ewarn ,
and
.Fn ebegin
respectively, but only work when
.Va EINFO_VERBOSE
is true. You can also make the
.Fn einfo ,
.Fn ewarn ,
and
.Fn ebegin
functions silent by setting
.Va EINFO_QUIET
to true.
.Pp
These functions are designed to output a whole line, so they also
append a newline to the string. To stop this behaviour, you can use the
functions
.Fn einfon , 
.Fn ewarnn ,
.Fn eerrorn ,
.Fn einfovn ,
.Fn ewarnvn ,
and
.Fn ebeginvn .
.Pp
.Fn eend ,
.Fn ewend ,
.Fn eendv
and
.Fn ewendv
are the counterparts to the above functions. If
.Fa retval
is zero then ok in green is printed in a bracket at the end of the prior
line. Otherwise we print the formatted string using
.Fn error
(or
.Fn ewarn
if
.Fn ewend
is called) !! in red (or yellow if
.Fn ewend
is called) is printed in a bracket at the end of the line.
The value of
.Fa retval
is returned.
.Pp
.Fn ebracket
does the same as
.Fn eend
but prints
.Fa msg
instead of ok or !! in the color 
.Fa color
at the column
.Fa col .
.Pp
.Fn eindent
indents subsequent calls to the above functions by 3 characters.
.Fn eoutdent
removes an
.Fn eindent .
.Fn eindentv
and
.Fn eoutdentv
only work when
.Va EINFO_VERBOSE
is true.
.Pp
.Fn eprefix
prefixes the string
.Fa prefix
to the above functions.
.Sh IMPLEMENTATION NOTES
einfo can optionally be linked against the
.Lb libtermcap
so that we can correctly query the connected console for our color and
cursor escape codes.
If not, then we have a hard coded list of terminals we know about that support
the commonly used codes for color and cursor position.
.Sh ENVIRONMENT
.Va EINFO_QUIET
when set to true makes the
.Fn einfo
and
.Fn einfon
family of functions quiet, so nothing is printed.
.Pp
.Va EINFO_VERBOSE
when set to true makes the
.Fn einfov
and
.Fn einfovn
family of functions work, so they do print.
.Sh FILES
.Pa /etc/init.d/functions.sh
is provided by OpenRC, which allows shell scripts to use the above functions.
For historical reasons our verbose functions are prefixed with v instead of
suffixed. So einfov becomes veinfo, einfovn becomes veinfon.
Rinse and repeat for the other verbose functions.
.Sh SEE ALSO
.Xr printf 3 ,
.Sh AUTHORS
.An "Roy Marples" Aq roy@marples.name