client/container: root: refactor common namespace

- Factor out respective common from macro and apply to all scopes
  * `dfi::common`
  * `dfi::macro::common`
  * `dfi::plugin::common`

- Add deprecation warnings in `dfi::macro::common`
  * Common functionality (not macro specific) is now in `dfi::common`

- Add convenience wrappers to inner common impl, where appropriate
  * Allows for backwards compatibility

- Add/update/clarify code docs and Doxygen definitions

- Related refactoring

NOTE: all changes are backward compatible (no need to bump major).

container/src/root/common/utility.hh

@@ -0,0 +1,134 @@
+// docker-finance | modern accounting for the power-user
+//
+// Copyright (C) 2021-2025 Aaron Fiore (Founder, Evergreen Crypto LLC)
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+//! \file
+//! \author Aaron Fiore (Founder, Evergreen Crypto LLC)
+//! \note File intended to be loaded into ROOT.cern framework / Cling interpreter
+//! \since docker-finance 1.1.0
+
+#ifndef CONTAINER_SRC_ROOT_COMMON_UTILITY_HH_
+#define CONTAINER_SRC_ROOT_COMMON_UTILITY_HH_
+
+#include <ctime>
+#include <filesystem>
+#include <initializer_list>
+#include <iostream>
+#include <string>
+#include <vector>
+
+//! \namespace dfi
+//! \since docker-finance 1.0.0
+namespace dfi
+{
+//! \namespace dfi::common
+//! \brief Shared common functionality
+//! \since docker-finance 1.1.0
+namespace common
+{
+//! \brief Wrapper to ROOT Cling commands
+//! \ingroup cpp_common_impl
+//! \since docker-finance 1.0.0
+class Command
+{
+ public:
+  Command() = default;
+  ~Command() = default;
+
+  Command(const Command&) = default;
+  Command& operator=(const Command&) = default;
+
+  Command(Command&&) = default;
+  Command& operator=(Command&&) = default;
+
+ private:
+  static void cmd_handler(const std::initializer_list<std::string>& command)
+  {
+    for (const auto& cmd : command)
+      {
+        std::cout << "Interpreting: '" << cmd << "'" << std::endl;
+        gInterpreter->ProcessLine(cmd.c_str());
+      }
+  }
+
+ public:
+  //! \brief Load given file path
+  static void load(const std::string& path)
+  {
+    std::filesystem::path p(path);
+    if (!std::filesystem::exists(p))
+      {
+        throw std::runtime_error(
+            std::string{"'" + path + "' does not exist!"}.c_str());
+      }
+    if (!std::filesystem::is_regular_file(p))
+      {
+        throw std::runtime_error(
+            std::string{"'" + path + "' is not a regular file!"}.c_str());
+      }
+
+    std::string cmd{".L " + path};
+    Command::cmd_handler({cmd});
+  }
+
+  //! \brief Load given file paths
+  static void load(const std::initializer_list<std::string>& commands)
+  {
+    for (const auto& cmd : commands)
+      Command::load(cmd);
+  }
+
+  // TODO(afiore): unload
+};
+
+//! \brief Get ROOT environment variable
+//! \param var ROOT variable
+//! \note ROOT environment variables include shell (and shell caller) environment
+//! \since docker-finance 1.0.0
+std::string get_env(const std::string& var)
+{
+  const auto* env = gSystem->Getenv(var.c_str());
+  if (!env)
+    throw std::runtime_error(
+        std::string{var + " is not set or is unavailable"}.c_str());
+  return std::string{env};
+}
+
+//! \brief Execute command in shell
+//! \param cmd Shell command [args]
+//! \returns Return value of command
+//! \since docker-finance 1.0.0
+int exec(const std::string& cmd)
+{
+  return gSystem->Exec(cmd.c_str());
+}
+
+//! \brief Make current timestamp
+//! \return timestamp in "yyyy-mm-ddThh:mm:ssZ" format
+//! \since docker-finance 1.0.0
+std::string make_timestamp()
+{
+  const std::time_t t{std::time({})};
+  std::vector<char> time(std::size("yyyy-mm-ddThh:mm:ssZ"));
+  std::strftime(time.data(), time.size(), "%FT%TZ", std::gmtime(&t));
+  return std::string{time.data()};
+}
+}  // namespace common
+}  // namespace dfi
+
+#endif  // CONTAINER_SRC_ROOT_COMMON_UTILITY_HH_
+
+// # vim: sw=2 sts=2 si ai et