Welcome to little lamb

Code » limb » commit ba217d5

Update output.h macros

author Olivier Brunel
2023-03-21 18:36:04 UTC
committer Olivier Brunel
2023-03-21 18:36:04 UTC
parent 61a448e0eb9e8cb5854f8dd1157d20484e44717c

Update output.h macros

No functional changes, but addition of a few new macros regarding the
output levels, e.g. quiet() for messages even in quiet mode, verb() for
those only in verbose mode, as well as dbg() for debug messages,
automatically prefixed with [function@file:line]

doc/die.3.md +17 -11
doc/out.3.md +52 -16
doc/output.h.0.md +35 -30
doc/warn.3.md +12 -2
include/limb/output.h +29 -19

diff --git a/doc/die.3.md b/doc/die.3.md
index 79eb6fe..2e4c689 100644
--- a/doc/die.3.md
+++ b/doc/die.3.md
@@ -13,24 +13,30 @@ die, dief, diefu, diesys, diefsys, diefusys - write a message to stderr and term
     extern const char *PROG;
 
 ```pre hl
-void die(<em>e</em>, ...)
-void dief(<em>e</em>, ...)
-void diefu(<em>e</em>, ...)
-void diesys(<em>e</em>, ...)
-void diefsys(<em>e</em>, ...)
-void diefusys(<em>e</em>, ...)
+void die(<em>exit</em>, ...)
+void dief(<em>exit</em>, ...)
+void diefu(<em>exit</em>, ...)
+void diesys(<em>exit</em>, ...)
+void diefsys(<em>exit</em>, ...)
+void diefusys(<em>exit</em>, ...)
 
-void dieusage(<em>e</em>, <em>usage</em>)
-void diehelp(<em>e</em>, <em>usage</em>, <em>help</em>)
+void dieusage(<em>exit</em>, <em>usage</em>)
+void diehelp(<em>exit</em>, <em>usage</em>, <em>help</em>)
 
 void dieversion(<em>version</em>, <em>year1</em>, <em>year2</em>, <em>author</em>, <em>url</em>, <em>license</em>)
 ```
 
 # DESCRIPTION
 
