Cleanup: Move RNA path functions into own C++ file

NOTE: This is committed to the 3.3 branch as part of D15606, which we
decided should go to this release still (by Bastien, Dalai and me). That
is because these are important usability fixes/improvements to have for
the LTS release.

Adds `rna_path.cc` and `RNA_path.h`.

`rna_access.c` is a quite big file, which makes it rather hard and
inconvenient to navigate. RNA path functions form a nicely coherent unit
that can stand well on it's own, so it makes sense to split them off to
mitigate the problem. Moreover, I was looking into refactoring the quite
convoluted/overloaded `rna_path_parse()`, and found that some C++
features may help greatly with that. So having that code compile in C++
would be helpful to attempt that.

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

Reviewed by: Brecht Van Lommel, Campbell Barton, Bastien Montagne

intern/cycles/blender/sync.h

@@ -7,6 +7,7 @@
 #include "MEM_guardedalloc.h"
 #include "RNA_access.h"
 #include "RNA_blender_cpp.h"
+#include "RNA_path.h"
 #include "RNA_types.h"
 
 #include "blender/id_map.h"

source/blender/blenkernel/intern/action.c

@@ -53,6 +53,7 @@
 #include "BIK_api.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 
 #include "BLO_read_write.h"

source/blender/blenkernel/intern/anim_data.c

@@ -43,6 +43,7 @@
 #include "BLO_read_write.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 
 #include "CLG_log.h"
 

source/blender/blenkernel/intern/anim_sys.c

@@ -53,6 +53,7 @@
 #include "DEG_depsgraph_query.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 
 #include "BLO_read_write.h"

source/blender/blenkernel/intern/fcurve.c

@@ -37,6 +37,7 @@
 #include "BLO_read_write.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 
 #include "CLG_log.h"
 

source/blender/blenkernel/intern/fcurve_driver.c

@@ -30,6 +30,7 @@
 #include "BKE_object.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 
 #include "atomic_ops.h"
 

source/blender/blenkernel/intern/key.c

@@ -46,6 +46,7 @@
 #include "BKE_scene.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 
 #include "BLO_read_write.h"

source/blender/blenkernel/intern/lib_override.cc

@@ -52,6 +52,7 @@
 #include "PIL_time.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 #include "RNA_types.h"
 

source/blender/depsgraph/intern/builder/deg_builder_cache.cc

@@ -15,6 +15,8 @@
 
 #include "BKE_animsys.h"
 
