Add FilePath utility class for handling resource / file paths in MuJoCo user code.

PiperOrigin-RevId: 651716008
Change-Id: I250b8cec32aab538f5862f8a05f42d1fae698307

src/user/user_util.cc

@@ -14,12 +14,18 @@
 
 #include "user/user_util.h"
 
+#include <algorithm>
+#include <cctype>
 #include <cmath>
 #include <cstddef>
 #include <cstdio>
+#include <cstring>
 #include <optional>
+#include <sstream>
 #include <string>
 #include <string_view>
+#include <utility>
+#include <vector>
 
 #include <mujoco/mujoco.h>
 #include "engine/engine_crossplatform.h"
@@ -934,3 +940,131 @@ std::string mjuu_extToContentType(std::string_view filename) {
     return "";
   }
 }
+
+namespace mujoco::user {
+
+std::string FilePath::Combine(const std::string& s1, const std::string& s2) {
+  // str2 has absolute path
+  if (!AbsPrefix(s2).empty()) {
+    return s2;
+  }
+
+  std::size_t n = s1.size();
+  if (n > 0 && s1[n - 1] != '\\' && s1[n - 1] != '/') {
+    return s1 + "/" + s2;
+  }
+  return s1 + s2;
+}
+
+std::string FilePath::PathReduce(const std::string& str) {
+  std::vector<std::string> dirs;
+  std::string abs_prefix = AbsPrefix(str);
+
+  int j = abs_prefix.size();
+
+  for (int i = j; i < str.size(); ++i) {
+    if (IsSeperator(str[i])) {
+      std::string temp = str.substr(j, i - j);
+      j = i + 1;
+      if (temp == ".." && !dirs.empty()) {
+        dirs.pop_back();
+      } else if (temp != ".") {
+        dirs.push_back(std::move(temp));
+      }
+    }
+  }
+
+  // push the rest of the string
+  dirs.push_back(str.substr(j, str.size() - j));
+
+  // join the path
+  std::stringstream path;
+  auto it = dirs.begin();
+  path << abs_prefix << *it++;
+  for (; it != dirs.end(); ++it) {
+    path << "/" << *it;
+  }
+  return path.str();
+}
+
+FilePath FilePath::operator+(const FilePath& path) const {
+  return FilePath(path_, path.path_);
+}
+
+std::string FilePath::Ext() const {
+  std::size_t n = path_.find_last_of('.');
+
+  if (n == std::string::npos) {
+    return "";
+  }
+  return path_.substr(n, path_.size() - n);
+}
+
+FilePath FilePath::StripExt() const {
+  size_t n = path_.find_last_of('.');
+
+  // no extension
+  if (n == std::string::npos) {
+    return FilePathFast(path_);
+  }
+
+  // return path without extension
+  return FilePathFast(path_.substr(0, n));
+}
+
+
+// is directory absolute path
+std::string FilePath::AbsPrefix(const std::string& str) {
+  // empty: not absolute
+  if (str.empty()) {
+    return "";
+  }
+
+  // path is scheme:filename which we consider an absolute path
+  // e.g. file URI's are always absolute paths
+  const mjpResourceProvider* provider = mjp_getResourceProvider(str.c_str());
+  if (provider != nullptr) {
+    std::size_t n = std::strlen(provider->prefix);
+    return str.substr(0, n + 1);
+  }
+
+  // check first char
+  if (str[0] == '\\' || str[0] == '/') {
+    return str.substr(0, 1);
+  }
+
+  // find ":/" or ":\"
+  std::size_t pos = str.find(":/");
+  if (pos != std::string::npos) {
+    return str.substr(0, pos + 2);
+  }
+
+  pos = str.find(":\\");
+  if (pos != std::string::npos) {
+    return str.substr(0, pos + 2);
+  }
+
+  return "";
+}
+
+FilePath FilePath::StripPath() const {
+  // find last path symbol
+  std::size_t n = path_.find_last_of("/\\");
+
+  // no path
+  if (n == std::string::npos) {
+    return FilePathFast(path_);
+  }
+
+  return FilePathFast(path_.substr(n + 1, path_.size() - (n + 1)));
+}
+
+std::string FilePath::StrLower() const {
+  std::string str = path_;
+  std::transform(str.begin(), str.end(), str.begin(),
+                 [](unsigned char c) { return std::tolower(c); });
+  return str;
+}
+
+}  // namespace mujoco::user
+

