Main program class that manages modules, plugins, and command-line parsing. More...

#include <CLI/MaCh3Program.hpp>

Inheritance diagram for M3::MaCh3Program:

Collaboration diagram for M3::MaCh3Program:

Public Member Functions
virtual	~MaCh3Program ()
	Destructor that unloads all dynamic plugins. More...

void	add_core_module (IModule &module)
	Add a core module to the program. More...

void	load_dynamic_plugins ()
	Load dynamic plugins from the MACH3_PLUGINS environment variable. More...

void	install_completions () const
	Install shell completion scripts for bash and zsh. More...

void	completions (const std::string &prefix, const std::vector< std::string > &context) const
	Generate completion suggestions given the current prefix and preceding words. More...

void	unload_dynamic_plugins ()
	Unload all dynamically loaded plugins. More...

int	Run ()
	Run the selected subcommand. More...

Public Member Functions inherited from M3::MaCh3ArgumentParser
virtual	~MaCh3ArgumentParser ()=default

const std::string	name () const
	Get the name of this parser/subcommand. More...

const std::list< std::reference_wrapper< ArgumentParser > > &	subparsers () const
	Get the list of registered subparsers. More...

const MaCh3ArgumentParser &	get_subcommand_used () const
	Get the subcommand that was used in parsing. More...

std::vector< std::string >	get_long_option_names () const
	Return all long option names (–xxx) registered with this parser. More...

bool	option_takes_value (const std::string &name) const
	Return true if the named option expects a value (not a flag) More...

Private Member Functions
std::string	detect_shell () const
	Detect the user's shell from the SHELL environment variable. More...

bool	write_file (const fs::path &path, std::string_view content) const
	Write content to a file, creating parent directories if needed. More...

std::vector< std::string >	expand_plugin_path (const std::string &path) const
	Expand a plugin path (file or directory) into a list of .so files. More...

Private Attributes
std::vector< std::string >	m_subcommands
	List of registered subcommand names. More...

std::map< const MaCh3ArgumentParser , IModule >	m_module_map
	Map of parsers to core modules (non-owning) More...

std::map< const MaCh3ArgumentParser *, std::unique_ptr< DynamicPlugin > >	m_dynamic_plugin_map
	Map of parsers to dynamic plugins (owning) More...

Static Private Attributes
static constexpr std::string_view	BASH_COMPLETION

static constexpr std::string_view	ZSH_COMPLETION

Detailed Description

Main program class that manages modules, plugins, and command-line parsing.

This class extends MaCh3ArgumentParser to provide functionality for:

Managing core modules and dynamic plugins
Installing and generating shell completions
Running selected subcommands

Author: Alexander Richards

Definition at line 25 of file MaCh3Program.hpp.

Constructor & Destructor Documentation

◆ ~MaCh3Program()

virtual M3::MaCh3Program::~MaCh3Program ( )

inlinevirtual

Destructor that unloads all dynamic plugins.

Definition at line 30 of file MaCh3Program.hpp.

                                    {
                 //std::cout<<"UNLOADED"<< std::endl;
                 this->unload_dynamic_plugins();
             }

Member Function Documentation

◆ add_core_module()

void M3::MaCh3Program::add_core_module ( IModule & module )

Add a core module to the program.

Parameters

module Reference to the module to be added

Definition at line 171 of file MaCh3Program.cpp.

                                                      {
         MaCh3ArgumentParser* parser = module.get_parser();
         this->add_subparser(*parser);
         m_module_map[parser] = &module;
         m_subcommands.push_back(parser->name());
     }

◆ completions()

void M3::MaCh3Program::completions	(	const std::string &	prefix,
		const std::vector< std::string > &	context
	)		const

Generate completion suggestions given the current prefix and preceding words.

Parameters

prefix	The partially-typed word being completed
context	Words already typed after the program name but before prefix

