error: add errmsg_raw utility

demo/error.c

@@ -51,7 +51,7 @@ void error_demo(void)
 	catch(&err) {
 		/* this will only be executed if the callee yeeted an error */
 		printf("  fails() failed with code %u: %s\n",
-			errnum(&err), nstr_raw(errmsg(&err)));
+			errnum(&err), errmsg_raw(&err));
 
 		/*
 		 * you always need to call errput() in the outermost function,
@@ -67,7 +67,7 @@ void error_demo(void)
 	succeeds(2, &err);
 	catch(&err) {
 		printf("  succeeds() failed with code %u: %s\n",
-			errnum(&err), nstr_raw(errmsg(&err)));
+			errnum(&err), errmsg_raw(&err));
 		errput(&err);
 	}
 
@@ -75,7 +75,7 @@ void error_demo(void)
 	chain(3, &err);
 	catch(&err) {
 		printf("  chain() failed with code %u: %s\n",
-			errnum(&err), nstr_raw(errmsg(&err)));
+			errnum(&err), errmsg_raw(&err));
 		errput(&err);
 	}
 }

include/neo/_error.h

@@ -8,6 +8,27 @@
 /**
  * @defgroup error Error Handling
  *
+ * libneo has a standardized way of handling errors: If a function is somehow
+ * able to fail at runtime, for example because of invalid parameters or lack of
+ * system resources, it accepts an argument of type `error *` which is usually
+ * the last one in the parameter list.  When such a function is called and it
+ * encounters a runtime error, it `yeet()`s that error, does cleanup work if
+ * required, and then returns an undefined value.  If the function call was
+ * successful, this is indicated by `neat()`.  Functions accepting an `error *`
+ * parameter **MUST** always call either `yeet()` or `neat()`, but not both.
+ *
+ * If you call such a function, you have two options.  If you don't want to deal
+ * with error handling, you can simply pass in `nil`, which will print the error
+ * message to stderr and cause the program to terminate if an error is
+ * `yeet()`ed.  This is useful for quick prototyping and situations where
+ * encountering an error would be so critical that your program would need to
+ * halt anyway.  To actually handle errors, you declare a local variable of type
+ * `error` and pass its address to the function.  Then, immediately after the
+ * call, use the `catch()` macro to handle the error.  In the error handler,
+ * you must call `errput()` to release resources attached to the error.
+ *
+ * See `demo/error.c` in the source code repository for examples.
+ *
  * @{
  */
 
@@ -57,7 +78,7 @@ void errput(error *err);
  * by `err` is an actual error, i.e. it has been `yeet()`ed to.
  * Resources for the error must be released using `errput()`.
  */
-#define ncatch(err) if ((err) != nil && (err)->_number != 0)
+#define ncatch(err) if ((err) != nil && (err)->_number + 1 >= 2)
 #ifndef __cplusplus
 	/**
 	 * @brief Catch an error.
@@ -86,7 +107,19 @@ void errput(error *err);
  * @param err `error *` to get the message of
  * @returns The error message, may be `nil`
  */
-#define errmsg(err) ((err) == nil ? (nstr_t *)nil : (err)->_message)
+#define errmsg(err) ((err) == nil ? (nstr_t *)0 : (err)->_message)
+
+/**
+ * @brief Get an optional error message as a raw C string.
+ *
+ * @param err `error *` to get the message of
+ * @returns The error message as a `const char *`, may be `nil`
+ */
+#define errmsg_raw(err) (				\
+	( (err) != nil && (err)->_message != nil )	\
+		? nstr_raw((err)->_message)		\
+		: (const char *)0			\
+)
 
 /** @} */