Line 0
Link Here
|
|
|
1 |
.\" Copyright (c) 2007-2008 Roy Marples |
2 |
.\" All rights reserved |
3 |
.\" |
4 |
.\" Redistribution and use in source and binary forms, with or without |
5 |
.\" modification, are permitted provided that the following conditions |
6 |
.\" are met: |
7 |
.\" 1. Redistributions of source code must retain the above copyright |
8 |
.\" notice, this list of conditions and the following disclaimer. |
9 |
.\" 2. Redistributions in binary form must reproduce the above copyright |
10 |
.\" notice, this list of conditions and the following disclaimer in the |
11 |
.\" documentation and/or other materials provided with the distribution. |
12 |
.\" |
13 |
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND |
14 |
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
15 |
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
16 |
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
17 |
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
18 |
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
19 |
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
20 |
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
21 |
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
22 |
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
23 |
.\" SUCH DAMAGE. |
24 |
.\" |
25 |
.Dd Mar 16, 2008 |
26 |
.Dt EINFO 3 SMM |
27 |
.Os OpenRC |
28 |
.Sh NAME |
29 |
.Nm einfo , ewarn , eerror , ebegin , |
30 |
.Nm einfon , ewarnn , eerrorn , ebeginn , |
31 |
.Nm einfov , ewarnv , ebeginv , |
32 |
.Nm einfovn , ewarnvn , ebeginvn , |
33 |
.Nm ewarnx , eerrorx , |
34 |
.Nm eend , ewend , |
35 |
.Nm eendv , ewendv , |
36 |
.Nm ebracket , |
37 |
.Nm eindent , eoutdent , |
38 |
.Nm eindentv , eoutdentv , |
39 |
.Nm eprefix |
40 |
.Nd colorful informational output |
41 |
.Sh LIBRARY |
42 |
Enhanced Information output library (libeinfo, -leinfo) |
43 |
.Sh SYNOPSIS |
44 |
.In einfo.h |
45 |
.Ft int Fn einfo "const char * restrict format" ... |
46 |
.Ft int Fn ewarn "const char * restrict format" ... |
47 |
.Ft int Fn eerror "const char * restrict format" ... |
48 |
.Ft int Fn ebegin "const char * restrict format" ... |
49 |
.Ft int Fn einfon "const char * restrict format" ... |
50 |
.Ft int Fn ewarnn "const char * restrict format" ... |
51 |
.Ft int Fn eerrorn "const char * restrict format" ... |
52 |
.Ft int Fn ebeginn "const char * restrict format" ... |
53 |
.Ft int Fn einfov "const char * restrict format" ... |
54 |
.Ft int Fn ewarnv "const char * restrict format" ... |
55 |
.Ft int Fn ebeginv "const char * restrict format" ... |
56 |
.Ft int Fn einfovn "const char * restrict format" ... |
57 |
.Ft int Fn ewarnvn "const char * restrict format" ... |
58 |
.Ft int Fn ebeginvn "const char * restrict format" ... |
59 |
.Ft int Fn ewarnx "const char * restrict format" ... |
60 |
.Ft int Fn eerrorx "const char * restrict format" ... |
61 |
.Ft int Fn eend "int retval" "const char * restrict format" ... |
62 |
.Ft int Fn ewend "int retval" "const char * restrict format" ... |
63 |
.Ft int Fn eendv "int retval" "const char * restrict format" ... |
64 |
.Ft int Fn ewendv "int retval" "const char * restrict format" ... |
65 |
.Ft void Fn ebracket "int col" "ECOLOR color" "const char * restrict msg" |
66 |
.Ft void Fn eindent void |
67 |
.Ft void Fn eoutdent void |
68 |
.Ft void Fn eindentv void |
69 |
.Ft void Fn eoutdentv void |
70 |
.Ft void Fn eprefix "const char * prefix" |
71 |
.Sh DESCRIPTION |
72 |
The |
73 |
.Fn einfo |
74 |
family of functions provide a simple informational output that is colorised. |
75 |
Basically |
76 |
.Fn einfo , |
77 |
.Fn ewarn |
78 |
and |
79 |
.Fn eerror |
80 |
behave exactly like |
81 |
.Fn printf |
82 |
but prefix the output with a colored *. The function called denotes the color |
83 |
used with |
84 |
.Fn einfo |
85 |
being green, |
86 |
.Fn ewarn |
87 |
being yellow and |
88 |
.Fn eerror |
89 |
being red. |
90 |
einfo goes to stdout and the others go to stderr. |
91 |
The number of real characters printed is returned. |
92 |
.Fn ebegin |
93 |
is identical to |
94 |
.Fn einfo |
95 |
except that 3 dots are appended to the output. |
96 |
.Pp |
97 |
.Fn einfov , |
98 |
.Fn ewarnv |
99 |
and |
100 |
.Fn ebeginv |
101 |
work the same way to |
102 |
.Fn einfo , |
103 |
.Fn ewarn , |
104 |
and |
105 |
.Fn ebegin |
106 |
respectively, but only work when |
107 |
.Va EINFO_VERBOSE |
108 |
is true. You can also make the |
109 |
.Fn einfo , |
110 |
.Fn ewarn , |
111 |
and |
112 |
.Fn ebegin |
113 |
functions silent by setting |
114 |
.Va EINFO_QUIET |
115 |
to true. |
116 |
.Pp |
117 |
These functions are designed to output a whole line, so they also |
118 |
append a newline to the string. To stop this behaviour, you can use the |
119 |
functions |
120 |
.Fn einfon , |
121 |
.Fn ewarnn , |
122 |
.Fn eerrorn , |
123 |
.Fn einfovn , |
124 |
.Fn ewarnvn , |
125 |
and |
126 |
.Fn ebeginvn . |
127 |
.Pp |
128 |
.Fn eend , |
129 |
.Fn ewend , |
130 |
.Fn eendv |
131 |
and |
132 |
.Fn ewendv |
133 |
are the counterparts to the above functions. If |
134 |
.Fa retval |
135 |
is zero then ok in green is printed in a bracket at the end of the prior |
136 |
line. Otherwise we print the formatted string using |
137 |
.Fn error |
138 |
(or |
139 |
.Fn ewarn |
140 |
if |
141 |
.Fn ewend |
142 |
is called) !! in red (or yellow if |
143 |
.Fn ewend |
144 |
is called) is printed in a bracket at the end of the line. |
145 |
The value of |
146 |
.Fa retval |
147 |
is returned. |
148 |
.Pp |
149 |
.Fn ebracket |
150 |
does the same as |
151 |
.Fn eend |
152 |
but prints |
153 |
.Fa msg |
154 |
instead of ok or !! in the color |
155 |
.Fa color |
156 |
at the column |
157 |
.Fa col . |
158 |
.Pp |
159 |
.Fn eindent |
160 |
indents subsequent calls to the above functions by 3 characters. |
161 |
.Fn eoutdent |
162 |
removes an |
163 |
.Fn eindent . |
164 |
.Fn eindentv |
165 |
and |
166 |
.Fn eoutdentv |
167 |
only work when |
168 |
.Va EINFO_VERBOSE |
169 |
is true. |
170 |
.Pp |
171 |
.Fn eprefix |
172 |
prefixes the string |
173 |
.Fa prefix |
174 |
to the above functions. |
175 |
.Sh IMPLEMENTATION NOTES |
176 |
einfo can optionally be linked against the |
177 |
.Lb libtermcap |
178 |
so that we can correctly query the connected console for our color and |
179 |
cursor escape codes. |
180 |
If not, then we have a hard coded list of terminals we know about that support |
181 |
the commonly used codes for color and cursor position. |
182 |
.Sh ENVIRONMENT |
183 |
.Va EINFO_QUIET |
184 |
when set to true makes the |
185 |
.Fn einfo |
186 |
and |
187 |
.Fn einfon |
188 |
family of functions quiet, so nothing is printed. |
189 |
.Pp |
190 |
.Va EINFO_VERBOSE |
191 |
when set to true makes the |
192 |
.Fn einfov |
193 |
and |
194 |
.Fn einfovn |
195 |
family of functions work, so they do print. |
196 |
.Sh FILES |
197 |
.Pa @LIBEXECDIR@/sh/functions.sh |
198 |
is provided by OpenRC, which allows shell scripts to use the above functions. |
199 |
For historical reasons our verbose functions are prefixed with v instead of |
200 |
suffixed. So einfov becomes veinfo, einfovn becomes veinfon. |
201 |
Rinse and repeat for the other verbose functions. |
202 |
.Sh SEE ALSO |
203 |
.Xr printf 3 , |
204 |
.Sh AUTHORS |
205 |
.An Roy Marples <roy@marples.name> |