Definition at line 88 of file MaCh3Program.cpp.

                                                                                                      {
         // Find the active subcommand from previously typed context words
         std::string active_subcommand;
         for (const auto& word : context) {
             for (const auto& sub : m_subcommands) {
                 if (word == sub) {
                     active_subcommand = sub;
                     break;
                 }
             }
             if (!active_subcommand.empty()) break;
         }
  
         if (active_subcommand.empty()) {
             // No subcommand typed yet — complete top-level subcommand names
             for (const auto& cmd : m_subcommands) {
                 if (cmd.rfind(prefix, 0) == 0)
                     std::cout << cmd << "\n";
             }
             return;
         }
  
         // Find the parser for the active subcommand
         const MaCh3ArgumentParser* sub_parser = nullptr;
         for (const auto& [parser, mod] : m_module_map) {
             if (parser->name() == active_subcommand) { sub_parser = parser; break; }
         }
         if (!sub_parser) {
             for (const auto& [parser, plug] : m_dynamic_plugin_map) {
                 if (parser->name() == active_subcommand) { sub_parser = parser; break; }
             }
         }
         if (!sub_parser) return; // unknown subcommand — fall back to files
  
         // If the last context word is an option that expects a value argument,
         // output nothing so the shell falls back to file completion.
         if (!context.empty()) {
             const std::string& prev = context.back();
             if (prev.size() >= 2 && prev[0] == '-') {
                 if (sub_parser->option_takes_value(prev)) {
                     return; // option takes a value — let the shell complete files
                 }
             }
         }
  
         // Complete long option names when the prefix starts with '-'
         if (!prefix.empty() && prefix[0] == '-') {
             for (const auto& name : sub_parser->get_long_option_names()) {
                 if (name.rfind(prefix, 0) == 0)
                     std::cout << name << "\n";
             }
             return;
         }
         // Non-option prefix (or empty) — output nothing, shell falls back to files
     }

◆ detect_shell()

std::string M3::MaCh3Program::detect_shell ( ) const

private

Detect the user's shell from the SHELL environment variable.

Returns: Shell name ("bash", "zsh", or empty string if not detected)

Definition at line 28 of file MaCh3Program.cpp.

                                               {
         const char* shell = std::getenv("SHELL");
         if (!shell) return "";
  
         std::string s(shell);
         if (s.find("bash") != std::string::npos) return "bash";
         if (s.find("zsh")  != std::string::npos) return "zsh";
  
         return "";
     }

◆ expand_plugin_path()

std::vector< std::string > M3::MaCh3Program::expand_plugin_path ( const std::string & path ) const

private

Expand a plugin path (file or directory) into a list of .so files.

Expand a plugin path to a list of shared library files.

Parameters

path	Path to a plugin file or directory containing plugins

Returns: Vector of plugin file paths

If the path is a file, returns it directly. If it's a directory, returns all .so files found in that directory.

Parameters

path	Path to a plugin file or directory

Returns: Vector of absolute paths to .so files

Definition at line 255 of file MaCh3Program.cpp.

                                                                                      {
         std::vector<std::string> result;
  
         fs::path p(path);
  
         if (!fs::exists(p)) {
             std::cerr << "Plugin path does not exist: " << path << "\n";
             return result;
         }
  
         if (fs::is_regular_file(p)) {
             // Single .so file
             result.push_back(path);
         }
         else if (fs::is_directory(p)) {
             // Load all .so files in directory
             for (auto& entry : fs::directory_iterator(p)) {
                 if (entry.is_regular_file() && entry.path().extension() == ".so") {
                     result.push_back(entry.path().string());
                 }
             }
         }
         else {
             std::cerr << "Invalid plugin path (not file or directory): " << path << "\n";
         }
  
         return result;
     }

◆ install_completions()

void M3::MaCh3Program::install_completions ( ) const

Install shell completion scripts for bash and zsh.

