container: plugins: root: add examples

container/plugins/root/example.cc

@@ -0,0 +1,144 @@
+// docker-finance | modern accounting for the power-user
+//
+// Copyright (C) 2024 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.0.0
+
+// NOTE: API headers are included by default
+
+//! \namespace docker_finance::plugin
+//! \brief docker-finance plugins
+//! \warning All plugins (repo/custom) must exist within this namespace
+//!          and work within their own inner namespace
+//! \since docker-finance 1.0.0
+namespace docker_finance::plugin
+{
+//! \namespace docker_finance::plugin::my_plugin_namespace
+//! \brief docker-finance plugin example namespace
+//! \details An example namespace used only within this example file
+//! \warning Not a real namespace - for example purposes only
+//! \since docker-finance 1.0.0
+namespace my_plugin_namespace
+{
+//! \brief Example plugin function 1
+//! \details Directly access docker-finance crypto abstractions and
+//!       print hundreds of SHA2-256 libsodium-generated hashes of
+//!       Crypto++-generated cryptographically secure random numbers
+//! \ingroup cpp_plugin_impl
+void example1()
+{
+  using g_Random = docker_finance::crypto::cryptopp::Random;
+  using g_Hash = docker_finance::crypto::libsodium::Hash;
+  g_Random r;
+  g_Hash h;
+  for (size_t i{}; i < std::numeric_limits<uint8_t>::max(); i++)
+    {
+      uint32_t num = r.generate();
+      std::cout << h.encode<g_Hash::SHA2_256>(num) << " = " << num << "\n";
+    }
+}
+
+//! \brief Example plugin function 2
+//! \details Directly access underlying docker-finance shell environment
+//! \ingroup cpp_plugin_impl
+void example2()
+{
+  namespace common = ::docker_finance::macro::common;
+
+  auto print_env = [](const std::string& env) {
+    std::cout << env << "=" << common::get_env(env) << "\n";
+  };
+
+  // Container env
+  std::cout
+      << "\nShell environment (container)\n-----------------------------\n";
+  print_env("DOCKER_FINANCE_CLIENT_FLOW");
+  print_env("DOCKER_FINANCE_CONTAINER_CMD");
+  print_env("DOCKER_FINANCE_CONTAINER_CONF");
+  print_env("DOCKER_FINANCE_CONTAINER_EDITOR");
+  print_env("DOCKER_FINANCE_CONTAINER_FLOW");
+  print_env("DOCKER_FINANCE_CONTAINER_PLUGINS");
+  print_env("DOCKER_FINANCE_CONTAINER_REPO");
+  print_env("DOCKER_FINANCE_CONTAINER_SHARED");
+  print_env("DOCKER_FINANCE_DEBUG");
+  print_env("DOCKER_FINANCE_VERSION");
+
+  std::cout << "\nSame as previous but executing commands in "
+               "shell\n------------------------------------------------\n";
+  common::exec("printenv | grep ^DOCKER_FINANCE | sort");
+
+  // Caller env
+  std::cout << "\nShell environment (caller)\n--------------------------\n";
+  print_env("global_arg_delim_1");
+  print_env("global_arg_delim_2");
+  print_env("global_arg_delim_3");
+  print_env("global_arg_subcommand");
+  print_env("global_basename");
+  print_env("global_child_profile");
+  print_env("global_child_profile_flow");
+  print_env("global_child_profile_journal");
+  print_env("global_conf_fetch");
+  print_env("global_conf_hledger");
+  print_env("global_conf_meta");
+  print_env("global_conf_shell");
+  // TODO(unassigned): read array from shell? ROOT impl simply calls stdlib getenv()
+  // print_env("global_hledger_cmd");
+  print_env("global_parent_profile");
+  print_env("global_usage");
+}
+
+//! \brief Example plugin function 3
+//! \details Execute docker-finance shell commands
+//! \ingroup cpp_plugin_impl
+void example3()
+{
+  namespace common = ::docker_finance::macro::common;
+
+  const std::string base{
+      common::get_env("global_basename") + " "
+      + common::get_env("global_parent_profile")
+      + common::get_env("global_arg_delim_1")
+      + common::get_env("global_child_profile") + " "};
+
+  auto make_cmd = [&base](const std::string& arg) {
+    return std::string{base + arg};
+  };
+
+  auto exec_cmd = [&make_cmd](const std::string& cmd) {
+    // shell 0 = success
+    THROW_IF(common::exec(make_cmd(cmd)), std::runtime_error, "command failed")
+  };
+
+  std::cout << "\nImporting journals...\n";
+  exec_cmd("import 1>/dev/null");
+
+  std::cout << "\nShowing BTC balance...\n";
+  exec_cmd("hledger bal assets liabilities cur:BTC");
+
+  std::cout << "\nGenerating income tax snippet...\n";
+  const std::string delim{common::get_env("global_arg_delim_2")};
+  exec_cmd(
+      "taxes all" + delim + "account tag" + delim + "income write" + delim
+      + "off | tail -n3");
+}
+
+}  // namespace my_plugin_namespace
+}  // namespace docker_finance::plugin
+
+// # vim: sw=2 sts=2 si ai et