add map function to targets

Author: goatshriek

include/private/entry.h

@@ -1,7 +1,7 @@
 /* SPDX-License-Identifier: Apache-2.0 */
 
 /*
- * Copyright 2018-2024 Joel E. Anderson
+ * Copyright 2018-2025 Joel E. Anderson
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -385,7 +385,8 @@ strbuilder_append_structured_data( struct strbuilder *builder,
  * Not safe in the context of asynchronous cancellation due to potential resource
  * cleanup issues.
  *
- * @since release v1.5.0lock_entry
+ * @since release v1.5.0
+ *
  * @param entry A pointer to the entry to be destroyed. Must not be NULL.
  */
 void

include/stumpless/filter.h

@@ -1,7 +1,7 @@
 /* SPDX-License-Identifier: Apache-2.0 */
 
 /*
- * Copyright 2022 Joel E. Anderson
+ * Copyright 2022-2025 Joel E. Anderson
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,16 +24,16 @@
  */
 
 #ifndef __STUMPLESS_FILTER_H
-#  define __STUMPLESS_FILTER_H
+#define __STUMPLESS_FILTER_H
 
-#  include <stdbool.h>
-#  include <stumpless/config.h>
-#  include <stumpless/entry.h>
-#  include <stumpless/target.h>
+#include <stdbool.h>
+#include <stumpless/config.h>
+#include <stumpless/entry.h>
+#include <stumpless/target.h>
 
-#  ifdef __cplusplus
+#ifdef __cplusplus
 extern "C" {
-#  endif
+#endif
 
 /**
  * Compares the severity of the entry to the current mask of the target, and
@@ -49,24 +49,27 @@ extern "C" {
  *
  * **Async Cancel Safety: AC-Unsafe lock**
  * This function is not safe to call from threads that may be asynchronously
- * cancelled, due to the use of a lock that could be left locked..
+ * cancelled, due to the use of a lock that could be left locked.
  *
  * @since release v2.1.0
  *
  * @param target The target that the entry will be sent to if it passes.
  *
  * @param entry The entry that is being submitted to the target.
  *
+ * @param data Unused.
+ *
  * @return true if the severity of the entry is set in the target's mask,
  * false otherwise.
  */
 STUMPLESS_PUBLIC_FUNCTION
 bool
 stumpless_mask_filter( const struct stumpless_target *target,
-                       const struct stumpless_entry *entry );
+                       const struct stumpless_entry *entry,
+                       void *data );
 
-#  ifdef __cplusplus
+#ifdef __cplusplus
 } /* extern "C" */
-#  endif
+#endif
 
 #endif /* __STUMPLESS_FILTER_H */

include/stumpless/target.h

@@ -128,11 +128,41 @@ struct stumpless_target;
  * @param entry The entry that is being submitted to the target. Will not be
  * NULL when called during logging.
  *
+ * @param data A pointer to data that may hold anything that the filter function
+ * needs to use in addition to the target and entry.
+ *
  * @return true if the entry should be sent to the target, false if not.
  */
 typedef bool ( *stumpless_filter_func_t )(
   const struct stumpless_target *target,
-  const struct stumpless_entry *entry );
+  const struct stumpless_entry *entry,
+  void *data );
+
+/**
+ * A function that maps a given entry to another.
+ *
+ * Map functions are useful for adding, removing, or otherwise modifying an
+ * entry before it is logged to a target. They return a pointer to the mapped
+ * entry.
+ *
+ * Map functions should not modify the entry they operate on. If no modification
+ * is needed, then it is better to simply not specify a map function.
+ *
+ * @since release v3.0.0
+ *
+ * @param target The target that the map function was called as part of.
+ *
+ * @param entry The entry that this map function will base its output on.
+ *
+ * @param data A pointer to data that may hold anything that the map function
+ * needs to use in addition to the target and entry.
+ *
+ * @return A pointer to the mapped entry.
+ */
+typedef struct stumpless_entry * ( *stumpless_map_func_t )(
+  const struct stumpless_target *target,
+  const struct stumpless_entry *entry,
+  void *data );
 
 /**
  * A target that log entries can be sent to.
@@ -188,6 +218,30 @@ struct stumpless_target {
  * @since release v2.1.0
  */
   stumpless_filter_func_t filter;
+/**
+ * A pointer to data which may be used by the filter function.
+ *
+ * @since release v3.0.0
+ */
+  void *filter_data;
+/**
+ * A mapping function which will map the entry the target recieved to one that
+ * will be logged. This supports things including redacting specific items,
+ * adding new elements automatically, or mapping element or parameter values to
+ * other entry fields.
+ *
+ * If present, the map function is called after the filter, before the entry is
+ * logged to the target.
+ *
+ * @since release v3.0.0
+ */
+  stumpless_map_func_t map;
+/**
+  * A pointer to data which may be used by the map function.
+  *
+  * @since release v3.0.0
+  */
+  void *map_data;
 #ifdef STUMPLESS_THREAD_SAFETY_SUPPORTED
 /**
  * A pointer to a mutex which protects all target fields. The exact type of

src/filter.c

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /*
- * Copyright 2022 Joel E. Anderson
+ * Copyright 2022-2025 Joel E. Anderson
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,7 +23,10 @@
 
 bool
 stumpless_mask_filter( const struct stumpless_target *target,
-                       const struct stumpless_entry *entry ) {
+                       const struct stumpless_entry *entry,
+                       void *data ) {
+  (void) data;
+
   return STUMPLESS_SEVERITY_MASK( stumpless_get_entry_severity( entry ) )
            & stumpless_get_target_mask( target );
 }

src/target.c

@@ -210,7 +210,7 @@ stumpless_add_entry( struct stumpless_target *target,
   }
 
   filter = stumpless_get_target_filter( target );
-  if( filter && !filter( target, entry ) ) {
+  if( filter && !filter( target, entry, target->filter_data ) ) {
     return 0;
   }
 
@@ -1174,6 +1174,9 @@ new_target( enum stumpless_target_type type, const char *name ) {
   target->default_msgid_length = 1;
   target->mask = STUMPLESS_SEVERITY_MASK_UPTO( STUMPLESS_SEVERITY_DEBUG_VALUE );
   target->filter = stumpless_mask_filter;
+  target->filter_data = NULL;
+  target->map = NULL;
+  target->map_data = NULL;
 
   return target;