Definition at line 39 of file MaCh3Program.cpp.

                                                 {
         const char* home = std::getenv("HOME");
         if (!home) {
             std::cerr << "Cannot determine HOME directory\n";
             return;
         }
  
         std::string shell = detect_shell();
         if (shell.empty()) {
             std::cerr << "Could not detect your shell. Supported: bash, zsh\n";
             return;
         }
  
         // Resolve the absolute path of this binary so the completion script
         // works even when mach3 is not on PATH.
         std::string binary_path = "mach3";
         try {
             binary_path = fs::read_symlink("/proc/self/exe").string();
         } catch (...) {}
  
         // Replace the generic "mach3" invocation in the template with the
         // absolute binary path so the script is self-contained.
         auto embed_path = [&](std::string_view tmpl) -> std::string {
             std::string s(tmpl);
             const std::string placeholder = "mach3 --complete";
             const std::string replacement = binary_path + " --complete";
             for (std::size_t pos = s.find(placeholder); pos != std::string::npos;
                  pos = s.find(placeholder, pos + replacement.size()))
                 s.replace(pos, placeholder.size(), replacement);
             return s;
         };
  
         fs::path home_path(home);
  
         if (shell == "bash") {
             fs::path path = home_path / ".local/share/bash-completion/completions/mach3";
             if (write_file(path, embed_path(MaCh3Program::BASH_COMPLETION)))
                 std::cout << "Installed bash completions → " << path << "\n";
             return;
         }
  
         if (shell == "zsh") {
             fs::path path = home_path / ".local/share/zsh/site-functions/_mach3";
             if (write_file(path, embed_path(MaCh3Program::ZSH_COMPLETION)))
                 std::cout << "Installed zsh completions → " << path << "\n";
             return;
         }
     }

◆ load_dynamic_plugins()

void M3::MaCh3Program::load_dynamic_plugins ( )

Load dynamic plugins from the MACH3_PLUGINS environment variable.

Load dynamic plugins from paths specified in MACH3_PLUGINS environment variable.

Reads the MACH3_PLUGINS environment variable (colon-separated paths), loads each .so file, and registers the plugins with the program. Each plugin must export create_plugin and destroy_plugin functions.

Definition at line 183 of file MaCh3Program.cpp.

                                            {
         const char* env = std::getenv("MACH3_PLUGINS");
         if (!env) {
             //std::cerr << "No plugins specified\n";
             return;
         }
  
         std::stringstream ss(env);
         std::string path;
  
         while (std::getline(ss, path, ':')) {
             for (const auto& sofile : this->expand_plugin_path(path)) {
                 try{
                     std::unique_ptr<DynamicPlugin> dlplugin = std::make_unique<DynamicPlugin>(sofile);
                     MaCh3ArgumentParser* parser = dlplugin->get_parser();
                     if (!parser) {
                         std::cerr << "Plugin " << sofile << " did not provide a valid parser.\n";
                         continue;
                     }
  
                     this->add_subparser(*parser);
                     m_dynamic_plugin_map[parser] = std::move(dlplugin);
                     m_subcommands.push_back(parser->name());
                 }
                 catch (const std::exception& e) {
                     std::cerr << "Failed to load plugin from " << sofile << ": " << e.what() << "\n";
                     continue;
                 }
                 catch (...) {
                     std::cerr << "Failed to load plugin from " << sofile << ": unknown error\n";
                     continue;
                 }
             }
         }
     }

◆ Run()

int M3::MaCh3Program::Run ( )

Run the selected subcommand.

Execute the selected subcommand.

Returns: Exit code from the executed module

Determines which subcommand was invoked and runs the corresponding module or plugin.

Returns: Exit code from the executed module (0 on success)

Definition at line 231 of file MaCh3Program.cpp.

                          {
         const MaCh3ArgumentParser& sub_parser = this->get_subcommand_used();
         
         if (sub_parser){
             auto plugin_itr = m_module_map.find(&sub_parser);
             if (plugin_itr != m_module_map.end()){
                 return plugin_itr->second->Run();
             }
             auto dplugin_itr = m_dynamic_plugin_map.find(&sub_parser);
             if (dplugin_itr != m_dynamic_plugin_map.end()){
                 return dplugin_itr->second->Run();
             }
         }
         return 0;        
     }

