From 0bbbacf161aa0f4bd4869d108f56d85f9c5ec8e6 Mon Sep 17 00:00:00 2001
From: myk002 <myk002@yahoo.com>
Date: Tue, 2 Aug 2022 18:40:50 -0700
Subject: [PATCH] extend the docs and examples in skeleton.cpp

---
 plugins/examples/skeleton.cpp | 221 +++++++++++++++++++++-------------
 1 file changed, 134 insertions(+), 87 deletions(-)

diff --git a/plugins/examples/skeleton.cpp b/plugins/examples/skeleton.cpp
index 7d5936f6d..e1f552d31 100644
--- a/plugins/examples/skeleton.cpp
+++ b/plugins/examples/skeleton.cpp
@@ -1,65 +1,71 @@
-// This is a generic plugin that does nothing useful apart from acting as an example... of a plugin that does nothing :D
+// This is an example plugin that just documents and implements all the plugin
+// callbacks and features. You can compile it, load it, run it, and see the
+// debug messages get printed to the console.
+//
+// See the other example plugins in this directory for plugins that are
+// configured for specific use cases (but don't come with as many comments as
+// this one does).
+
+#include <string>
+#include <vector>
+
+#include "df/world.h"
 
-// some headers required for a plugin. Nothing special, just the basics.
 #include "Core.h"
-#include <Console.h>
-#include <Export.h>
-#include <PluginManager.h>
-#include <modules/EventManager.h>
-// If you need to save data per-world:
-//#include "modules/Persistence.h"
+#include "Debug.h"
+#include "LuaTools.h"
+#include "PluginManager.h"
 
-// DF data structure definition headers
-#include "DataDefs.h"
-//#include "df/world.h"
+#include "modules/Persistence.h"
+#include "modules/World.h"
 
-// our own, empty header.
-#include "skeleton.h"
+using std::string;
+using std::vector;
 
 using namespace DFHack;
-using namespace df::enums;
 
-// Expose the plugin name to the DFHack core, as well as metadata like the DFHack version.
-// The name string provided must correspond to the filename -
+// Expose the plugin name to the DFHack core, as well as metadata like the
+// DFHack version that this plugin was compiled with. This macro provides a
+// variable for the plugin name as const char * plugin_name.
+// The name provided must correspond to the filename --
 // skeleton.plug.so, skeleton.plug.dylib, or skeleton.plug.dll in this case
 DFHACK_PLUGIN("skeleton");
 
-// The identifier declared with this macro (ie. enabled) can be specified by the user
-// and subsequently used to manage the plugin's operations.
-// This will also be tracked by `plug`; when true the plugin will be shown as enabled.
-DFHACK_PLUGIN_IS_ENABLED(enabled);
+// The identifier declared with this macro (i.e. is_enabled) is used to track
+// whether the plugin is in an "enabled" state. If you don't need enablement
+// for your plugin, you don't need this line. This variable will also be read
+// by the `plug` builtin command; when true the plugin will be shown as enabled.
+DFHACK_PLUGIN_IS_ENABLED(is_enabled);
 
 // Any globals a plugin requires (e.g. world) should be listed here.
 // For example, this line expands to "using df::global::world" and prevents the
-// plugin from being loaded if df::global::world is null (i.e. missing from symbols.xml):
-//
+// plugin from being loaded if df::global::world is null (i.e. missing from
+// symbols.xml).
 REQUIRE_GLOBAL(world);
 
-// You may want some compile time debugging options
-// one easy system just requires you to cache the color_ostream &out into a global debug variable
-//#define P_DEBUG 1
-//uint16_t maxTickFreq = 1200; //maybe you want to use some events
+// logging levels can be dynamically controlled with the `debugfilter` command.
+namespace DFHack {
+    // for configuration-related logging
+    DBG_DECLARE(skeleton, status, DebugCategory::LINFO);
+    // for logging during the periodic scan
+    DBG_DECLARE(skeleton, cycle, DebugCategory::LINFO);
+}
 
-command_result command_callback1(color_ostream &out, std::vector<std::string> &parameters);
+command_result command_callback1(color_ostream &out, vector<string> &parameters);
 
