Refactor BKE_bpath module.

The main goal of this refactor is to make BPath module use `IDTypeInfo`,
and move each ID-specific part of the `foreach_path` looper into their
own IDTypeInfo struct, using a new `foreach_path` callback.

Additionally, following improvements/cleanups are included:
* Attempt to get better, more consistent namings.
** In particular, move from `path_visitor` to more standard `foreach_path`.
* Update and extend documentation.
** API doc was moved to header, according to recent discussions on this
   topic.
* Remove `BKE_bpath_relocate_visitor` from API, this is specific
  callback that belongs in `lib_id.c` user code.

NOTE: This commit is expected to be 100% non-behavioral-change. This
implies that several potential further changes were only noted as
comments (like using a more generic solution for
`lib_id_library_local_paths`, addressing inconsistencies like path of
packed libraries always being skipped, regardless of the
`BKE_BPATH_FOREACH_PATH_SKIP_PACKED` `eBPathForeachFlag` flag value,
etc.).

NOTE: basic unittests were added to master already in
rBdcc500e5a265093bc9cc.

Reviewed By: brecht

Differential Revision: https://developer.blender.org/D13381

1 files changed, 45 insertions, 5 deletions

diff --git a/source/blender/blenkernel/intern/lib_id.c b/source/blender/blenkernel/intern/lib_id.c
index 0b0ed199981..d41e81a07b5 100644
--- a/source/blender/blenkernel/intern/lib_id.c
+++ b/source/blender/blenkernel/intern/lib_id.c
@@ -107,6 +107,8 @@ IDTypeInfo IDType_ID_LINK_PLACEHOLDER = {
     .make_local = NULL,
     .foreach_id = NULL,
     .foreach_cache = NULL,
+    .foreach_path = NULL,
+    .owner_get = NULL,
 
     .blend_write = NULL,
     .blend_read_data = NULL,
@@ -125,18 +127,56 @@ IDTypeInfo IDType_ID_LINK_PLACEHOLDER = {
 /* ************* general ************************ */
 
 /**
+ * Rewrites a relative path to be relative to the main file - unless the path is
+ * absolute, in which case it is not altered.
+ */
+static bool lib_id_library_local_paths_callback(BPathForeachPathData *bpath_data,
+                                                char *r_path_dst,
+                                                const char *path_src)
+{
+  const char **data = bpath_data->user_data;
+  /* be sure there is low chance of the path being too short */
+  char filepath[(FILE_MAXDIR * 2) + FILE_MAXFILE];
+  const char *base_new = data[0];
+  const char *base_old = data[1];
+
+  if (BLI_path_is_rel(base_old)) {
+    CLOG_ERROR(&LOG, "old base path '%s' is not absolute.", base_old);
+    return false;
+  }
+
+  /* Make referenced file absolute. This would be a side-effect of
+   * BLI_path_normalize, but we do it explicitly so we know if it changed. */
+  BLI_strncpy(filepath, path_src, FILE_MAX);
+  if (BLI_path_abs(filepath, base_old)) {
+    /* Path was relative and is now absolute. Remap.
+     * Important BLI_path_normalize runs before the path is made relative
+     * because it won't work for paths that start with "//../" */
+    BLI_path_normalize(base_new, filepath);
+    BLI_path_rel(filepath, base_new);
+    BLI_strncpy(r_path_dst, filepath, FILE_MAX);
+    return true;
+  }
+
+  /* Path was not relative to begin with. */
+  return false;
+}
+
+/**
  * This has to be called from each make_local_* func, we could call from BKE_lib_id_make_local()
  * but then the make local functions would not be self contained.
  * Also note that the id _must_ have a library - campbell */
+/* TODO: This can probably be replaced by an ID-level version of #BKE_bpath_relative_rebase. */
 static void lib_id_library_local_paths(Main *bmain, Library *lib, ID *id)
 {
   const char *bpath_user_data[2] = {BKE_main_blendfile_path(bmain), lib->filepath_abs};
 
-  BKE_bpath_traverse_id(bmain,
-                        id,
-                        BKE_bpath_relocate_visitor,
-                        BKE_BPATH_TRAVERSE_SKIP_MULTIFILE,
-                        (void *)bpath_user_data);
+  BKE_bpath_foreach_path_id(
+      &(BPathForeachPathData){.bmain = bmain,
+                              .callback_function = lib_id_library_local_paths_callback,
+                              .flag = BKE_BPATH_FOREACH_PATH_SKIP_MULTIFILE,
+                              .user_data = (void *)bpath_user_data},
+      id);
 }
 
 static int lib_id_clear_library_data_users_update_cb(LibraryIDLinkCallbackData *cb_data)