[Helper] Deprecate findOrCreateAValidPath and introduce clearer funct…

…ions (sofa-framework#5264)

* [Helper] Fix findOrCreateAValidPath when given a file path

* [Helper] Fix findOrCreateAValidPath when given a file path

* Introduce clearer function names

* deprecate findOrCreateAValidPath

* restore previous findOrCreateAValidPath

Sofa/framework/Helper/src/sofa/helper/Utils.cpp

@@ -315,8 +315,8 @@ const std::string& Utils::getSofaUserLocalDirectory()
 {
     constexpr std::string_view sofaLocalDirSuffix = "SOFA";
 
-    static std::string sofaLocalDirectory = FileSystem::cleanPath(FileSystem::findOrCreateAValidPath(
-        FileSystem::append(getUserLocalDirectory(), sofaLocalDirSuffix)));
+    static const auto sofaLocalDirectory = FileSystem::cleanPath(FileSystem::append(getUserLocalDirectory(), sofaLocalDirSuffix));
+    FileSystem::ensureFolderExists(sofaLocalDirectory);
 
     return sofaLocalDirectory;
 }

Sofa/framework/Helper/src/sofa/helper/config.h.in

@@ -91,3 +91,11 @@ SOFA_ATTRIBUTE_DISABLED( \
 SOFA_ATTRIBUTE_DEPRECATED( \
 "v24.12", "v25.06", "This function is now in StringUtils.h")
 #endif // SOFA_BUILD_SOFA_HELPER
+
+#ifdef SOFA_BUILD_SOFA_HELPER
+#define SOFA_HELPER_FILESYSTEM_FINDORCREATEAVALIDPATH_DEPRECATED()
+#else
+#define SOFA_HELPER_FILESYSTEM_FINDORCREATEAVALIDPATH_DEPRECATED() \
+SOFA_ATTRIBUTE_DEPRECATED( \
+"v25.06", "v25.12", "It is not clear that this function works on folders or files. Use ensureFolderExists or ensureFolderForFileExists instead.")
+#endif // SOFA_BUILD_SOFA_HELPER

Sofa/framework/Helper/src/sofa/helper/system/FileSystem.cpp

@@ -388,7 +388,28 @@ std::string FileSystem::findOrCreateAValidPath(const std::string path)
     return path ;
 }
 
+void FileSystem::ensureFolderExists(const std::string& pathToFolder)
+{
+    if (!FileSystem::exists(pathToFolder))
+    {
+        const std::string parentPath = FileSystem::getParentDirectory(pathToFolder);
+        FileSystem::ensureFolderExists(parentPath);
 
+        if (FileSystem::exists(parentPath))
+        {
+            FileSystem::createDirectory(pathToFolder);
+        }
+    }
+}
+
+void FileSystem::ensureFolderForFileExists(const std::string& pathToFile)
+{
+    if (!FileSystem::exists(pathToFile))
+    {
+        const std::string parentPath = FileSystem::getParentDirectory(pathToFile);
+        FileSystem::ensureFolderExists(parentPath);
+    }
+}
 
 std::string FileSystem::cleanPath(const std::string& path, separator s)
 {

Sofa/framework/Helper/src/sofa/helper/system/FileSystem.h

@@ -93,12 +93,31 @@ static bool removeDirectory(const std::string& path);
 /// @return true on error
 static bool removeAll(const std::string& path) ;
 
+/// @brief The file or empty directory identified by the path is deleted
+///
+/// @return true if the file was deleted, false if it did not exist.
 static bool removeFile(const std::string& path);
 
 /// @brief check that all element in the path exists or create them. (This function accepts relative paths)
 ///
 /// @return the valid path.
-static std::string findOrCreateAValidPath(const std::string path) ;
+SOFA_HELPER_FILESYSTEM_FINDORCREATEAVALIDPATH_DEPRECATED()
+static std::string findOrCreateAValidPath(const std::string path);
+
+/// @brief Ensures that a folder exists at the specified path. If the folder does not exist, it will be created.
+///
+/// @param pathToFolder The path of the folder to ensure exists.
+///
+/// @note The function assumes that a path to a folder is given.
+static void ensureFolderExists(const std::string& pathToFolder);
+
+/// @brief Ensures that the folder containing the specified file path exists. If the folder does not
+/// exist, it will be created. If the file does not exist, it will not be created.
+///
+/// @param pathToFile The path to the file. The function ensures that the directory containing this file exists.
+///
+/// @note The function assumes that a path to a file is given.
+static void ensureFolderForFileExists(const std::string& pathToFile);
 
 /// @brief Return true if and only if the given file exists.
 static bool exists(const std::string& path);

Sofa/framework/Helper/test/system/FileSystem_test.cpp

@@ -22,6 +22,7 @@
 #include <sofa/testing/config.h>
 
 #include <sofa/helper/system/FileSystem.h>
+#include <sofa/helper/Utils.h>
 #include <gtest/gtest.h>
 #include <sofa/helper/logging/MessageDispatcher.h>
 #include <exception>
@@ -359,3 +360,69 @@ TEST(FileSystemTest, append)
     EXPECT_EQ(FileSystem::append("a/b/c/d/", "e", "/f", "/g"), "a/b/c/d/e/f/g");
     EXPECT_EQ(FileSystem::append("a/b/c/d/", "/e", "/f", "/g"), "a/b/c/d/e/f/g");
 }
+
+TEST(FileSystemTest, ensureFolderExists)
+{
+    ASSERT_TRUE(FileSystem::isDirectory(sofa::helper::Utils::getSofaPathPrefix()));
+
+    const auto parentDir = FileSystem::append(sofa::helper::Utils::getSofaPathPrefix(), "test_folder");
+    const auto dir = FileSystem::append(parentDir, "another_layer");
+
+    //the folders don't exist yet
+    EXPECT_FALSE(FileSystem::isDirectory(parentDir));
+    EXPECT_FALSE(FileSystem::isDirectory(dir));
+
+    FileSystem::ensureFolderExists(dir);
+
+    EXPECT_TRUE(FileSystem::isDirectory(parentDir));
+    EXPECT_TRUE(FileSystem::isDirectory(dir));
+
+    //cleanup
+    EXPECT_FALSE(FileSystem::removeDirectory(dir));
+    EXPECT_FALSE(FileSystem::removeDirectory(parentDir));
+}
+
+TEST(FileSystemTest, ensureFolderForFileExists_fileAndFolderDontExist)
+{
+    ASSERT_TRUE(FileSystem::isDirectory(sofa::helper::Utils::getSofaPathPrefix()));
+
+    const auto parentDir = FileSystem::append(sofa::helper::Utils::getSofaPathPrefix(), "test_folder");
+    const auto dir = FileSystem::append(parentDir, "another_layer");
+
+    //the folder does not exist yet
+    EXPECT_FALSE(FileSystem::isDirectory(dir));
+
+    const auto file = FileSystem::append(dir, "file.txt");
+    FileSystem::ensureFolderForFileExists(file);
+
+    EXPECT_TRUE(FileSystem::isDirectory(dir));
+    EXPECT_FALSE(FileSystem::isDirectory(file));
+
+    EXPECT_FALSE(FileSystem::exists(file));
+
+    //cleanup
+    EXPECT_FALSE(FileSystem::removeDirectory(dir));
+    EXPECT_FALSE(FileSystem::removeDirectory(parentDir));
+}
+
+TEST(FileSystemTest, ensureFolderForFileExists_fileExist)
+{
+    ASSERT_TRUE(FileSystem::isDirectory(sofa::helper::Utils::getSofaPathPrefix()));
+
+    const auto file = FileSystem::append(sofa::helper::Utils::getSofaPathPrefix(), "file.txt");
+    EXPECT_FALSE(FileSystem::exists(file));
+
+    std::ofstream fileStream;
+    fileStream.open(file);
+    fileStream << "Hello";
+    fileStream.close();
+
+    EXPECT_TRUE(FileSystem::exists(file));
+
+    FileSystem::ensureFolderForFileExists(file);
+
+    EXPECT_TRUE(FileSystem::exists(file));
+
+    //cleanup
+    EXPECT_TRUE(FileSystem::removeFile(file));
+}