Welcome to little lamb

Code » limb » commit 3c31dae

Add obuffer.h and related functions

author Olivier Brunel
2023-03-21 18:25:33 UTC
committer Olivier Brunel
2023-03-21 18:25:33 UTC
parent 01cef642e06097739b359b9f1818f3b7b80d11d7

Add obuffer.h and related functions

An "output buffer" is just a pointer to a buffer and an output level
(u8), meaning when sending data to such a buffer it will only be written
into if the level of the message/data is that of the buffer or lower.

As such, we can easily have e.g; verbose messages ignored, or ignore
regular/normal ones for a buffer lowered to OLVL_QUIET

doc/obuffer.h.0.md +56 -0
doc/obuffer_put.3.md +36 -0
doc/obuffer_putmsg.3.md +34 -0
include/limb/obuffer.h +31 -0
meta/libs/limb +4 -0
src/obuffer_put.c +11 -0
src/obuffer_putmsg.c +11 -0
src/obuffers_putmsg.c +13 -0

diff --git a/doc/obuffer.h.0.md b/doc/obuffer.h.0.md
new file mode 100644
index 0000000..0c707f7
--- /dev/null
+++ b/doc/obuffer.h.0.md
@@ -0,0 +1,56 @@
+% limb manual
+% obuffer.h(0)
+
+# NAME
+
+obuffer.h - output buffer interface
+
+# SYNOPSIS
+
+    #include <limb/obuffer.h>
+
+# DESCRIPTION
+
+This header defines required functions to write on output buffers.
+
+An output buffer is simply a buffer writing on a file descriptor, with an
+assigned output level. Whenever a message is to be sent, is also comes with its
+own level. Only messages with a level matching the buffer's level or lower will
+be writing to the buffer.
+
+## Constants
+
+The following constants are defined :
+
+: *OLVL_SILENT*, *OLVL_QUIET*, *OLVL_NORMAL*, *OLVL_VERBOSE*,
+: *OLVL_DEBUG*, *OLVL_DEBUG_VERBOSE*
+:: Different output levels
+
+## Types
+
+The following types are defined :
+
+: *obuffer*
+:: A *struct obuffer*
+
+## Structures
+
+The following structures are defined :
+
+: *struct obuffer*
+:: Content of an output buffer. The level for the buffer can be accessed via the
+`lvl` member, of type *u8*.
+
+## Functions
+
+The following functions are defined :
+
+: [obuffer_put](3)
+:: To write given data to an output buffer (if levels match)
+
+: [obuffer_putmsg](3)
+:: To write a message, given as an array of strings, to an output buffer (if
+:: levels match)
+
+: [obuffers_putmsg](3)
+:: Same as [obuffer_putmsg](3) only to an array of output buffers.
diff --git a/doc/obuffer_put.3.md b/doc/obuffer_put.3.md
new file mode 100644
index 0000000..ed460bc
--- /dev/null
+++ b/doc/obuffer_put.3.md
@@ -0,0 +1,36 @@
+% limb manual
+% obuffer_put(3)
+
+# NAME
+
+obuffer\_put - write data to an output buffer
+
+# SYNOPSIS
+
+    #include <limb/obuffer.h>
+
+```pre hl
+ssize_t obuffer_put(obuffer *<em>obuf</em>, u8 <em>level</em>, const char *<em>data</em>, size_t <em>dlen</em>)
+```
+
+# DESCRIPTION
+
+The `obuffer_put`() function will write the given data pointed to by `data`, of
+length `dlen`, into the output buffer `obuf` if its level is at least `level`.
+
+If `obuf` has a level lower than `level` then nothing is done.
+
+# RETURN VALUE
+
+The `obuffer_put`() function returns the number of bytes written into `obuf`
+on success. Otherwise, it returns 0.
+
+! INFO: Error checking
+! It is possible to return 0 on success, if the output buffer has a level lower
+! than `level`. In order to check for error, you should set `errno` to 0 prior
+! to calling `obuffer_put`().
+
+# ERRORS
+
+The `obuffer_putesc`() function may fail and set `errno` for any of the errors
+specified for [buffer_put](3).
diff --git a/doc/obuffer_putmsg.3.md b/doc/obuffer_putmsg.3.md
new file mode 100644
index 0000000..c35b2e1
--- /dev/null
+++ b/doc/obuffer_putmsg.3.md
@@ -0,0 +1,34 @@
+% limb manual
+% obuffer_putmsg(3)
+
+# NAME
+
+obuffer\_putmsg, obuffers_putmsg - write message, given as an array of strings,
+to an output buffer
+
+# SYNOPSIS
+
+    #include <limb/obuffer.h>
+
+```pre hl
+void obuffer_putmsg(obuffer *<em>obuf</em>, u8 <em>level</em>, const char * const *<em>as</em>, unsigned int <em>n</em>)
+void obuffers_putmsg(obuffer *<em>obufs</em>, unsigned int <em>nbufs</em>,
+                     u8 <em>level</em>, const char * const *<em>as</em>, unsigned int <em>n</em>)
+```
+
+# DESCRIPTION
+
+The `obuffer_putmsg`() function will write the message, given as array of
+strings `as` of `n` elements, into the output buffer `obuf` if its level is at
+least `level`.
+
+If `obuf` has a level lower than `level` then nothing is done.
+
+The `obuffers_putmsg`() is similar, but for the array of `nbufs` output buffers
+pointed to by `obufs`. Each of the output buffers will have its own level
+checked against `level`, and only for those matching will the message be written
+into.
+
+! NOTE:
+! Every output buffer in `obufs` is checked to be "active", that is to have a
+! buffer set. Otherwise it is skipped.
diff --git a/include/limb/obuffer.h b/include/limb/obuffer.h
new file mode 100644
index 0000000..828c88d
--- /dev/null
+++ b/include/limb/obuffer.h
@@ -0,0 +1,31 @@
+/* This file is part of limb                           https://lila.oss/limb
+ * Copyright (C) 2023 Olivier Brunel                          jjk@jjacky.com */
+/* SPDX-License-Identifier: GPL-2.0-only */
+#ifndef LIMB_OBUFFER_H
+#define LIMB_OBUFFER_H
+
+#include "limb/buffer.h"
+#include "limb/int.h"
+
+enum olevel {
+    OLVL_SILENT         = 0,
+    OLVL_QUIET          = 50,
+    OLVL_NORMAL         = 100,
+    OLVL_VERBOSE        = 150,
+    OLVL_DEBUG          = 200,
+    OLVL_DEBUG_VERBOSE  = 250,
+};
+
+typedef struct obuffer obuffer;
+
+struct obuffer {
+    buffer *b;
+    u8 lvl;
+};
+
+extern ssize_t obuffer_put(obuffer *obuf, u8 level, const char *s, size_t len);
+extern void obuffer_putmsg(obuffer *obuf, u8 level, const char * const *as, unsigned int n);
+extern void obuffers_putmsg(obuffer *obufs, unsigned int nbufs,
+                            u8 level, const char * const *as, unsigned int n);
+
+#endif /* LIMB_OBUFFER_H */
diff --git a/meta/libs/limb b/meta/libs/limb
index 7e81f6f..da8a1e2 100644
--- a/meta/libs/limb
+++ b/meta/libs/limb
@@ -25,6 +25,10 @@ obj/buffer_putescall.o
 obj/buffer_putesc.o
 obj/buffer_putescs.o
 obj/buffer_putmsg.o
