feat(file_system): Add remove(path) and remove_contents(path) (#267)

* feat(file_system): Add remove(path) and remove_contents(path)

* update readme.

Author: finger563

components/file_system/example/README.md

@@ -26,5 +26,5 @@ See the Getting Started Guide for full steps to configure and use ESP-IDF to bui
 
 ## Example Output
 
-![CleanShot 2024-06-28 at 09 08 19](https://github.com/esp-cpp/espp/assets/213467/ae2791b0-e240-4a55-808d-fed00335b4e4)
+![CleanShot 2024-07-01 at 13 57 50](https://github.com/esp-cpp/espp/assets/213467/dd45e8eb-6927-403b-a889-86274cfeeb76)
 

components/file_system/example/main/file_system_example.cpp

@@ -39,6 +39,7 @@ extern "C" void app_main(void) {
   }
 
   const std::string_view test_dir = "sandbox";
+  const std::string_view sub_dir = "subdir";
   const std::string_view test_file = "test.csv";
   const std::string_view file_contents = "Hello World!";
   // use posix api
@@ -108,6 +109,22 @@ extern "C" void app_main(void) {
       logger.info("Renamed '{}' to '{}'", file, file2);
     }
 
+    // make a subdirectory
+    std::string sub = sandbox + "/" + std::string(sub_dir);
+    mkdir(sub.c_str(), 0755);
+    logger.info("Created subdirectory {}", sub);
+
+    // make a file in the subdirectory
+    std::string sub_file = sub + "/subfile.txt";
+    FILE *sub_fp = fopen(sub_file.c_str(), "w");
+    if (sub_fp == nullptr) {
+      logger.error("Couldn't open {} for writing!", sub_file);
+    } else {
+      fwrite(file_contents.data(), 1, file_contents.size(), sub_fp);
+      fclose(sub_fp);
+      logger.info("Wrote '{}' to {}", file_contents, sub_file);
+    }
+
     // list files in a directory
     auto &fs = espp::FileSystem::get();
     espp::FileSystem::ListConfig config;
@@ -146,7 +163,7 @@ extern "C" void app_main(void) {
     }
 
     // cleanup
-    auto items = {file, file2, sandbox};
+    auto items = {sub_file, sub, file, file2, sandbox};
     for (auto &item : items) {
       // use stat to figure out if it exists
       auto code = stat(item.c_str(), &st);
@@ -234,6 +251,24 @@ extern "C" void app_main(void) {
       logger.info("Renamed {} to {}", file.string(), file2.string());
     }
 
+    // make a subdirectory
+    fs::path sub = sandbox / fs::path{sub_dir};
+    fs::create_directory(sub, ec);
+    if (ec) {
+      logger.error("Could not create directory {} - {}", sub.string(), ec.message());
+    } else {
+      logger.info("Created subdirectory {}", sub.string());
+    }
+
+    // make a file in the subdirectory
+    fs::path sub_file = sub / "subfile.txt";
+    std::ofstream sub_ofs(sub_file);
+    sub_ofs << file_contents;
+    sub_ofs.close();
+    sub_ofs.flush();
+    logger.info("Wrote '{}' to {}", file_contents, sub_file.string());
+
+    // list files in a directory
     logger.info("Directory iterator:");
     logger.warn(
         "NOTE: directory_iterator is not implemented in esp-idf right now :( (as of v5.2.2)");
@@ -247,23 +282,30 @@ extern "C" void app_main(void) {
       logger.info("\tThis is expected since directory_iterator is not implemented in esp-idf.");
     }
 
-    // cleanup
-    auto items = {file, file2, sandbox};
-    for (const auto &item : items) {
-      if (!fs::exists(item)) {
-        logger.warn("Not removing '{}', it doesn't exist!", item.string());
-        continue;
-      }
-      // and if it is a directory
-      bool is_dir = fs::is_directory(item);
-      auto err = is_dir ? rmdir(item.string().c_str()) : unlink(item.string().c_str());
-      if (err) {
-        logger.error("Could not remove {}, error code: {}", item.string(), err);
-      } else {
-        logger.info("Cleaned up {}", item.string());
-      }
-      // fs::remove(item, ec); // NOTE: cannot use fs::remove since it seems POSIX remove()
-      // doesn't work
+    logger.info("Recursive directory listing:");
+    auto &espp_fs = espp::FileSystem::get();
+    auto files = espp_fs.get_files_in_path(sandbox, true, true);
+    for (const auto &f : files) {
+      logger.info("\t{}", f);
+    }
+
+    // cleanup, use convenience functions
+    // NOTE: cannot use fs::remove since it seems POSIX remove() doesn't work
+    // We'll use espp::FileSystem::remove, which works for both files and
+    // directories, and will recursively remove all the contents of the
+    // directory.
+    espp_fs.set_log_level(espp::Logger::Verbosity::DEBUG);
+    if (!espp_fs.remove(sandbox, ec)) {
+      logger.error("Could not remove {}", sandbox.string());
+    } else {
+      logger.info("Cleaned up {}", sandbox.string());
+    }
+
+    // now list entries in root (recursively) after cleanup
+    logger.info("Recursive directory listing after cleanup:");
+    files = espp_fs.get_files_in_path(espp_fs.get_root_path(), true, true);
+    for (const auto &f : files) {
+      logger.info("\t{}", f);
     }
     //! [file_system std filesystem example]
   }

components/file_system/include/file_system.hpp

@@ -161,6 +161,27 @@ class FileSystem : public BaseComponent {
                                                        bool include_directories = false,
                                                        bool recursive = false);
 
+  /// @brief Completely remove a file or directory (including contents)
+  /// @details This method removes a file or directory and all of its contents.
+  ///          If the path is a directory, it will iterate over the contents
+  ///          and remove them recursively. If the path is a file, it will
+  ///          remove the file. If the path does not exist, it will return false.
+  /// @param path The path to the file or directory
+  /// @param ec The error code to set if an error occurs
+  /// @return Whether the file or directory was successfully removed
+  bool remove(const std::filesystem::path &path, std::error_code &ec);
+
+  /// @brief Remove the contents of a directory, but not the directory itself
+  /// @details This method removes the contents of a directory, but not the
+  ///          directory itself. If the path is not a directory, it will return
+  ///          false. If the path does not exist, it will return false. If the
+  ///          path is a directory, it will iterate over the contents and remove
+  ///          them recursively.
+  /// @param path The path to the directory
+  /// @param ec The error code to set if an error occurs
+  /// @return Whether the contents of the directory were successfully removed
+  bool remove_contents(const std::filesystem::path &path, std::error_code &ec);
+
   /// @brief List the contents of a directory
   /// @details
   /// This method lists the contents of a directory. It returns a string
@@ -238,5 +259,19 @@ class FileSystem : public BaseComponent {
   /// This method initializes the file system. It is protected and called only by the constructor.
   /// It is responsible for mounting the file system and creating the root directory.
   void init();
+
+  /// @brief Remove a file
+  /// @param path The path to the file
+  /// @return Whether the file was successfully removed
+  bool remove_file(const std::filesystem::path &path);
+
+  /// @brief Remove an empty directory
+  /// @param path The path to the empty directory
+  /// @return Whether the directory was successfully removed
+  /// @note This method does not remove the contents of the directory, only the
+  ///       directory itself.
+  /// @warning If the directory is not empty, it will not be removed, and the
+  ///          method will return false.
+  bool remove_directory(const std::filesystem::path &path);
 };
 } // namespace espp

components/file_system/src/file_system.cpp

@@ -121,6 +121,46 @@ std::vector<std::filesystem::path> FileSystem::get_files_in_path(const std::file
   return files;
 }
 
+bool FileSystem::remove(const std::filesystem::path &path, std::error_code &ec) {
+  logger_.debug("Removing path: {}", path.string());
+  namespace fs = std::filesystem;
+  auto file_status = fs::status(path, ec);
+  if (std::filesystem::is_directory(file_status)) {
+    if (!remove_contents(path, ec)) {
+      logger_.error("Failed to remove contents of directory: {}", path.string());
+      return false;
+    }
+    return remove_directory(path);
+  } else {
+    return remove_file(path);
+  }
+}
+
+bool FileSystem::remove_file(const std::filesystem::path &path) {
+  logger_.debug("Removing file: {}", path.string());
+  return unlink(path.c_str()) == 0;
+}
+
+bool FileSystem::remove_directory(const std::filesystem::path &path) {
+  logger_.debug("Removing directory: {}", path.string());
+  return rmdir(path.c_str()) == 0;
+}
+
+bool FileSystem::remove_contents(const std::filesystem::path &path, std::error_code &ec) {
+  logger_.debug("Removing contents of directory: {}", path.string());
+  bool include_directories = true;
+  bool recursive = false; // don't want recursive since we'll already recurse
+  auto files = get_files_in_path(path, include_directories, recursive);
+  bool success = true;
+  for (const auto &file : files) {
+    if (!remove(file, ec)) {
+      logger_.error("Failed to remove file: {}", file.string());
+      success = false;
+    }
+  }
+  return success;
+}
+
 std::string FileSystem::list_directory(const std::string &path, const ListConfig &config,
                                        const std::string &prefix) {
   std::string result;