From 992a63467b06e9ffcbaf1bfadfdc843f40c7f704 Mon Sep 17 00:00:00 2001
From: ModulatingForce <116608425+modulatingforce@users.noreply.github.com>
Date: Fri, 22 Dec 2023 12:03:26 -0500
Subject: [PATCH] Added HOWTO Add Modules and BotActions

---
 src/help/HOWTO/Add_Modules_BotActions.md | 97 ++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 src/help/HOWTO/Add_Modules_BotActions.md

diff --git a/src/help/HOWTO/Add_Modules_BotActions.md b/src/help/HOWTO/Add_Modules_BotActions.md
new file mode 100644
index 0000000..6b6474c
--- /dev/null
+++ b/src/help/HOWTO/Add_Modules_BotActions.md
@@ -0,0 +1,97 @@
+
+# How to : Add Modules & BotActions
+
+`BotModule` s are containers of `BotAction` s grouped together to provide certain Bot Features or Functionality
+
+## To Add a New Module & BotAction
+
+The developer must have the following done first to setup the Bot Module Code before coding their Custom Module Code
+
+1. In `src/modules.rs` : 
+
+    a. add in the module : e.g., `mod experiments;`
+
+    b. In the `pub fn init(mgr:&mut ModulesManager)` defintion, call an *init()* from the module, passing a `ModulesManager` : e.g., `experiments::init(mgr);`
+
+Example `src/modules.rs`
+```rust
+/*
+    `modules` will :
+    - be a starting refrence point for the bot instance to pull module definitions for
+
+*/
+
+pub use crate::core::botmodules::ModulesManager;
+
+pub use crate::core::botinstance::BotInstance;
+
+
+// [ ] Load submodules
+
+mod experiments;
+
+
+// [ ] init() function that accepts bot instance - this is passed to init() on submodules
+
+pub fn init(mgr:&mut ModulesManager) -> () {
+    // Modules initializer loads modules into the bot
+    // this is achieved by calling submodules that also have fn init() defined
+
+    experiments::init(mgr);
+    
+
+    ();
+}
+```
+
+2. In the directory modules, define a New file based on the module name : e.g., `modules/experiments.rs`
+
+4. Within the New Modules File (e.g, `modules/experiments.rs`) , define the following template
+
+```rust
+/*
+
+    #todo - [ ] Need to add perhaps a consant for the modules name for ease - and add that to the guide
+
+    Submodules -
+
+    - should have definitions of BotAction that will be added to a bit
+        - therefore, will be defined in modules.rs file  
+    - will define one init(&BotInstance) take within the module that will contain :
+        - BotAction definitions that each call &BotInstance module manager to add itself
+
+*/
+
+// mod crate::modules;
+//use crate::modules;
+
+use crate::core::botmodules::{ModulesManager,BotCommand,BotModule};
+
+pub fn init(mgr:&mut ModulesManager) -> () {
+
+    // // Example Working BotCommand Add
+    // BotCommand {
+    //     module : BotModule(String::from("experiments 004")),
+    //     command : String::from("DUPCMD4"), // command call name
+    //     alias : vec![String::from("DUPALIAS4A"),String::from("DUPALIAS4B")], // String of alternative names
+    //     // bot_prefix : char, // although should be global?
+    //     // exec_body : fn,
+    //     help : String::from("DUPCMD4 tester"),
+    // }.add_to_modmgr(mgr);
+
+
+
+    println!("At Experiments module");
+
+
+    ();
+}
+```
+
+5. Within the `init()` function definition, 
+
+    a. Define `BotCommand` , `Listener` , `Routine` (or other `BotAction`) ,
+
+    b. Each definition calls `.add_to_modmgr(mgr)` where `mgr` is `ModulesManager`
+
+4. **(FUTURE RELEASE)** the developer can define execution bodies within the module that would be called for that BotAction . For example, listeners are ran in response to a PRVTMSG . 
\ No newline at end of file