author | Olivier Brunel
<jjk@jjacky.com> 2023-03-21 18:36:04 UTC |
committer | Olivier Brunel
<jjk@jjacky.com> 2023-03-21 18:36:04 UTC |
parent | 61a448e0eb9e8cb5854f8dd1157d20484e44717c |
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__)