src/user/user_util.h

@@ -15,11 +15,11 @@
 #ifndef MUJOCO_SRC_USER_USER_UTIL_H_
 #define MUJOCO_SRC_USER_USER_UTIL_H_
 
+#include <cstddef>
 #include <optional>
 #include <string>
 #include <string_view>
 
-
 const double mjEPS = 1E-14;     // minimum value in various calculations
 const double mjMINMASS = 1E-6;  // minimum mass allowed
 
@@ -155,6 +155,83 @@ void mjuu_trnVecPose(double res[3], const double pos[3], const double quat[4], c
 // compute frame quat and diagonal inertia from full inertia matrix, return error if any
 const char* mjuu_fullInertia(double quat[4], double inertia[3], const double fullinertia[6]);
 
+namespace mujoco::user {
+
+// utility class for handling file paths
+class FilePath {
+ public:
+  FilePath() = default;
+  explicit FilePath(const std::string& str) : path_(PathReduce(str)) {}
+  explicit FilePath(const char* str) { path_ = PathReduce(str); }
+  FilePath(const std::string& str1, const std::string& str2) {
+    path_ = PathReduce(Combine(str1, str2));
+  }
+  FilePath(FilePath&& other) = default;
+  FilePath& operator=(FilePath&& other) = default;
+  FilePath(const FilePath&) = default;
+  FilePath& operator=(const FilePath&) = default;
+
+  // return true if the path is absolute
+  bool IsAbs() const { return !AbsPrefix(path_).empty(); }
+
+  // return string with the absolute prefix of the path
+  // e.g. "c:\", "http://", etc
+  std::string AbsPrefix() const { return AbsPrefix(path_); }
+
+  // return copy of the internal path string
+  const std::string& Str() const { return path_; }
+
+  // return copy of the internal path string in lower case
+  // (for case insensitive purposes)
+  std::string StrLower() const;
+
+  // return the extension of the file path (e.g. "hello.txt" -> ".txt")
+  std::string Ext() const;
+
+  // concatenate two paths together
+  FilePath operator+(const FilePath& path) const;
+
+  // return a new FilePath with the extension stripped
+  FilePath StripExt() const;
+
+  // return a new FilePath with the path stripped
+  FilePath StripPath() const;
+
+  // return a new FilePath with path lower cased
+  FilePath Lower() const { return FilePathFast(StrLower()); }
+
+  // C++ string methods
+  std::size_t size() const { return path_.size(); }
+  const char* c_str() const { return path_.c_str(); }
+  bool empty() const { return path_.empty(); }
+  char operator[](int i) const { return path_[i]; }
+
+ private:
+  static std::string AbsPrefix(const std::string& str);
+  static std::string PathReduce(const std::string& str);
+  static bool IsSeperator(char c) {
+    return c == '/' || c == '\\';
+  }
+  static std::string Combine(const std::string& s1, const std::string& s2);
+
+  // fast constructor that does not call PathReduce
+  static FilePath FilePathFast(const std::string& str) {
+    FilePath path;
+    path.path_ = str;
+    return path;
+  }
+
+  static FilePath FilePathFast(std::string&& str) {
+    FilePath path;
+    path.path_ = str;
+    return path;
+  }
+
+  std::string path_;
+};
+
+}  // namespace mujoco::user
+
 // strip path from filename
 std::string mjuu_strippath(std::string filename);
 

src/user/user_vfs.cc

@@ -14,8 +14,6 @@
 
 #include "user/user_vfs.h"
 
-#include <algorithm>
-#include <cctype>
 #include <cstddef>
 #include <cstring>
 #include <cstdint>
@@ -31,9 +29,11 @@
 
 namespace {
 
+using mujoco::user::FilePath;
+
 // internal struct for VFS files
 struct VFSFile {
-  std::string filename;
+  FilePath filename;
   std::vector<uint8_t> filedata;
   std::size_t filesize;
   uint64_t filestamp;
@@ -43,18 +43,18 @@ struct VFSFile {
 class VFS {
  public:
   // returns true if the file exists in the VFS
-  bool HasFile(const std::string& filename) const;
+  bool HasFile(const FilePath& filename) const;
 
   // returns inserted mjuuVFSFile if the file was added successfully. This class
   // assumes ownership of the buffer.
-  VFSFile* AddFile(const std::string& filename, std::vector<uint8_t>&& buffer,
+  VFSFile* AddFile(const FilePath& filename, std::vector<uint8_t>&& buffer,
                    uint64_t filestamp);
 
   // returns the internal file struct for the given filename
-  const VFSFile* GetFile(const std::string& filename) const;
+  const VFSFile* GetFile(const FilePath& filename) const;
 
   // deletes file from VFS, return 0: success, -1: not found
-  int DeleteFile(const std::string& filename);
+  int DeleteFile(const FilePath& filename);
 
  private:
   std::unordered_map<std::string, VFSFile> files_;
@@ -66,13 +66,8 @@ inline VFS* GetVFSImpl(const mjVFS* vfs) {
 }
 
 // strip path prefix from filename and make lowercase
-std::string StripPath(const char* name) {
+FilePath StripPath(const char* filename) {
-  std::string newname = mjuu_strippath(name);
+  return FilePath(filename).StripPath().Lower();
-
-  // make lowercase
-  std::transform(newname.begin(), newname.end(), newname.begin(),
-                 [](unsigned char c) { return std::tolower(c); });
-  return newname;
 }
 
 // copies data into a buffer and produces a hash of the data
@@ -103,13 +98,13 @@ uint64_t vfs_hash(const std::vector<uint8_t>& buffer) {
   return hash;
 }
 
-bool VFS::HasFile(const std::string& filename) const {
+bool VFS::HasFile(const FilePath& filename) const {
-  return files_.find(filename) != files_.end();
+  return files_.find(filename.Str()) != files_.end();
 }
 
-VFSFile* VFS::AddFile(const std::string& filename, std::vector<uint8_t>&& buffer,
+VFSFile* VFS::AddFile(const FilePath& filename, std::vector<uint8_t>&& buffer,
                       uint64_t filestamp) {
-  auto [it, inserted] = files_.insert({filename, VFSFile()});
+  auto [it, inserted] = files_.insert({filename.Str(), VFSFile()});
   if (!inserted) {
     return nullptr;  // repeated name
   }
@@ -119,16 +114,16 @@ VFSFile* VFS::AddFile(const std::string& filename, std::vector<uint8_t>&& buffer
   return &(it->second);
 }
 
-const VFSFile* VFS::GetFile(const std::string& filename) const {
+const VFSFile* VFS::GetFile(const FilePath& filename) const {
-  auto it = files_.find(filename);
+  auto it = files_.find(filename.Str());
   if (it == files_.end()) {
     return nullptr;
   }
   return &it->second;
 }
 
-int VFS::DeleteFile(const std::string& filename) {
+int VFS::DeleteFile(const FilePath& filename) {
-  auto it = files_.find(filename);
+  auto it = files_.find(filename.Str());
   if (it == files_.end()) {
     return -1;
   }
@@ -221,10 +216,10 @@ int mj_addFileVFS(mjVFS* vfs, const char* directory, const char* filename) {
   VFS* cvfs = GetVFSImpl(vfs);
 
   // make full name
-  std::string fullname = mjuu_combinePaths(directory, filename);
+  FilePath fullname = FilePath(directory, filename);
 
   // strip path
-  std::string newname = StripPath(filename);
+  FilePath newname = StripPath(filename);
 
   // check beforehand for repeated name, to avoid reading file into memory
   if (cvfs->HasFile(newname)) {

test/user/user_resource_test.cc

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Tests for user/user_resource.c
+// Tests for user/user_resource.cc
 
 #include <array>
 #include <cstdint>

test/user/user_util_test.cc

@@ -0,0 +1,108 @@
+// Copyright 2024 DeepMind Technologies Limited
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Tests for user/user_util.cc
+
+#include "src/user/user_util.h"
+
+#include <gtest/gtest.h>
+
+namespace mujoco {
+namespace {
+
+using user::FilePath;
+
+TEST(UserUtilTest, PathReduce) {
+  FilePath path = FilePath("/hello/.././world/");
+  EXPECT_EQ(path.Str(), "/world/");
+}
+
+TEST(UserUtilTest, PathReduce2) {
+  FilePath path = FilePath("../hello/./world/");
+  EXPECT_EQ(path.Str(), "../hello/world/");
+}
+
+TEST(UserUtilTest, PathReduceWin) {
+  FilePath path = FilePath("C:\\hello\\..\\world");
+  EXPECT_EQ(path.Str(), "C:\\world");
+}
+
+TEST(UserUtilTest, IsAbs) {
+  EXPECT_TRUE(FilePath("/hello").IsAbs());
+  EXPECT_TRUE(FilePath("C:\\hello").IsAbs());
+  EXPECT_FALSE(FilePath("hello").IsAbs());
+}
+
+TEST(UserUtilTest, Combine) {
+  FilePath path1 = FilePath("/hello");
+  FilePath path2 = FilePath("world");
+  EXPECT_EQ((path1 + path2).Str(), "/hello/world");
+}
+
+TEST(UserUtilTest, Combine2) {
+  FilePath path1 = FilePath("hello/");
+  FilePath path2 = FilePath("world");
+  EXPECT_EQ((path1 + path2).Str(), "hello/world");
+}
+
+TEST(UserUtilTest, Combine3) {
+  FilePath path1 = FilePath("/hello");
+  FilePath path2 = FilePath("../world");
+  EXPECT_EQ((path1 + path2).Str(), "/world");
+}
+
+TEST(UserUtilTest, CombineAbs) {
+  FilePath path1 = FilePath("/hello");
+  FilePath path2 = FilePath("/world");
+  EXPECT_EQ((path1 + path2).Str(), "/world");
+}
+
+TEST(UserUtilTest, Ext) {
+  FilePath path = FilePath("/hello/world.txt");
+  EXPECT_EQ(path.Ext(), ".txt");
+}
+
+TEST(UserUtilTest, ExtEmpty) {
+  FilePath path = FilePath("/hello/world");
+  EXPECT_EQ(path.Ext(), "");
+}
+
+TEST(UserUtilTest, StripExt) {
+  FilePath path = FilePath("/hello/world.txt");
+  EXPECT_EQ(path.StripExt().Str(), "/hello/world");
+}
+
+TEST(UserUtilTest, StripPath) {
+  FilePath path = FilePath("/hello/world.txt");
+  EXPECT_EQ(path.StripPath().Str(), "world.txt");
+}
+
+TEST(UserUtilTest, StripPathEmpty) {
+  FilePath path = FilePath("world.txt");
+  EXPECT_EQ(path.StripPath().Str(), "world.txt");
+}
+
+TEST(UserUtilTest, StripPathWin) {
+  FilePath path = FilePath("\\world.txt");
+  EXPECT_EQ(path.StripPath().Str(), "world.txt");
+}
+
+
+TEST(UserUtilTest, StrLower) {
+  FilePath path = FilePath("/HELLO/worlD.txt");
+  EXPECT_EQ(path.StrLower(), "/hello/world.txt");
+}
+
+}  // namespace
+}  // namespace mujoco