+#include "RNA_path.h"
+
 namespace blender::deg {
 
 /* Animated property storage. */

source/blender/depsgraph/intern/builder/deg_builder_nodes.cc

@@ -93,6 +93,7 @@
 #include "BKE_world.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 #include "RNA_types.h"
 

source/blender/depsgraph/intern/builder/deg_builder_relations.h

@@ -15,6 +15,7 @@
 #include "DNA_ID.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 #include "RNA_types.h"
 
 #include "BLI_string.h"

source/blender/depsgraph/intern/depsgraph_query.cc

@@ -23,6 +23,7 @@
 #include "DNA_scene_types.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 
 #include "DEG_depsgraph.h"

source/blender/draw/intern/draw_instance_data.c

@@ -27,6 +27,7 @@
 #include "BKE_duplilist.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 
 #include "BLI_bitmap.h"
 #include "BLI_memblock.h"

source/blender/editors/animation/anim_channels_defines.c

@@ -43,6 +43,7 @@
 #include "DNA_world_types.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 
 #include "BKE_anim_data.h"

source/blender/editors/animation/anim_deps.c

@@ -32,6 +32,7 @@
 #include "DEG_depsgraph.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 
 #include "SEQ_sequencer.h"
 #include "SEQ_utils.h"

source/blender/editors/animation/anim_draw.c

@@ -35,6 +35,7 @@
 #include "ED_keyframes_keylist.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 
 #include "UI_interface.h"
 #include "UI_resources.h"

source/blender/editors/animation/anim_ipo_utils.c

@@ -22,6 +22,7 @@
 #include "DNA_anim_types.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 
 #include "ED_anim_api.h"

source/blender/editors/animation/drivers.c

@@ -39,6 +39,7 @@
 
 #include "RNA_access.h"
 #include "RNA_define.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 
 #include "anim_intern.h"

source/blender/editors/animation/keyframes_general.c

@@ -29,6 +29,7 @@
 
 #include "RNA_access.h"
 #include "RNA_enum_types.h"
+#include "RNA_path.h"
 
 #include "ED_anim_api.h"
 #include "ED_keyframes_edit.h"

source/blender/editors/animation/keyframing.c

@@ -64,6 +64,7 @@
 #include "RNA_access.h"
 #include "RNA_define.h"
 #include "RNA_enum_types.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 
 #include "anim_intern.h"

source/blender/editors/animation/keyingsets.c

@@ -39,6 +39,7 @@
 #include "RNA_access.h"
 #include "RNA_define.h"
 #include "RNA_enum_types.h"
+#include "RNA_path.h"
 
 #include "anim_intern.h"
 

source/blender/editors/armature/pose_slide.c

@@ -53,6 +53,7 @@
 
 #include "RNA_access.h"
 #include "RNA_define.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 
 #include "WM_api.h"

source/blender/editors/armature/pose_utils.c

@@ -26,6 +26,7 @@
 #include "DEG_depsgraph.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 
 #include "WM_api.h"

source/blender/editors/interface/eyedroppers/eyedropper_driver.c

@@ -24,6 +24,7 @@
 
 #include "RNA_access.h"
 #include "RNA_define.h"
+#include "RNA_path.h"
 
 #include "UI_interface.h"
 

source/blender/editors/interface/interface_anim.c

@@ -35,6 +35,7 @@
 #include "UI_interface.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 
 #include "WM_api.h"
 #include "WM_types.h"

source/blender/editors/interface/interface_ops.c

@@ -40,6 +40,7 @@
 
 #include "RNA_access.h"
 #include "RNA_define.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 #include "RNA_types.h"
 

source/blender/editors/interface/interface_region_menu_pie.cc

@@ -27,6 +27,7 @@
 #include "WM_types.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 
 #include "UI_interface.h"

source/blender/editors/interface/interface_region_tooltip.c

@@ -39,6 +39,7 @@
 #include "WM_types.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 
 #include "UI_interface.h"
 

source/blender/editors/object/object_constraint.c

@@ -50,6 +50,7 @@
 #include "RNA_access.h"
 #include "RNA_define.h"
 #include "RNA_enum_types.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 
 #include "ED_keyframing.h"

source/blender/editors/screen/screen_user_menu.c

@@ -34,6 +34,7 @@
 #include "UI_resources.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 
 /* -------------------------------------------------------------------- */

source/blender/editors/space_console/space_console.c

@@ -20,6 +20,7 @@
 #include "ED_space_api.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 
 #include "WM_api.h"
 #include "WM_types.h"

source/blender/editors/space_graph/graph_buttons.c

@@ -41,6 +41,7 @@
 #include "WM_types.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 
 #include "ED_anim_api.h"

source/blender/editors/space_node/node_group.cc

@@ -36,6 +36,7 @@
 
 #include "RNA_access.h"
 #include "RNA_define.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 
 #include "WM_api.h"

source/blender/editors/space_outliner/outliner_edit.cc

@@ -55,6 +55,7 @@
 #include "RNA_access.h"
 #include "RNA_define.h"
 #include "RNA_enum_types.h"
+#include "RNA_path.h"
 
 #include "GPU_material.h"
 

source/blender/editors/space_text/space_text.c

@@ -30,6 +30,7 @@
 #include "UI_view2d.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 
 #include "text_format.h"
 #include "text_intern.h" /* own include */

source/blender/io/collada/BCAnimationCurve.cpp

@@ -1,6 +1,8 @@
 /* SPDX-License-Identifier: GPL-2.0-or-later
  * Copyright 2008 Blender Foundation. All rights reserved. */
 
+#include "RNA_path.h"
+
 #include "BCAnimationCurve.h"
 
 BCAnimationCurve::BCAnimationCurve()

source/blender/makesrna/RNA_access.h

@@ -475,247 +475,6 @@ bool RNA_property_copy(
 bool RNA_property_reset(PointerRNA *ptr, PropertyRNA *prop, int index);
 bool RNA_property_assign_default(PointerRNA *ptr, PropertyRNA *prop);
 
-/* Path
- *
- * Experimental method to refer to structs and properties with a string,
- * using a syntax like: scenes[0].objects["Cube"].data.verts[7].co
- *
- * This provides a way to refer to RNA data while being detached from any
- * particular pointers, which is useful in a number of applications, like
- * UI code or Actions, though efficiency is a concern. */
-
-char *RNA_path_append(
-    const char *path, const PointerRNA *ptr, PropertyRNA *prop, int intkey, const char *strkey);
-#if 0 /* UNUSED. */
-char *RNA_path_back(const char *path);
-#endif
-
-/**
- * Search for the start of the 'rna array index' part of the given `rna_path`.
- *
- * Given the root RNA pointer and resolved RNA property, and the RNA path, return the first
- * character in `rna_path` that is part of the array index for the given property. Return NULL if
- * none can be found, e.g. because the property is not an RNA array.
- *
- * \param array_prop: if not NULL, the #PropertyRNA assumed to be the last one from the RNA path.
- * Only used to ensure it is a valid array property.
- */
-const char *RNA_path_array_index_token_find(const char *rna_path, const PropertyRNA *array_prop);
-
-/* RNA_path_resolve() variants only ensure that a valid pointer (and optionally property) exist. */
-
-/**
- * Resolve the given RNA Path to find the pointer and/or property
- * indicated by fully resolving the path.
- *
- * \warning Unlike \a RNA_path_resolve_property(), that one *will* try to follow RNAPointers,
- * e.g. the path 'parent' applied to a RNAObject \a ptr will return the object.parent in \a r_ptr,
- * and a NULL \a r_prop...
- *
- * \note Assumes all pointers provided are valid
- * \return True if path can be resolved to a valid "pointer + property" OR "pointer only"
- */
-bool RNA_path_resolve(const PointerRNA *ptr,
-                      const char *path,
-                      PointerRNA *r_ptr,
-                      PropertyRNA **r_prop);
-
-/**
- * Resolve the given RNA Path to find the pointer and/or property + array index
- * indicated by fully resolving the path.
- *
- * \note Assumes all pointers provided are valid.
- * \return True if path can be resolved to a valid "pointer + property" OR "pointer only"
- */
-bool RNA_path_resolve_full(const PointerRNA *ptr,
-                           const char *path,
-                           PointerRNA *r_ptr,
-                           PropertyRNA **r_prop,
-                           int *r_index);
-/**
- * A version of #RNA_path_resolve_full doesn't check the value of #PointerRNA.data.
- *
- * \note While it's correct to ignore the value of #PointerRNA.data
- * most callers need to know if the resulting pointer was found and not null.
- */
-bool RNA_path_resolve_full_maybe_null(const PointerRNA *ptr,
-                                      const char *path,
-                                      PointerRNA *r_ptr,
-                                      PropertyRNA **r_prop,
-                                      int *r_index);
-
-/* RNA_path_resolve_property() variants ensure that pointer + property both exist. */
-
-/**
- * Resolve the given RNA Path to find both the pointer AND property
- * indicated by fully resolving the path.
- *
- * This is a convenience method to avoid logic errors and ugly syntax.
- * \note Assumes all pointers provided are valid
- * \return True only if both a valid pointer and property are found after resolving the path
- */
-bool RNA_path_resolve_property(const PointerRNA *ptr,
-                               const char *path,
-                               PointerRNA *r_ptr,
-                               PropertyRNA **r_prop);
-
-/**
- * Resolve the given RNA Path to find the pointer AND property (as well as the array index)
- * indicated by fully resolving the path.
- *
- * This is a convenience method to avoid logic errors and ugly syntax.
- * \note Assumes all pointers provided are valid
- * \return True only if both a valid pointer and property are found after resolving the path
- */
-bool RNA_path_resolve_property_full(const PointerRNA *ptr,
-                                    const char *path,
-                                    PointerRNA *r_ptr,
-                                    PropertyRNA **r_prop,
-                                    int *r_index);
-
-/* RNA_path_resolve_property_and_item_pointer() variants ensure that pointer + property both exist,
- * and resolve last Pointer value if possible (Pointer prop or item of a Collection prop). */
-
-/**
- * Resolve the given RNA Path to find both the pointer AND property
- * indicated by fully resolving the path, and get the value of the Pointer property
- * (or item of the collection).
- *
- * This is a convenience method to avoid logic errors and ugly syntax,
- * it combines both \a RNA_path_resolve and #RNA_path_resolve_property in a single call.
- * \note Assumes all pointers provided are valid.
- * \param r_item_ptr: The final Pointer or Collection item value.
- * You must check for its validity before use!
- * \return True only if both a valid pointer and property are found after resolving the path
- */
-bool RNA_path_resolve_property_and_item_pointer(const PointerRNA *ptr,
-                                                const char *path,
-                                                PointerRNA *r_ptr,
-                                                PropertyRNA **r_prop,
-                                                PointerRNA *r_item_ptr);
-
-/**
- * Resolve the given RNA Path to find both the pointer AND property (as well as the array index)
- * indicated by fully resolving the path,
- * and get the value of the Pointer property (or item of the collection).
- *
- * This is a convenience method to avoid logic errors and ugly syntax,
- * it combines both \a RNA_path_resolve_full and
- * \a RNA_path_resolve_property_full in a single call.
- * \note Assumes all pointers provided are valid.
- * \param r_item_ptr: The final Pointer or Collection item value.
- * You must check for its validity before use!
- * \return True only if both a valid pointer and property are found after resolving the path
- */
-bool RNA_path_resolve_property_and_item_pointer_full(const PointerRNA *ptr,
-                                                     const char *path,
-                                                     PointerRNA *r_ptr,
-                                                     PropertyRNA **r_prop,
-                                                     int *r_index,
-                                                     PointerRNA *r_item_ptr);
-
-typedef struct PropertyElemRNA PropertyElemRNA;
-struct PropertyElemRNA {
-  PropertyElemRNA *next, *prev;
-  PointerRNA ptr;
-  PropertyRNA *prop;
-  int index;
-};
-/**
- * Resolve the given RNA Path into a linked list of #PropertyElemRNA's.
- *
- * To be used when complex operations over path are needed, like e.g. get relative paths,
- * to avoid too much string operations.
- *
- * \return True if there was no error while resolving the path
- * \note Assumes all pointers provided are valid
- */
-bool RNA_path_resolve_elements(PointerRNA *ptr, const char *path, struct ListBase *r_elements);
-
-/**
- * Find the path from the structure referenced by the pointer to the runtime RNA-defined
- * #IDProperty object.
- *
- * \note Does *not* handle pure user-defined IDProperties (a.k.a. custom properties).
- *
- * \param ptr: Reference to the object owning the custom property storage.
- * \param needle: Custom property object to find.
- * \return Relative path or NULL.
- */
-char *RNA_path_from_struct_to_idproperty(PointerRNA *ptr, struct IDProperty *needle);
-
-/**
- * Find the actual ID pointer and path from it to the given ID.
- *
- * \param id: ID reference to search the global owner for.
- * \param[out] r_path: Path from the real ID to the initial ID.
- * \return The ID pointer, or NULL in case of failure.
- */
-struct ID *RNA_find_real_ID_and_path(struct Main *bmain, struct ID *id, const char **r_path);
-
-char *RNA_path_from_ID_to_struct(const PointerRNA *ptr);
-
-char *RNA_path_from_real_ID_to_struct(struct Main *bmain,
-                                      const PointerRNA *ptr,
-                                      struct ID **r_real);
-
-char *RNA_path_from_ID_to_property(const PointerRNA *ptr, PropertyRNA *prop);
-/**
- * \param index_dim: The dimension to show, 0 disables. 1 for 1d array, 2 for 2d. etc.
- * \param index: The *flattened* index to use when \a `index_dim > 0`,
- * this is expanded when used with multi-dimensional arrays.
- */
-char *RNA_path_from_ID_to_property_index(const PointerRNA *ptr,
-                                         PropertyRNA *prop,
-                                         int index_dim,
-                                         int index);
-
-char *RNA_path_from_real_ID_to_property_index(struct Main *bmain,
-                                              const PointerRNA *ptr,
-                                              PropertyRNA *prop,
-                                              int index_dim,
-                                              int index,
-                                              struct ID **r_real_id);
-
-/**
- * \return the path to given ptr/prop from the closest ancestor of given type,
- * if any (else return NULL).
- */
-char *RNA_path_resolve_from_type_to_property(const PointerRNA *ptr,
-                                             PropertyRNA *prop,
-                                             const struct StructRNA *type);
-
-/**
- * Get the ID as a python representation, eg:
- *   bpy.data.foo["bar"]
- */
-char *RNA_path_full_ID_py(struct Main *bmain, struct ID *id);
-/**
- * Get the ID.struct as a python representation, eg:
- *   bpy.data.foo["bar"].some_struct
- */
-char *RNA_path_full_struct_py(struct Main *bmain, const PointerRNA *ptr);
-/**
- * Get the ID.struct.property as a python representation, eg:
- *   bpy.data.foo["bar"].some_struct.some_prop[10]
- */
-char *RNA_path_full_property_py_ex(
-    struct Main *bmain, const PointerRNA *ptr, PropertyRNA *prop, int index, bool use_fallback);
-char *RNA_path_full_property_py(struct Main *bmain,
-                                const PointerRNA *ptr,
-                                PropertyRNA *prop,
-                                int index);
-/**
- * Get the struct.property as a python representation, eg:
- *   some_struct.some_prop[10]
- */
-char *RNA_path_struct_property_py(PointerRNA *ptr, PropertyRNA *prop, int index);
-/**
- * Get the struct.property as a python representation, eg:
- *   some_prop[10]
- */
-char *RNA_path_property_py(const PointerRNA *ptr, PropertyRNA *prop, int index);
-
 /* Quick name based property access
  *
  * These are just an easier way to access property values without having to

source/blender/makesrna/RNA_path.h

@@ -0,0 +1,259 @@
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+
+#pragma once
+
+/** \file
+ * \ingroup RNA
+ *
+ * RNA paths are a way to refer to pointers and properties with a string,
+ * using a syntax like: scenes[0].objects["Cube"].data.verts[7].co
+ *
+ * This provides a way to refer to RNA data while being detached from any
+ * particular pointers, which is useful in a number of applications, like
+ * UI code or Actions, though efficiency is a concern.
+ */
+
+#include "RNA_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+struct ListBase;
+struct IDProperty;
+
+char *RNA_path_append(
+    const char *path, const PointerRNA *ptr, PropertyRNA *prop, int intkey, const char *strkey);
+#if 0 /* UNUSED. */
+char *RNA_path_back(const char *path);
+#endif
+
+/**
+ * Search for the start of the 'rna array index' part of the given `rna_path`.
+ *
+ * Given the root RNA pointer and resolved RNA property, and the RNA path, return the first
+ * character in `rna_path` that is part of the array index for the given property. Return NULL if
+ * none can be found, e.g. because the property is not an RNA array.
+ *
+ * \param array_prop: if not NULL, the #PropertyRNA assumed to be the last one from the RNA path.
+ * Only used to ensure it is a valid array property.
+ */
+const char *RNA_path_array_index_token_find(const char *rna_path, const PropertyRNA *array_prop);
+
+/* RNA_path_resolve() variants only ensure that a valid pointer (and optionally property) exist. */
+
+/**
+ * Resolve the given RNA Path to find the pointer and/or property
+ * indicated by fully resolving the path.
+ *
+ * \warning Unlike \a RNA_path_resolve_property(), that one *will* try to follow RNAPointers,
+ * e.g. the path 'parent' applied to a RNAObject \a ptr will return the object.parent in \a r_ptr,
+ * and a NULL \a r_prop...
+ *
+ * \note Assumes all pointers provided are valid
+ * \return True if path can be resolved to a valid "pointer + property" OR "pointer only"
+ */
+bool RNA_path_resolve(const PointerRNA *ptr,
+                      const char *path,
+                      PointerRNA *r_ptr,
+                      PropertyRNA **r_prop);
+
+/**
+ * Resolve the given RNA Path to find the pointer and/or property + array index
+ * indicated by fully resolving the path.
+ *
+ * \note Assumes all pointers provided are valid.
+ * \return True if path can be resolved to a valid "pointer + property" OR "pointer only"
+ */
+bool RNA_path_resolve_full(const PointerRNA *ptr,
+                           const char *path,
+                           PointerRNA *r_ptr,
+                           PropertyRNA **r_prop,
+                           int *r_index);
+/**
+ * A version of #RNA_path_resolve_full doesn't check the value of #PointerRNA.data.
+ *
+ * \note While it's correct to ignore the value of #PointerRNA.data
+ * most callers need to know if the resulting pointer was found and not null.
+ */
+bool RNA_path_resolve_full_maybe_null(const PointerRNA *ptr,
+                                      const char *path,
+                                      PointerRNA *r_ptr,
+                                      PropertyRNA **r_prop,
+                                      int *r_index);
+
+/* RNA_path_resolve_property() variants ensure that pointer + property both exist. */
+
+/**
+ * Resolve the given RNA Path to find both the pointer AND property
+ * indicated by fully resolving the path.
+ *
+ * This is a convenience method to avoid logic errors and ugly syntax.
+ * \note Assumes all pointers provided are valid
+ * \return True only if both a valid pointer and property are found after resolving the path
+ */
+bool RNA_path_resolve_property(const PointerRNA *ptr,
+                               const char *path,
+                               PointerRNA *r_ptr,
+                               PropertyRNA **r_prop);
+
+/**
+ * Resolve the given RNA Path to find the pointer AND property (as well as the array index)
+ * indicated by fully resolving the path.
+ *
+ * This is a convenience method to avoid logic errors and ugly syntax.
+ * \note Assumes all pointers provided are valid
+ * \return True only if both a valid pointer and property are found after resolving the path
+ */
+bool RNA_path_resolve_property_full(const PointerRNA *ptr,
+                                    const char *path,
+                                    PointerRNA *r_ptr,
+                                    PropertyRNA **r_prop,
+                                    int *r_index);
+
+/* RNA_path_resolve_property_and_item_pointer() variants ensure that pointer + property both exist,
+ * and resolve last Pointer value if possible (Pointer prop or item of a Collection prop). */
+
+/**
+ * Resolve the given RNA Path to find both the pointer AND property
+ * indicated by fully resolving the path, and get the value of the Pointer property
+ * (or item of the collection).
+ *
+ * This is a convenience method to avoid logic errors and ugly syntax,
+ * it combines both \a RNA_path_resolve and #RNA_path_resolve_property in a single call.
+ * \note Assumes all pointers provided are valid.
+ * \param r_item_ptr: The final Pointer or Collection item value.
+ * You must check for its validity before use!
+ * \return True only if both a valid pointer and property are found after resolving the path
+ */
+bool RNA_path_resolve_property_and_item_pointer(const PointerRNA *ptr,
+                                                const char *path,
+                                                PointerRNA *r_ptr,
+                                                PropertyRNA **r_prop,
+                                                PointerRNA *r_item_ptr);
+
+/**
+ * Resolve the given RNA Path to find both the pointer AND property (as well as the array index)
+ * indicated by fully resolving the path,
+ * and get the value of the Pointer property (or item of the collection).
+ *
+ * This is a convenience method to avoid logic errors and ugly syntax,
+ * it combines both \a RNA_path_resolve_full and
+ * \a RNA_path_resolve_property_full in a single call.
+ * \note Assumes all pointers provided are valid.
+ * \param r_item_ptr: The final Pointer or Collection item value.
+ * You must check for its validity before use!
+ * \return True only if both a valid pointer and property are found after resolving the path
+ */
+bool RNA_path_resolve_property_and_item_pointer_full(const PointerRNA *ptr,
+                                                     const char *path,
+                                                     PointerRNA *r_ptr,
+                                                     PropertyRNA **r_prop,
+                                                     int *r_index,
+                                                     PointerRNA *r_item_ptr);
+
+typedef struct PropertyElemRNA PropertyElemRNA;
+struct PropertyElemRNA {
+  PropertyElemRNA *next, *prev;
+  PointerRNA ptr;
+  PropertyRNA *prop;
+  int index;
+};
+/**
+ * Resolve the given RNA Path into a linked list of #PropertyElemRNA's.
+ *
+ * To be used when complex operations over path are needed, like e.g. get relative paths,
+ * to avoid too much string operations.
+ *
+ * \return True if there was no error while resolving the path
+ * \note Assumes all pointers provided are valid
+ */
+bool RNA_path_resolve_elements(PointerRNA *ptr, const char *path, struct ListBase *r_elements);
+
+/**
+ * Find the path from the structure referenced by the pointer to the runtime RNA-defined
+ * #IDProperty object.
+ *
+ * \note Does *not* handle pure user-defined IDProperties (a.k.a. custom properties).
+ *
+ * \param ptr: Reference to the object owning the custom property storage.
+ * \param needle: Custom property object to find.
+ * \return Relative path or NULL.
+ */
+char *RNA_path_from_struct_to_idproperty(PointerRNA *ptr, struct IDProperty *needle);
+
+/**
+ * Find the actual ID pointer and path from it to the given ID.
+ *
+ * \param id: ID reference to search the global owner for.
+ * \param[out] r_path: Path from the real ID to the initial ID.
+ * \return The ID pointer, or NULL in case of failure.
+ */
+struct ID *RNA_find_real_ID_and_path(struct Main *bmain, struct ID *id, const char **r_path);
+
+char *RNA_path_from_ID_to_struct(const PointerRNA *ptr);
+
+char *RNA_path_from_real_ID_to_struct(struct Main *bmain,
+                                      const PointerRNA *ptr,
+                                      struct ID **r_real);
+
+char *RNA_path_from_ID_to_property(const PointerRNA *ptr, PropertyRNA *prop);
+/**
+ * \param index_dim: The dimension to show, 0 disables. 1 for 1d array, 2 for 2d. etc.
+ * \param index: The *flattened* index to use when \a `index_dim > 0`,
+ * this is expanded when used with multi-dimensional arrays.
+ */
+char *RNA_path_from_ID_to_property_index(const PointerRNA *ptr,
+                                         PropertyRNA *prop,
+                                         int index_dim,
+                                         int index);
+
+char *RNA_path_from_real_ID_to_property_index(struct Main *bmain,
+                                              const PointerRNA *ptr,
+                                              PropertyRNA *prop,
+                                              int index_dim,
+                                              int index,
+                                              struct ID **r_real_id);
+
+/**
+ * \return the path to given ptr/prop from the closest ancestor of given type,
+ * if any (else return NULL).
+ */
+char *RNA_path_resolve_from_type_to_property(const PointerRNA *ptr,
+                                             PropertyRNA *prop,
+                                             const struct StructRNA *type);
+
+/**
+ * Get the ID as a python representation, eg:
+ *   bpy.data.foo["bar"]
+ */
+char *RNA_path_full_ID_py(struct Main *bmain, struct ID *id);
+/**
+ * Get the ID.struct as a python representation, eg:
+ *   bpy.data.foo["bar"].some_struct
+ */
+char *RNA_path_full_struct_py(struct Main *bmain, const PointerRNA *ptr);
+/**
+ * Get the ID.struct.property as a python representation, eg:
+ *   bpy.data.foo["bar"].some_struct.some_prop[10]
+ */
+char *RNA_path_full_property_py_ex(
+    struct Main *bmain, const PointerRNA *ptr, PropertyRNA *prop, int index, bool use_fallback);
+char *RNA_path_full_property_py(struct Main *bmain,
+                                const PointerRNA *ptr,
+                                PropertyRNA *prop,
+                                int index);
+/**
+ * Get the struct.property as a python representation, eg:
+ *   some_struct.some_prop[10]
+ */
+char *RNA_path_struct_property_py(PointerRNA *ptr, PropertyRNA *prop, int index);
+/**
+ * Get the struct.property as a python representation, eg:
+ *   some_prop[10]
+ */
+char *RNA_path_property_py(const PointerRNA *ptr, PropertyRNA *prop, int index);
+
+#ifdef __cplusplus
+}
+#endif

source/blender/makesrna/intern/CMakeLists.txt

@@ -159,6 +159,7 @@ set(SRC_RNA_INC
   ../RNA_documentation.h
   ../RNA_enum_items.h
   ../RNA_enum_types.h
+  ../RNA_path.h
   ../RNA_types.h
 )
 
@@ -416,6 +417,7 @@ add_custom_command(
 set(SRC
   rna_access.c
   rna_access_compare_override.c
+  rna_path.cc
   ${GENSRC}
 
   ${SRC_RNA_INC}

source/blender/makesrna/intern/rna_access_compare_override.c

@@ -38,6 +38,7 @@
 #include "RNA_access.h"
 #include "RNA_define.h"
 #include "RNA_enum_types.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 
 #include "rna_access_internal.h"

source/blender/makesrna/intern/rna_access_internal.h

@@ -10,6 +10,10 @@
 
 #include "rna_internal_types.h"
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 struct IDProperty;
 struct PropertyRNAOrID;
 
@@ -26,3 +30,9 @@ void rna_property_rna_or_id_get(PropertyRNA *prop,
 
 void rna_idproperty_touch(struct IDProperty *idprop);
 struct IDProperty *rna_idproperty_find(PointerRNA *ptr, const char *name);
+
+PropertyRNA *rna_struct_find_nested(PointerRNA *ptr, StructRNA *srna);
+
+#ifdef __cplusplus
+}
+#endif

source/blender/makesrna/intern/rna_color.c

@@ -23,6 +23,7 @@
 #ifdef RNA_RUNTIME
 
 #  include "RNA_access.h"
+#  include "RNA_path.h"
 
 #  include "DNA_image_types.h"
 #  include "DNA_material_types.h"

source/blender/makesrna/intern/rna_internal.h

@@ -14,6 +14,10 @@
 
 #include "UI_resources.h"
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 #define RNA_MAGIC ((int)~0)
 
 struct AssetLibraryReference;
@@ -691,3 +695,7 @@ void rna_RenderPass_rect_set(PointerRNA *ptr, const float *values);
              : -FLT_MAX, double \
              : -DBL_MAX)
 #endif
+
+#ifdef __cplusplus
+}
+#endif

source/blender/python/intern/bpy_rna.c

@@ -15,6 +15,7 @@
 #include <float.h> /* FLT_MIN/MAX */
 #include <stddef.h>
 
+#include "RNA_path.h"
 #include "RNA_types.h"
 
 #include "BLI_bitmap.h"

source/blender/python/intern/bpy_rna_anim.c

@@ -32,6 +32,7 @@
 
 #include "RNA_access.h"
 #include "RNA_enum_types.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 
 #include "WM_api.h"

source/blender/windowmanager/intern/wm_operators.c

@@ -81,6 +81,7 @@
 #include "RNA_access.h"
 #include "RNA_define.h"
 #include "RNA_enum_types.h"
+#include "RNA_path.h"
 #include "RNA_prototypes.h"
 
 #include "UI_interface.h"

source/blender/windowmanager/message_bus/intern/wm_message_bus_rna.c

@@ -20,6 +20,7 @@
 #include "message_bus/intern/wm_message_bus_intern.h"
 
 #include "RNA_access.h"
+#include "RNA_path.h"
 
 /* -------------------------------------------------------------------- */
 /** \name Internal Utilities