+// run when the plugin is loaded
 DFhackCExport command_result plugin_init(color_ostream &out, std::vector<PluginCommand> &commands) {
-    commands.push_back(PluginCommand("skeleton",
-                                     "~54 character description of plugin", //to use one line in the ``[DFHack]# ls`` output
-                                     command_callback1,
-                                     false,
-                                     "example usage"
-                                     " skeleton <option> <args>\n"
-                                     "    explanation of plugin/command\n"
-                                     "\n"
-                                     " skeleton\n"
-                                     "    what happens when using the command\n"
-                                     "\n"
-                                     " skeleton option1\n"
-                                     "    what happens when using the command with option1\n"
-                                     "\n"));
+    // For in-tree plugins, don't use the "usage" parameter of PluginCommand.
+    // Instead, add an .rst file with the same name as the plugin to the
+    // docs/plugins/ directory.
+    commands.push_back(PluginCommand(
+        "skeleton",
+        "Short (~54 character) description of command.", // to use one line in the ``[DFHack]# ls`` output
+        command_callback1));
     return CR_OK;
 }
 
+// run when the plugin is unloaded
 DFhackCExport command_result plugin_shutdown(color_ostream &out) {
     // You *MUST* kill all threads you created before this returns.
     // If everything fails, just return CR_FAILURE. Your plugin will be
@@ -68,28 +74,20 @@ DFhackCExport command_result plugin_shutdown(color_ostream &out) {
 
 }
 
+// run when the `enable` or `disable` command is run with this plugin name as
+// an argument
 DFhackCExport command_result plugin_enable(color_ostream &out, bool enable) {
-    namespace EM = EventManager;
-    if (enable && !enabled) {
-        //using namespace EM::EventType;
-        //EM::EventHandler eventHandler(onNewEvent, maxTickFreq);
-        //EM::registerListener(EventType::JOB_COMPLETED, eventHandler, plugin_self);
-        //out.print("plugin enabled!\n");
-    } else if (!enable && enabled) {
-        EM::unregisterAll(plugin_self);
-        //out.print("plugin disabled!\n");
-    }
-    enabled = enable;
+    // you have to maintain the state of the is_enabled variable yourself. it
+    // doesn't happen automatically.
+    is_enabled = enable;
     return CR_OK;
 }
 
-
-/* OPTIONAL *
 // Called to notify the plugin about important state changes.
 // Invoked with DF suspended, and always before the matching plugin_onupdate.
 // More event codes may be added in the future.
 DFhackCExport command_result plugin_onstatechange(color_ostream &out, state_change_event event) {
-    if (enabled) {
+    if (is_enabled) {
         switch (event) {
             case SC_UNKNOWN:
                 break;
@@ -116,9 +114,8 @@ DFhackCExport command_result plugin_onstatechange(color_ostream &out, state_chan
     return CR_OK;
 }
 
-// Whatever you put here will be done in each game step. Don't abuse it.
-DFhackCExport command_result plugin_onupdate ( color_ostream &out )
-{
+// Whatever you put here will be done in each game frame refresh. Don't abuse it.
+DFhackCExport command_result plugin_onupdate (color_ostream &out) {
     // whetever. You don't need to suspend DF execution here.
     return CR_OK;
 }
@@ -128,44 +125,94 @@ DFhackCExport command_result plugin_onupdate ( color_ostream &out )
 // and plugin_load_data is called whenever a new world is loaded. If the plugin
 // is loaded or unloaded while a world is active, plugin_save_data or
 // plugin_load_data will be called immediately.
-DFhackCExport command_result plugin_save_data (color_ostream &out)
-{
+DFhackCExport command_result plugin_save_data (color_ostream &out) {
     // Call functions in the Persistence module here.
     return CR_OK;
 }
 
-DFhackCExport command_result plugin_load_data (color_ostream &out)
-{
+DFhackCExport command_result plugin_load_data (color_ostream &out) {
     // Call functions in the Persistence module here.
     return CR_OK;
 }
-* OPTIONAL */
-
-
-// A command! It sits around and looks pretty. And it's nice and friendly.
-command_result command_callback1(color_ostream &out, std::vector<std::string> &parameters) {
-    // It's nice to print a help message you get invalid options
-    // from the user instead of just acting strange.
-    // This can be achieved by adding the extended help string to the
-    // PluginCommand registration as show above, and then returning
-    // CR_WRONG_USAGE from the function. The same string will also
-    // be used by 'help your-command'.
-    if (!parameters.empty()) {
-        return CR_WRONG_USAGE; //or maybe you want it to do something else
+
+// define the structure that will represent the possible commandline options
+struct command_options {
+    // whether to display help
+    bool help = false;
+
+    // whether to run a cycle right now
+    bool now = false;
+
+    // how many ticks to wait between cycles when enabled, -1 means unset
+    int32_t ticks = -1;
+
+    // example params of different types
+    df::coord start;
+    string format;
+    vector<string*> list; // note this must be a vector of pointers, not objects
+
+    static struct_identity _identity;
+};
+static const struct_field_info command_options_fields[] = {
+    { struct_field_info::PRIMITIVE,      "help",   offsetof(command_options, help),  &df::identity_traits<bool>::identity,    0, 0 },
+    { struct_field_info::PRIMITIVE,      "now",    offsetof(command_options, now),   &df::identity_traits<bool>::identity,    0, 0 },
+    { struct_field_info::PRIMITIVE,      "ticks",  offsetof(command_options, ticks), &df::identity_traits<int32_t>::identity, 0, 0 },
+    { struct_field_info::SUBSTRUCT,      "start",  offsetof(command_options, start), &df::coord::_identity,                   0, 0 },
+    { struct_field_info::PRIMITIVE,      "format", offsetof(command_options, format), df::identity_traits<string>::get(),     0, 0 },
+    { struct_field_info::STL_VECTOR_PTR, "list",   offsetof(command_options, list),   df::identity_traits<string>::get(),     0, 0 },
+    { struct_field_info::END }
+};
+struct_identity command_options::_identity(sizeof(command_options), &df::allocator_fn<command_options>, NULL, "command_options", NULL, command_options_fields);
+
+// load the lua module associated with the plugin and parse the commandline
+// in lua (which has better facilities than C++ for string parsing). You should
+// create a file named after your plugin in the plugins/lua directory. This
+// example expects you to define a global function in that file named
+// "parse_commandline" that takes the options struct defined above along with
+// the commandline parameters. It should parse the parameters and set data in
+// the options structure. See plugins/lua/skeleton.lua for an example.
+static bool get_options(color_ostream &out,
+                        command_options &opts,
+                        const vector<string> &parameters)
+{
+    auto L = Lua::Core::State;
+    Lua::StackUnwinder top(L);
+
+    if (!lua_checkstack(L, parameters.size() + 2) ||
+        !Lua::PushModulePublic(
+            out, L, ("plugins." + string(plugin_name)).c_str(),
+            "parse_commandline")) {
+        out.printerr("Failed to load %s Lua code\n", plugin_name);
+        return false;
     }
-    // Commands are called from threads other than the DF one.
-    // Suspend this thread until DF has time for us.
-    // **If you use CoreSuspender** it'll automatically resume DF when
-    // execution leaves the current scope.
+
+    Lua::Push(L, &opts);
+    for (const string &param : parameters)
+        Lua::Push(L, param);
+
+    if (!Lua::SafeCall(out, L, parameters.size() + 1, 0))
+        return false;
+
+    return true;
+}
+
+// This is the callback we registered in plugin_init. Note that while plugin
+// callbacks are called with the core suspended, command callbacks are called
+// from a different thread and need to explicity suspend the core if they
+// interact with Lua or DF game state (most commands do at least one of these).
+static command_result command_callback1(color_ostream &out, vector<string> &parameters) {
+    // I'll say it again: always suspend the core in command callbacks unless
+    // all your data is local.
     CoreSuspender suspend;
-    // Actually do something here. Yay.
 
-    // process parameters
-    if (parameters.size() == 1 && parameters[0] == "option1") {
-        // stuff
-    } else {
-        return CR_FAILURE;
-    }
-    // Give control back to DF.
+    // Return CR_WRONG_USAGE to print out your help text. The help text is
+    // sourced from the associated rst file in docs/plugins/. The same help will
+    // also be returned by 'help your-command'.
+    command_options opts;
+    if (!get_options(out, opts, parameters) || opts.help)
+        return CR_WRONG_USAGE;
+
+    // TODO: do something according to the flags set in the options struct
+
     return CR_OK;
 }