-All of those are implemented as macros (to [put](3)) and will write the
-specified strings to /stderr/, with a new line added at the end, then terminate
-the calling process via [_exit](3) using `e`.
+All of those are implemented as macros (to [err_putmsgdie](3) or
+[out_putmsgdie](3) for `dieversion`()) and will write the specified strings to
+*stderr* (or *stdout* for `dieversion`(), with a new line added at the end, then
+terminate the calling process via [\_exit](3) using `exit` as return/status code.
+
+! INFO: output buffers
+! All of those are using output buffers, and will therefore write to the output
+! buffers for *stdout* or *stderr*, as well as all the extra buffers set up,
+! e.g. via [obuffers_addlog](3) and/or [obuffers_adddbg](3).
 
 All messages will be prefixed by the program's name (i.e. value of `PROG`), a
 colon and a space.
diff --git a/doc/out.3.md b/doc/out.3.md
index dd2530b..a30da5e 100644
--- a/doc/out.3.md
+++ b/doc/out.3.md
@@ -5,7 +5,8 @@
 
 # NAME
 
-out, err, sys, add, adde, outdie, errdie, sysdie - write text to standard
+out, quiet, verb, err, errverb, sys, sysverb, add, adde, outdie, quietdie,
+verbdie, errdie, errverbdie, sysdie, sysverbdie - write text to standard
 output/error (and terminate process)
 
 # SYNOPSIS
@@ -13,37 +14,72 @@ output/error (and terminate process)
     #include <limb/output.h>
 
 ```pre hl
+void quiet(...)
 void out(...)
+void verb(...)
 void err(...)
+void errverb(...)
 void sys(...)
+void sysverb(...)
+void dbg(...)
+void dbgverb(...)
 
 void add(...)
 void adde(...)
 
-void outdie(<em>e</em>, ...)
-void errdie(<em>e</em>, ...)
-void sysdie(<em>e</em>, ...)
+void quietdie(<em>exit</em>, ...)
+void outdie(<em>exit</em>, ...)
+void verbdie(<em>exit</em>, ...)
+void errdie(<em>exit</em>, ...)
+void errverbdie(<em>exit</em>, ...)
+void sysdie(<em>exit</em>, ...)
+void sysverbdie(<em>exit</em>, ...)
 ```
 
 # DESCRIPTION
 
-All of those are implemented as macros (to [put](3)) and will write to
-either standard outpout or standard error, then maybe terminate the calling
-process or return.
+All of those are implemented as macros and will write to either standard output
+or standard error, then maybe terminate the calling process or return.
 
-The macro `out`() writes given strings to /stdout/, adding a newline and
-flushing out the buffer.
+! INFO: output buffers
+! All of those are using output buffers, and will therefore write to the output
+! buffers for *stdout* or *stderr*, as well as all the extra buffers set up,
+! e.g. via [obuffers_addlog](3) and/or [obuffers_adddbg](3).
 
-The macro `err`() writes given strings to /stderr/, adding a newline and
-flushing out the buffer.
+The macro `out`() writes given strings to *stdout* buffers with level
+*OLVL_NORMAL* or more, adding a newline and flushing out the buffer.
 
-The macro `add`() writes given strings to /stdout/.
+The macros `quiet`() and `verb`() are similar to `out`(), only with *OLVL_QUIET*
+and *OLVL_VERBOSE* levels respectively.
 
-The macro `adde`() writes given strings to /stderr/.
+The macro `err`() writes given strings to *stderr* buffers with level
+*OLVL_NORMAL* or more, adding a newline and flushing out the buffer.
+
+The macro `errverb`() is similar only with *OLVL_VERSOSE* level.
+
+The macro `add`() writes given strings to *stdout* buffers with *OLVL_NORMAL*.
+
+The macro `adde`() writes given strings to *stderr* buffers with *OLVL_NORMAL*.
 
 The macro `sys`() is similar to `err`() but will add a colon, a space and the
 error description from [strerror](3) on `errno` after the given strings.
 
-Macros `outdie`(), `errdie`() and `sysdie`() are similar to `out`(), `err`() and
-`sys`() respectively but will terminate the calling process (via [\_exit](3)
-using `e`).
+The macro `sysverb`() is similar only with *OLVL_VERSOSE* level.
+
+The macro `dbg`() is similar to `out`() but with level *OLVL_DEBUG*, and
+prefixing with function name, file name and line number (see [dbg_putmsg](3) for
+more).
+
+Macros `quietdie`(), `outdie`(), `verbdie`(), `errdie`(), `errverbdie`(),
+`sysdie`() and `sysverbdie`() are similar to `quiet`(), `out`(), `verb`(),
+`err`(), `errverb`(), `sys`() and `sysverb`() respectively but will terminate
+the calling process (via [\_exit](3) using `e`).
+
+## Escaping
+
+It is possible to use *PUTMSG_ESC* (or simply *ESC*) as one of the strings in
+order to toggle escaping. See to [buffer_putmsg](3) for more.
+
+# SEE ALSO
+
+[out_putmsg](3), [buffer_putmsg](3)
diff --git a/doc/output.h.0.md b/doc/output.h.0.md
index 63642cc..bbbac98 100644
--- a/doc/output.h.0.md
+++ b/doc/output.h.0.md
@@ -15,32 +15,26 @@ output.h - writing to stdout/stderr
 This header defines functions used to write messages/warnings to stdout or
 stderr.
 
-## Constants
-
-The following constants are defined :
-
-: *ESC*
-:: Special value that can be passed as a string to [put](3) (and related macros)
-:: to enable escaping mode for following strings (up to the next *ESC*)
-
-: *PUT_SYS*
-:: Option to [put](3) to have the error description of `errno` suffixed
-
-: *PUT_DIE*
-:: Option to [put](3) to end program execution using given exit code
-
-: *PUT_LFF*
-:: Option to [put](3) to add a LF and flush the buffer
+It actually relies on/makes use of [out_putmsg](3), [err_putmsg](3),
+[dbg_putmsg](3), [out_putmsgdie](3) and [err_putmsgdie](3).
 
 ## Functions
 
 The following functions/macros are defined :
 
 : [add](3)
-:: Write given strings to *stdout*
+:: Write given strings to *stdout* buffers with level *OLVL_NORMAL* or more
 
 : [adde](3)
-:: Write given strings to *stderr*
+:: Write given strings to *stderr* buffers with level *OLVL_NORMAL* or more
+
+: [dbg](3)
+:: Write given strings to *stdout* buffers with level *OLVL_DEBUG* or more,
+:: prefixing with function name, file name and line number, adding a LF and
+:: flushing the buffer afterwards
+
+: [dbgverb](3)
+:: Same as [dbg](3) but with *OLVL_DEBUG_VERBOSE*
 
 : [die](3)
 :: Same as [errdie](3) but prefixed with "*PROG*: "
@@ -72,32 +66,43 @@ The following functions/macros are defined :
 :: Write a version and copyright message to *stdout*
 
 : [err](3)
-:: Write given strings to *stderr*, add a LF and flush the buffer
+:: Write given strings to *stderr* buffers with level *OLVL_NORMAL* or more,
+:: adding a LF and flushing the buffer afterwards
 
 : [errdie](3)
 :: Same as [err](3) but ends program execution using given exit code
 
+: [errverb](3)
+:: Same as [err](3) but with *OLVL_VERBOSE*
+
 : [out](3)
-:: Write given strings to *stdout*, add a LF and flush the buffer
+:: Write given strings to *stdout* buffers with level *OLVL_NORMAL* or more,
+:: adding a LF and flushing the buffer afterwards
 
 : [outdie](3)
 :: Same as [out](3) but ends program execution using given exit code
 
-: [put](3)
-:: Write given array of strings to given buffer, optionally the error
-:: description and/or aborting program execution
+: [quiet](3)
+:: Same as [out](3) but with *OLVL_QUIET*
 
 : [sys](3)
-:: Write given strings to *stderr*, add a LF and flush the buffer
+:: Same as [err](3) with adding a colon, a space and the error description for
+:: `errno` before the LF
 
 : [sysdie](3)
 :: Same as [sys](3) but ends program execution using given exit code
 
+: [sysverb](3)
+:: Same as [sys](3) but with *OLVL_VERBOSE*
+
+: [verb](3)
+:: Same as [out](3) but with *OLVL_VERBOSE*
+
 : [warn](3)
-:: Write a warning to *stderr*
+:: Write a warning to *stderr* buffers with level *OLVL_NORMAL* or more
 
 : [warnsys](3)
-:: Write a warning to *stderr* followed by the error description
+:: Same as [warn](3) but adding error description after the warning
 
 : [warnu](3)
 :: Same as [warn](3) but starting the warning with "unable to "
@@ -110,13 +115,13 @@ The following functions/macros are defined :
 The following macros are defined :
 
 : [retw](3)
-:: same as [warn](3) then return the given value
+:: Same as [warn](3) then return the given value
 
 : [retwu](3)
-:: same as [warnu](3) then return the given value
+:: Same as [warnu](3) then return the given value
 
 : [retwsys](3)
-:: same as [warnsys](3) then return the given value
+:: Same as [warnsys](3) then return the given value
 
 : [retwusys](3)
-:: same as [warnusys](3) then return the given value
+:: Same as [warnusys](3) then return the given value
diff --git a/doc/warn.3.md b/doc/warn.3.md
index 3216978..f79ae6f 100644
--- a/doc/warn.3.md
+++ b/doc/warn.3.md
@@ -21,8 +21,14 @@ void warnusys(...)
 
 # DESCRIPTION
 
-All of those are implemented as macros (to [put](3)) and will write the
-specified strings as warning to /stderr/, with a new line added at the end.
+All of those are implemented as macros and will write the specified strings as
+warning to *stderr* output buffers (with level *OLVL_NORMAL* or more), with a
+new line added at the end.
+
+! INFO: output buffers
+! All of those are using output buffers, and will therefore write to the output
+! buffers for *stdout* or *stderr*, as well as all the extra buffers set up,
+! e.g. via [obuffers_addlog](3) and/or [obuffers_adddbg](3).
 
 All warnings will be prefixed by the program's name (i.e. value of `PROG`), the
 word "warning " in between colon and a space.
@@ -32,3 +38,7 @@ word "warning " in between colon and a space.
 The `warnsys`() and `warnusys`() macros are similar, only the specified strings
 will be followed by a colon, a space and the error description provided by
 [strerror](3) according to `errno`.
+
+# SEE ALSO
+
+[out](3), [err_putmsg](3), [buffer_putmsg](3)
diff --git a/include/limb/output.h b/include/limb/output.h
index d5f5a3e..05c73ea 100644
--- a/include/limb/output.h
+++ b/include/limb/output.h
@@ -4,31 +4,41 @@
 #ifndef LIMB_OUTPUT_H
 #define LIMB_OUTPUT_H
 
-#include <skalibs/buffer.h>
-
-enum {
-    PUT_SYS     = (1 << 0),
-    PUT_DIE     = (1 << 1),
-    PUT_LFF     = (1 << 2),
-};
-
-#define ESC                 ((void *) 1)
-
-extern void put(buffer *b, int e, unsigned int opts, const char * const *as, unsigned int n);
+#include "limb/obuffers.h"
 
 extern const char *PROG;
 
 #define outarray(...)       ((char const * const []) {__VA_ARGS__})
 #define outalen(...)        (sizeof(outarray(__VA_ARGS__)) / sizeof(char const *))
 
-#define out(...)            put(buffer_1, 0, PUT_LFF, outarray(__VA_ARGS__), outalen(__VA_ARGS__))
-#define err(...)            put(buffer_2, 0, PUT_LFF, outarray(__VA_ARGS__), outalen(__VA_ARGS__))
-#define sys(...)            put(buffer_2, 0, PUT_SYS | PUT_LFF, outarray(__VA_ARGS__), outalen(__VA_ARGS__))
-#define add(...)            put(buffer_1, 0, 0, outarray(__VA_ARGS__), outalen(__VA_ARGS__))
-#define adde(...)           put(buffer_2, 0, 0, outarray(__VA_ARGS__), outalen(__VA_ARGS__))
-#define outdie(e, ...)      put(buffer_1, e, PUT_LFF | PUT_DIE, outarray(__VA_ARGS__), outalen(__VA_ARGS__))
-#define errdie(e, ...)      put(buffer_2, e, PUT_LFF | PUT_DIE, outarray(__VA_ARGS__), outalen(__VA_ARGS__))
-#define sysdie(e, ...)      put(buffer_2, e, PUT_SYS | PUT_LFF | PUT_DIE, outarray(__VA_ARGS__), outalen(__VA_ARGS__))
+#define outmsg(l,...)       out_putmsg(l, outarray(__VA_ARGS__), outalen(__VA_ARGS__))
+#define errmsg(l,...)       err_putmsg(l, outarray(__VA_ARGS__), outalen(__VA_ARGS__))
+#define dbgmsg(l,...)       dbg_putmsg(l, __func__, __FILE__, __LINE__, outarray(__VA_ARGS__), outalen(__VA_ARGS__))
+
+#define outmsgdie(e,l,...)  out_putmsgdie(e, l, outarray(__VA_ARGS__), outalen(__VA_ARGS__))
+#define errmsgdie(e,l,...)  err_putmsgdie(e, l, outarray(__VA_ARGS__), outalen(__VA_ARGS__))
+
+#define quiet(...)          outmsg(OLVL_QUIET, __VA_ARGS__, PUTMSG_LFF)
+#define out(...)            outmsg(OLVL_NORMAL, __VA_ARGS__, PUTMSG_LFF)
+#define verb(...)           outmsg(OLVL_VERBOSE, __VA_ARGS__, PUTMSG_LFF)
+#define dbg(...)            dbgmsg(OLVL_DEBUG, __VA_ARGS__, PUTMSG_LFF)
+#define dbgverb(...)        dbgmsg(OLVL_DEBUG_VERBOSE, __VA_ARGS__, PUTMSG_LFF)
+
+#define err(...)            errmsg(OLVL_NORMAL, __VA_ARGS__, PUTMSG_LFF)
+#define errverb(...)        errmsg(OLVL_VERBOSE, __VA_ARGS__, PUTMSG_LFF)
+#define sys(...)            errmsg(OLVL_NORMAL, __VA_ARGS__, ": ", PUTMSG_SYS, PUTMSG_LFF)
+#define sysverb(...)        errmsg(OLVL_VERBOSE, __VA_ARGS__, ": ", PUTMSG_SYS, PUTMSG_LFF)
+
+#define add(...)            outmsg(OLVL_NORMAL, __VA_ARGS__)
+#define adde(...)           errmsg(OLVL_NORMAL, __VA_ARGS__)
+
+#define quietdie(e,...)     outmsgdie(e, OLVL_QUIET, __VA_ARGS__, PUTMSG_LFF)
+#define outdie(e,...)       outmsgdie(e, OLVL_NORMAL, __VA_ARGS__, PUTMSG_LFF)
+#define verbdie(e,...)      outmsgdie(e, OLVL_VERBOSE, __VA_ARGS__, PUTMSG_LFF)
+#define errdie(e,...)       errmsgdie(e, OLVL_NORMAL, __VA_ARGS__, PUTMSG_LFF)
+#define errverbdie(e,...)   errmsgdie(e, OLVL_VERBOSE, __VA_ARGS__, PUTMSG_LFF)
+#define sysdie(e,...)       errmsgdie(e, OLVL_NORMAL, __VA_ARGS__, ": ", PUTMSG_SYS, PUTMSG_LFF)
+#define sysverbdie(e,...)   errmsgdie(e, OLVL_VERBOSE, __VA_ARGS__, ": ", PUTMSG_SYS, PUTMSG_LFF)
 
 #define warn(...)           err(PROG, ": warning: ", __VA_ARGS__)
 #define warnu(...)          warn("unable to ", __VA_ARGS__)