◆ unload_dynamic_plugins()

void M3::MaCh3Program::unload_dynamic_plugins ( )

Unload all dynamically loaded plugins.

Unload all dynamic plugins and clean up resources.

Clears the plugin map. Smart pointers automatically handle cleanup.

Definition at line 222 of file MaCh3Program.cpp.

                                              {
         m_dynamic_plugin_map.clear();
     }

◆ write_file()

bool M3::MaCh3Program::write_file	(	const fs::path &	path,
		std::string_view	content
	)		const

private

Write content to a file, creating parent directories if needed.

Parameters

path	Filesystem path to write to
content	Content to write to the file

Returns: true if successful, false otherwise

Definition at line 16 of file MaCh3Program.cpp.

                                                                                  {
         try {
             fs::create_directories(path.parent_path());
             std::ofstream out(path);
             if (!out) return false;
             out << content;
             return true;
         } catch (...) {
             return false;
         }
     }

Member Data Documentation

◆ BASH_COMPLETION

constexpr std::string_view M3::MaCh3Program::BASH_COMPLETION

staticconstexprprivate

Initial value:

= R"(
_mach3_complete() {
    local cur prev words cword
    _init_completion || return
 
    # Pass current prefix + preceding words as context; binary filters by prefix
    local -a raw
    mapfile -t raw < <(mach3 --complete "$cur" "${words[@]:1:$((cword-1))}" 2>/dev/null)
 
    if [[ ${#raw[@]} -eq 0 ]]; then
        # No completions from binary — fall back to default (file) completion
        compopt -o default 2>/dev/null
        return
    fi
    COMPREPLY=( "${raw[@]}" )
}
complete -F _mach3_complete mach3
)"

Definition at line 78 of file MaCh3Program.hpp.

◆ m_dynamic_plugin_map

std::map<const MaCh3ArgumentParser*, std::unique_ptr<DynamicPlugin> > M3::MaCh3Program::m_dynamic_plugin_map

private

Map of parsers to dynamic plugins (owning)

Definition at line 76 of file MaCh3Program.hpp.

◆ m_module_map

std::map<const MaCh3ArgumentParser*, IModule*> M3::MaCh3Program::m_module_map

private

Map of parsers to core modules (non-owning)

Definition at line 75 of file MaCh3Program.hpp.

◆ m_subcommands

std::vector<std::string> M3::MaCh3Program::m_subcommands

private

List of registered subcommand names.

Definition at line 74 of file MaCh3Program.hpp.

◆ ZSH_COMPLETION

constexpr std::string_view M3::MaCh3Program::ZSH_COMPLETION

staticconstexprprivate

Initial value:

= R"(
#compdef mach3
 
_mach3() {
    local cur="${words[$CURRENT]}"
    local -a ctx
    ctx=("${words[@]:1:$((CURRENT-2))}")
 
    local -a completions
    completions=("${(@f)$(mach3 --complete "$cur" "${ctx[@]}" 2>/dev/null)}")
 
    if [[ ${#completions[@]} -eq 0 ]]; then
        _files
        return
    fi
    compadd -a completions
}
 
_mach3
)"

Definition at line 96 of file MaCh3Program.hpp.

The documentation for this class was generated from the following files:

CLI/MaCh3Program.hpp
CLI/MaCh3Program.cpp

Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~MaCh3Program()

Member Function Documentation

◆ add_core_module()

◆ completions()

◆ detect_shell()

◆ expand_plugin_path()

◆ install_completions()

◆ load_dynamic_plugins()

◆ Run()

◆ unload_dynamic_plugins()

◆ write_file()

Member Data Documentation

◆ BASH_COMPLETION

◆ m_dynamic_plugin_map

◆ m_module_map

◆ m_subcommands

◆ ZSH_COMPLETION