+# obuffer.h
+obj/obuffer_put.o
+obj/obuffer_putmsg.o
+obj/obuffers_putmsg.o
 # find msb
 obj/msb64.o
 # {,un}pack u64
diff --git a/src/obuffer_put.c b/src/obuffer_put.c
new file mode 100644
index 0000000..1595da4
--- /dev/null
+++ b/src/obuffer_put.c
@@ -0,0 +1,11 @@
+/* This file is part of limb                           https://lila.oss/limb
+ * Copyright (C) 2023 Olivier Brunel                          jjk@jjacky.com */
+/* SPDX-License-Identifier: GPL-2.0-only */
+#include "limb/obuffer.h"
+
+ssize_t
+obuffer_put(obuffer *obuf, u8 level, const char *s, size_t len)
+{
+    if (level > obuf->lvl) return 0;
+    return buffer_put(obuf->b, s, len);
+}
diff --git a/src/obuffer_putmsg.c b/src/obuffer_putmsg.c
new file mode 100644
index 0000000..b56d898
--- /dev/null
+++ b/src/obuffer_putmsg.c
@@ -0,0 +1,11 @@
+/* This file is part of limb                           https://lila.oss/limb
+ * Copyright (C) 2023 Olivier Brunel                          jjk@jjacky.com */
+/* SPDX-License-Identifier: GPL-2.0-only */
+#include "limb/obuffer.h"
+
+void
+obuffer_putmsg(obuffer *obuf, u8 level, const char * const *as, unsigned int n)
+{
+    if (level > obuf->lvl) return;
+    buffer_putmsg(obuf->b, as, n);
+}
diff --git a/src/obuffers_putmsg.c b/src/obuffers_putmsg.c
new file mode 100644
index 0000000..f47f514
--- /dev/null
+++ b/src/obuffers_putmsg.c
@@ -0,0 +1,13 @@
+/* This file is part of limb                           https://lila.oss/limb
+ * Copyright (C) 2023 Olivier Brunel                          jjk@jjacky.com */
+/* SPDX-License-Identifier: GPL-2.0-only */
+#include "limb/obuffer.h"
+
+void
+obuffers_putmsg(obuffer *obufs, unsigned int nbufs, u8 level,
+                const char * const *as, unsigned int n)
+{
+    for (int i = 0; i < nbufs; ++i)
+        if (obufs[i].b && level <= obufs[i].lvl)
+            buffer_putmsg(obufs[i].b, as, n);
+}