Modules descriptor objects (#66)

.github/workflows/build.yml

@@ -46,7 +46,7 @@ jobs:
     - name: 'Build environment'
       run: |
         cmake --build ${{ env.CEPGEN_PATH }}
-        cmake --build ${{ env.CEPGEN_PATH }} -- cepgenDocGenerator
+        cmake --build ${{ env.CEPGEN_PATH }} -- cepgenDescribeModules
     - name: 'Compress environment'
       run: tar -cvf environment.tar /Package
 

CepGen/Generator.h

@@ -41,7 +41,6 @@ namespace cepgen {
   /// \param[in] safe_mode Drop libraries initialisation?
   void initialise(bool safe_mode = false);
   void printHeader();  ///< Dump this program's header into the standard output stream
-  void dumpModules();  ///< List the modules registered in RTE database
 
   /// Core generator object allowing for process definition, cross section computation, and event generation
   /// \author Laurent Forthomme <laurent.forthomme@cern.ch>

CepGen/Modules/DocumentationGeneratorFactory.h

@@ -0,0 +1,45 @@
+/*
+ *  CepGen: a central exclusive processes event generator
+ *  Copyright (C) 2024  Laurent Forthomme
+ *
+ *  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
+ *  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 <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef CepGen_Modules_DocumentationGeneratorFactory_h
+#define CepGen_Modules_DocumentationGeneratorFactory_h
+
+#include "CepGen/Modules/ModuleFactory.h"
+
+/// Add a documentation generator to the list of handled modules
+#define REGISTER_DOCUMENTATION_GENERATOR(name, obj)                                        \
+  namespace cepgen {                                                                       \
+    struct BUILDERNM(obj) {                                                                \
+      BUILDERNM(obj)() { DocumentationGeneratorFactory::get().registerModule<obj>(name); } \
+    };                                                                                     \
+    static const BUILDERNM(obj) gDogGen##obj;                                              \
+  }                                                                                        \
+  static_assert(true, "")
+
+namespace cepgen {
+  namespace utils {
+    class DocumentationGenerator;
+  }
+  /// A documentation generator factory
+  DEFINE_FACTORY(std::string,
+                 DocumentationGeneratorFactory,
+                 utils::DocumentationGenerator,
+                 "Documentation generator factory");
+}  // namespace cepgen
+
+#endif

CepGen/Modules/ModuleFactoryImpl.h

@@ -33,6 +33,7 @@
 #include "CepGen/StructureFunctions/Parameterisation.h"
 #include "CepGen/StructureFunctions/SigmaRatio.h"
 #include "CepGen/Utils/Derivator.h"
+#include "CepGen/Utils/DocumentationGenerator.h"
 #include "CepGen/Utils/Drawer.h"
 #include "CepGen/Utils/Functional.h"
 #include "CepGen/Utils/RandomGenerator.h"
@@ -42,6 +43,7 @@ namespace cepgen {
   template class ModuleFactory<CollinearFlux, std::string>;
   template class ModuleFactory<Coupling, std::string>;
   template class ModuleFactory<utils::Derivator, std::string>;
+  template class ModuleFactory<utils::DocumentationGenerator, std::string>;
   template class ModuleFactory<utils::Drawer, std::string>;
   template class ModuleFactory<EventImporter, std::string>;
   template class ModuleFactory<EventModifier, std::string>;

CepGen/Utils/DocumentationGenerator.cpp

@@ -0,0 +1,89 @@
+/*
+ *  CepGen: a central exclusive processes event generator
+ *  Copyright (C) 2024  Laurent Forthomme
+ *
+ *  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
+ *  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 <http://www.gnu.org/licenses/>.
+ */
+
+#include "CepGen/Utils/DocumentationGenerator.h"
+#include "CepGen/Utils/String.h"
+
+// list of factories documented
+#include "CepGen/Modules/CardsHandlerFactory.h"
+#include "CepGen/Modules/CouplingFactory.h"
+#include "CepGen/Modules/DrawerFactory.h"
+#include "CepGen/Modules/EventExporterFactory.h"
+#include "CepGen/Modules/EventImporterFactory.h"
+#include "CepGen/Modules/EventModifierFactory.h"
+#include "CepGen/Modules/FormFactorsFactory.h"
+#include "CepGen/Modules/FunctionalFactory.h"
+#include "CepGen/Modules/GeneratorWorkerFactory.h"
+#include "CepGen/Modules/IntegratorFactory.h"
+#include "CepGen/Modules/PartonFluxFactory.h"
+#include "CepGen/Modules/PhaseSpaceGeneratorFactory.h"
+#include "CepGen/Modules/ProcessFactory.h"
+#include "CepGen/Modules/RandomGeneratorFactory.h"
+#include "CepGen/Modules/StructureFunctionsFactory.h"
+
+namespace cepgen {
+  namespace utils {
+    DocumentationGenerator::DocumentationGenerator(const ParametersList& params) : NamedModule(params) {}
+
+    void DocumentationGenerator::initialise() {
+      const auto categories = steer<std::vector<std::string> >("categories"),
+                 mod_names = steer<std::vector<std::string> >("modules");
+      const auto add_category = [&categories, &mod_names, this](const std::string& name,
+                                                                const std::string& title,
+                                                                const std::string& description,
+                                                                auto& factory) -> void {
+        if (!categories.empty() && !contains(categories, name))
+          return;
+        category_t cat;
+        cat.name = name;
+        cat.title = title;
+        cat.description = description;
+        for (const auto& mod : factory.modules())
+          if (mod_names.empty() || contains(mod_names, utils::toString(mod)))
+            cat.modules[utils::toString(mod)] = factory.describeParameters(mod);
+        categories_.emplace_back(std::make_pair(name, cat));
+      };
+      add_category("proc", "Processes", "", cepgen::ProcessFactory::get());
+      add_category("cards", "Cards handler", "", cepgen::CardsHandlerFactory::get());
+      add_category("formfac", "Form factors", "", cepgen::FormFactorsFactory::get());
+      add_category("strfun", "Structure functions", "", cepgen::StructureFunctionsFactory::get());
+      add_category("sigrat",
+                   "Longitudinal/transverse cross section ratio parameterisations",
+                   "",
+                   cepgen::SigmaRatiosFactory::get());
+      add_category("psmap", "Phase space mapper", "", cepgen::PhaseSpaceGeneratorFactory::get());
+      add_category("collflux", "Collinear parton flux modelling", "", cepgen::CollinearFluxFactory::get());
+      add_category("ktflux", "KT-factorised parton flux modelling", "", cepgen::KTFluxFactory::get());
+      add_category("alphaem", "Electromagnetic coupling evolution", "", cepgen::AlphaEMFactory::get());
+      add_category("alphas", "Strong coupling evolution", "", cepgen::AlphaSFactory::get());
+      add_category("integr", "Integrator algorithms", "", cepgen::IntegratorFactory::get());
+      add_category("func", "Functional parsers", "", cepgen::FunctionalFactory::get());
+      add_category("rndgen", "Random number generators", "", cepgen::RandomGeneratorFactory::get());
+      add_category("drawer", "Drawing tools", "", cepgen::DrawerFactory::get());
+      add_category("evtgen", "Event generation algorithms", "", cepgen::GeneratorWorkerFactory::get());
+      add_category("evtimp", "Event import algorithms", "", cepgen::EventImporterFactory::get());
+      add_category("evtmod", "Event modification algorithms", "", cepgen::EventModifierFactory::get());
+      add_category("evtout", "Event export modules", "", cepgen::EventExporterFactory::get());
+    }
+
+    ParametersDescription DocumentationGenerator::description() {
+      auto desc = ParametersDescription();
+      return desc;
+    }
+  }  // namespace utils
+}  // namespace cepgen

CepGen/Utils/DocumentationGenerator.h

@@ -0,0 +1,49 @@
+/*
+ *  CepGen: a central exclusive processes event generator
+ *  Copyright (C) 2024  Laurent Forthomme
+ *
+ *  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
+ *  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 <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef CepGen_Utils_DocumentationGenerator_h
+#define CepGen_Utils_DocumentationGenerator_h
+
+#include "CepGen/Modules/ModuleFactory.h"
+
+namespace cepgen {
+  namespace utils {
+    /// Documentation generator object
+    /// \author Laurent Forthomme <laurent.forthomme@cern.ch>
+    /// \date Mar 2024
+    class DocumentationGenerator : public NamedModule<DocumentationGenerator, std::string> {
+    public:
+      explicit DocumentationGenerator(const ParametersList&);
+      virtual ~DocumentationGenerator() = default;
+
+      static ParametersDescription description();
+
+      virtual void initialise();
+      virtual std::string describe() = 0;
+
+    protected:
+      struct category_t {
+        std::string name, title, description;
+        std::map<std::string, ParametersDescription> modules{};
+      };
+      std::vector<std::pair<std::string, category_t> > categories_;
+    };
+  }  // namespace utils
+}  // namespace cepgen
+
+#endif

CepGen/Utils/TextDocumentationGenerator.cpp

@@ -0,0 +1,73 @@
+/*
+ *  CepGen: a central exclusive processes event generator
+ *  Copyright (C) 2021-2024  Laurent Forthomme
+ *
+ *  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
+ *  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 <http://www.gnu.org/licenses/>.
+ */
+
+#include "CepGen/Modules/DocumentationGeneratorFactory.h"
+#include "CepGen/Utils/DocumentationGenerator.h"
+#include "CepGen/Utils/String.h"
+
+namespace cepgen {
+  namespace utils {
+    /// Text documentation generator object
+    /// \author Laurent Forthomme <laurent.forthomme@cern.ch>
+    /// \date Nov 2021
+    class TextDocumentationGenerator final : public DocumentationGenerator {
+    public:
+      explicit TextDocumentationGenerator(const ParametersList& params)
+          : DocumentationGenerator(params), dump_params_(steer<bool>("dumpParameters")) {}
+
+      static ParametersDescription description() {
+        auto desc = DocumentationGenerator::description();
+        desc.setDescription("Bare text documentation generator");
+        desc.add<bool>("light", false).setDescription("lightweight module description (without parameters)");
+        desc.add<bool>("dumpParameters", false)
+            .setDescription("dump the parameters list along with their parameters description?");
+        return desc;
+      }
+
+      std::string describe() override {
+        std::ostringstream os;
+        const auto separator = std::string(80, '-');
+        const auto light = steer<bool>("light");
+        for (const auto& cat : categories_) {
+          if (cat.second.modules.empty())
+            continue;
+          os << colourise("\n" + separator + "\n" + cat.second.title, Colour::green, Modifier::bold);
+          if (!light)
+            os << "\n";
+          for (const auto& mod : cat.second.modules) {
+            if (light) {
+              os << "\n> " << colourise(mod.first, Colour::cyan, Modifier::underline | Modifier::bold) << ": "
+                 << mod.second.description() << (mod.second.empty() ? " (*)" : "");
+            } else {
+              os << "\n" << mod.second.describe();
+              if (dump_params_)
+                os << "\n\tParametersList object:\n\t\t" << mod.second.parameters();
+              os << "\n";
+            }
+          }
+        }
+        return os.str();
+      }
+
+    private:
+      const bool dump_params_;
+    };
+  }  // namespace utils
+}  // namespace cepgen
+using cepgen::utils::TextDocumentationGenerator;
+REGISTER_DOCUMENTATION_GENERATOR("text", TextDocumentationGenerator);

CepGenAddOns/CTMLWrapper/CMakeLists.txt

@@ -11,5 +11,4 @@ endif()
 
 cepgen_build(CepGenCTML SOURCES *.cpp
     EXT_HEADERS ${CTML_INCLUDE}
-    UTILS utils/*.cc
     INSTALL_COMPONENT doc)