More status handling shorthands

Author: vector-of-bool

.clang-format

@@ -82,6 +82,7 @@ IncludeCategories:
 InsertNewlineAtEOF: true
 IfMacros:
   - mlib_math_catch
+  - amongoc_if_error
 AllowBreakBeforeNoexceptSpecifier: Always
 ---
 # For some reason, Clang sees some files as Objective-C. Add this section just to appease it.

docs/conf.py

@@ -415,6 +415,8 @@ class CustomCppLexer(CppLexer):
             (r"bson_type_\w+\b", token.Name.Constant),
             # Other macro
             (r"bson_foreach\w*\b", token.Keyword),
+            (r"amongoc_declmsg\b", token.Keyword),
+            (r"amongoc_if_error\b", token.Keyword),
             inherit,
         ],
     }

docs/how-to/communicate.example.c

@@ -74,8 +74,7 @@ int main(int argc, char const* const* argv) {
 
     amongoc_loop   loop;
     amongoc_status status = amongoc_default_loop_init(&loop);
-    if (amongoc_is_error(status)) {
-        amongoc_declmsg(msg, status);
+    amongoc_if_error (status, msg) {
         fprintf(stderr, "Error setting up the event loop: %s\n", msg);
         return 2;
     }
@@ -102,8 +101,7 @@ int main(int argc, char const* const* argv) {
     amongoc_client_delete(state.client);
     amongoc_default_loop_destroy(&loop);
 
-    if (amongoc_is_error(status)) {
-        amongoc_declmsg(msg, status);
+    amongoc_if_error (status, msg) {
         fprintf(stderr, "An error occurred: %s\n", msg);
         return 2;
     } else {

docs/how-to/communicate.rst

@@ -240,7 +240,7 @@ Print the Final Result
 
 .. literalinclude:: communicate.example.c
   :lineno-match:
-  :start-at: is_error
+  :start-at: if_error
   :end-before: end.
 
 Finally, we inspect the `amongoc_status` that was produced by our operation and

docs/how-to/looping.example.c

@@ -20,7 +20,9 @@ typedef struct {
  *
  * @param state_ptr Pointer to the `state` for the program
  */
-amongoc_emitter loop_step(amongoc_box state_ptr, amongoc_status prev_status, amongoc_box prev_res) {
+amongoc_emitter loop_step(amongoc_box    state_ptr,  //
+                          amongoc_status prev_status,
+                          amongoc_box    prev_res) {
     (void)prev_res;
     (void)prev_status;
     // Print our status
@@ -60,7 +62,10 @@ int main(int argc, char const* const* argv) {
 
     // Create a default loop
     amongoc_loop loop;
-    amongoc_default_loop_init(&loop);
+    amongoc_if_error (amongoc_default_loop_init(&loop), msg) {
+        fprintf(stderr, "Error initializing event loop: %s\n", msg);
+        return 1;
+    }
 
     // Seed the initial sum
     state app_state = {.countdown = delay, .loop = &loop, .a = 0, .b = 1};
@@ -77,14 +82,12 @@ int main(int argc, char const* const* argv) {
     amongoc_operation_delete(op);
     amongoc_default_loop_destroy(&loop);
 
-    if (amongoc_is_error(status)) {
-        amongoc_declmsg(msg, status);
+    amongoc_if_error (status, msg) {
         fprintf(stderr, "error: %s\n", msg);
         amongoc_box_destroy(result);
         return 2;
-    } else {
-        // Get the value returned with `amongoc_just` in `loop_step`
-        printf("Got final value: %lu\n", amongoc_box_cast(uint64_t, result));
     }
+    // Get the value returned with `amongoc_just` in `loop_step`
+    printf("Got final value: %lu\n", amongoc_box_cast(uint64_t, result));
     return 0;
 }

docs/how-to/looping.rst

@@ -196,14 +196,14 @@ program. We check for errors, either printing the error message or printing the
 final result:
 
 .. literalinclude:: looping.example.c
-  :start-at: is_error
+  :start-at: if_error (status, msg)
   :end-at: return 0;
   :lineno-match:
 
-We use `amongoc_is_error` to test the final status for an error condition. If it
-is an error, we get and print the error message to stderr, and we must destroy
-the final result box because it may contain an unspecified value related to the
-error, but we don't want to do anything with it.
+We use :c:macro:`amongoc_if_error` to test the final status for an error
+condition. If it is an error, we get and print the error message to stderr, and
+we must destroy the final result box because it may contain an unspecified value
+related to the error, but we don't want to do anything with it.
 
 In the success case, we extract the value returned in `amongoc_just` as a
 ``uint64_t`` and print it to stdout. Note that because the box returned by

docs/learn/connect.example.c

@@ -9,8 +9,7 @@ amongoc_box on_connect(amongoc_box userdata, amongoc_status* status, amongoc_box
 int main(void) {
     amongoc_loop   loop;
     amongoc_status status = amongoc_default_loop_init(&loop);
-    if (amongoc_is_error(status)) {
-        amongoc_declmsg(msg, status);
+    amongoc_if_error (status, msg) {
         fprintf(stderr, "Failed to prepare the event loop: %s\n", msg);
         return 2;
     }
@@ -32,8 +31,7 @@ amongoc_box on_connect(amongoc_box userdata, amongoc_status* status, amongoc_box
     // We don't use the userdata
     (void)userdata;
     // Check for an error
-    if (amongoc_is_error(*status)) {
-        amongoc_declmsg(msg, *status);
+    amongoc_if_error (*status, msg) {
         fprintf(stderr, "Error while connecting to server: %s\n", msg);
     } else {
         printf("Successfully connected!\n");

docs/ref/status.rst

@@ -83,6 +83,8 @@ Functions & Macros
     The defintion of what constitutes an error depends on the
     `amongoc_status::category`.
 
+  .. seealso:: :c:macro:`amongoc_if_error`
+
 
 .. function:: bool amongoc_is_cancellation(amongoc_status st)
 
@@ -130,8 +132,12 @@ Functions & Macros
 
   This function does not dynamically allocate any memory.
 
-  .. seealso:: :c:macro:`amongoc_declmsg` for concisely obtaining the message
-    from a status object.
+  .. seealso::
+
+    - :c:macro:`amongoc_declmsg` for concisely obtaining the message from a
+      status object.
+    - :c:macro:`amongoc_if_error` to check for an error and extract the message
+      in a single line.
 
 
 .. c:macro:: amongoc_declmsg(MsgVar, Status)
@@ -151,6 +157,34 @@ Functions & Macros
     const char* MsgVar = amongoc_message(Status, __buffer, sizeof __buffer)
 
 
+.. c:macro::
+  amongoc_if_error(Status, MsgVar, StatusVar)
+
+  Create a branch on whether the given status represents an error. This macro
+  supports being called with two arguments, or with three::
+
+    amongoc_if_error (status, msg_varname) {
+      fprintf(stderr, "Error message: %s\n", msg_varname)
+    }
+
+  ::
+
+    amongoc_if_error (status, msg_varname, status_varname) {
+      fprintf(stderr, "Error code %d has message: %s\n", status_varname.code, msg_varname);
+    }
+
+  :param Status: The first argument must be an expression of type `amongoc_status`. This is
+    the status to be inspected.
+  :param MsgVar: This argument should be a plain identifier, which will be declared within
+    the scope of the statement as the :term:`C string` for the status.
+  :param StatusVar: If provided, a variable of type `amongoc_status` will be declared within
+    the statment scope that captures the value of the ``Status`` argument.
+
+  .. hint::
+
+    If you are using ``clang-format``, add ``amongoc_if_error`` to the
+    ``IfMacros`` for your ``clang-format`` configuration.
+
 .. var:: const amongoc_status amongoc_okay
 
   A generic status with a code zero. This represents a generic non-error status.

include/amongoc/status.h

@@ -871,8 +871,32 @@ mlib_extern_c_end();
 
 #define amongoc_okay mlib_parenthesized_expression(*_amongocStatusGetOkayStatus())
 
-#if mlib_is_cxx()
+/**
+ * @brief Branch on whether a status code is an error, and get the string message
+ * out of it in a single statement.
+ *
+ * @param Status An expression of type `amongoc_status`
+ * @param MsgVar An identifier, which will be declared as a C string for the status' message
+ */
+#define amongoc_if_error(...) MLIB_ARGC_PICK(_amongoc_if_error, __VA_ARGS__)
+#define _amongoc_if_error_argc_2(Status, MsgVar)                                                   \
+    _amongoc_if_error_argc_3((Status), MsgVar, MLIB_PASTE(_amongoc_status_tmp_lno_, __LINE__))
+#define _amongoc_if_error_argc_3(Status, MsgVar, StatusVar)                                        \
+    _amongocIfErrorBlock((Status),                                                                 \
+                         MsgVar,                                                                   \
+                         StatusVar,                                                                \
+                         MLIB_PASTE(_amongoc_oncevar_lno_, __LINE__),                              \
+                         MLIB_PASTE(_amongoc_msgbuf_lno_, __LINE__))
+// clang-format off
+#define _amongocIfErrorBlock(Status, MsgVar, StatusVar, OnceVar, MsgBuf) \
+    for (int OnceVar = 1; OnceVar; OnceVar = 0) \
+    for (amongoc_status const StatusVar = (Status); OnceVar; OnceVar = 0) \
+    if (amongoc_is_error(StatusVar)) \
+    for (char MsgBuf[128]; OnceVar; OnceVar = 0) \
+    for (const char* MsgVar = amongoc_message(StatusVar, MsgBuf, sizeof MsgBuf); OnceVar; OnceVar = 0)
+// clang-format on
 
+#if mlib_is_cxx()
 namespace amongoc {
 
 using status = ::amongoc_status;

src/amongoc/status.test.cpp

@@ -8,12 +8,27 @@ TEST_CASE("Status/Okay") {
     amongoc_status st = amongoc_okay;
     CHECK(st.code == 0);
     CHECK(st.category == &amongoc_generic_category);
+
+    bool took_else = false;
+    amongoc_if_error (st, _) {
+        FAIL_CHECK("Did not expect an error");
+    } else {
+        took_else = true;
+    }
+    CHECK(took_else);
 }
 
 TEST_CASE("Status/From an Error") {
     auto st = amongoc_status::from(std::make_error_code(std::errc::io_error));
     CHECK(st.category == &amongoc_generic_category);
     CHECK(st.code == EIO);
+    bool took_err = false;
+    amongoc_if_error (st, _) {
+        took_err = true;
+    } else {
+        FAIL_CHECK("Did not take the error branch");
+    }
+    CHECK(took_err);
 }
 
 TEST_CASE("Status/As an Error") {