feat(lib): public API for generator registration

alandefreitas · alandefreitas · commit 8da09e3094c6 · 2025-12-22T22:07:41.000-05:00
closes #313
diff --git a/include/mrdocs/Generator.hpp b/include/mrdocs/Generator.hpp
@@ -5,6 +5,7 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 // Copyright (c) 2023 Vinnie Falco (vinnie.falco@gmail.com)
+// Copyright (c) 2023 Alan de Freitas (alandefreitas@gmail.com)
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
@@ -19,6 +20,7 @@
 #include <mrdocs/Config.hpp>
 #include <mrdocs/Corpus.hpp>
 #include <mrdocs/Support/Error.hpp>
+#include <memory>
 #include <ostream>
 #include <string>
 #include <string_view>
@@ -201,11 +203,50 @@ class MRDOCS_VISIBLE
     @param outputPath The specified output path, which can be a directory or file.
     @param extension The file extension to use for single-page output.
 */
+MRDOCS_DECL
 Expected<std::string>
 getSinglePageFullPath(
     std::string_view outputPath,
     std::string_view extension);
 
+/** Install a custom generator.
+
+    This function registers a generator with the global
+    generator registry, making it available for use.
+
+    Plugins can use this function to register custom
+    generators.
+
+    @par Thread Safety
+    This function is thread-safe and may be called
+    concurrently from multiple threads.
+
+    @return An error if a generator with the same id
+    already exists.
+
+    @param G The generator to install. Ownership is
+    transferred to the registry.
+*/
+MRDOCS_DECL
+Expected<void>
+installGenerator(std::unique_ptr<Generator> G);
+
+/** Find a generator by its id.
+
+    @par Thread Safety
+    This function is thread-safe and may be called
+    concurrently from multiple threads.
+
+    @return A pointer to the generator, or `nullptr`
+    if no generator with the given id exists.
+
+    @param id The symbolic name of the generator.
+    The name must be an exact match, including case.
+*/
+MRDOCS_DECL
+Generator const*
+findGenerator(std::string_view id) noexcept;
+
 } // mrdocs
 
 
diff --git a/src/lib/Support/Generator.cpp b/src/lib/Support/Generator.cpp
@@ -5,12 +5,14 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 // Copyright (c) 2023 Vinnie Falco (vinnie.falco@gmail.com)
+// Copyright (c) 2023 Alan de Freitas (alandefreitas@gmail.com)
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
 
 #include <lib/AST/ExtractDocComment.hpp>
 #include <lib/Support/Chrono.hpp>
+#include <lib/Support/GeneratorRegistryImpl.hpp>
 #include <lib/Support/Path.hpp>
 #include <mrdocs/Generator.hpp>
 #include <mrdocs/Support/Error.hpp>
@@ -156,5 +158,17 @@ getSinglePageFullPath(
     return fileName.str().str();
 }
 
+Expected<void>
+installGenerator(std::unique_ptr<Generator> G)
+{
+    return getGeneratorRegistryImpl().insert(std::move(G));
+}
+
+Generator const*
+findGenerator(std::string_view id) noexcept
+{
+    return getGeneratorRegistryImpl().find(id);
+}
+
 } // mrdocs
 
diff --git a/src/lib/Support/GeneratorRegistry.hpp b/src/lib/Support/GeneratorRegistry.hpp
@@ -4,12 +4,13 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 // Copyright (c) 2023 Vinnie Falco (vinnie.falco@gmail.com)
+// Copyright (c) 2023 Alan de Freitas (alandefreitas@gmail.com)
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
 
-#ifndef MRDOCS_API_GENERATORS_HPP
-#define MRDOCS_API_GENERATORS_HPP
+#ifndef MRDOCS_LIB_SUPPORT_GENERATORREGISTRY_HPP
+#define MRDOCS_LIB_SUPPORT_GENERATORREGISTRY_HPP
 
 #include <mrdocs/Platform.hpp>
 #include <mrdocs/Generator.hpp>
@@ -22,11 +23,11 @@ namespace mrdocs {
 /** A dynamic list of @ref Generator elements.
 */
 class MRDOCS_VISIBLE
-    Generators
+    GeneratorRegistry
 {
 protected:
     /// Construct an empty generator registry; only derived singletons create this.
-    Generators() noexcept = default;
+    GeneratorRegistry() noexcept = default;
 
 public:
     /// Pointer type for generator entries.
@@ -48,7 +49,7 @@ class MRDOCS_VISIBLE
     */
     MRDOCS_DECL
     virtual
-    ~Generators() noexcept;
+    ~GeneratorRegistry() noexcept;
 
     /** Return an iterator to the beginning.
     */
@@ -78,13 +79,7 @@ class MRDOCS_VISIBLE
         std::string_view name) const noexcept = 0;
 };
 
-/** Return a reference to the global Generators instance.
-*/
-MRDOCS_DECL
-Generators const&
-getGenerators() noexcept;
-
 } // mrdocs
 
 
-#endif // MRDOCS_API_GENERATORS_HPP
+#endif // MRDOCS_LIB_SUPPORT_GENERATORREGISTRY_HPP
diff --git a/src/lib/Support/GeneratorRegistryImpl.cpp b/src/lib/Support/GeneratorRegistryImpl.cpp
@@ -4,11 +4,12 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 // Copyright (c) 2023 Vinnie Falco (vinnie.falco@gmail.com)
+// Copyright (c) 2023 Alan de Freitas (alandefreitas@gmail.com)
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
 
-#include "GeneratorsImpl.hpp"
+#include "GeneratorRegistryImpl.hpp"
 #include <mrdocs/Support/Report.hpp>
 #include <llvm/ADT/STLExtras.h>
 
@@ -27,11 +28,11 @@ extern
 std::unique_ptr<Generator>
 makeHTMLGenerator();
 
-Generators::
-~Generators() noexcept = default;
+GeneratorRegistry::
+~GeneratorRegistry() noexcept = default;
 
 void
-GeneratorsImpl::
+GeneratorRegistryImpl::
 refresh_plist()
 {
     plist_.clear();
@@ -40,19 +41,20 @@ refresh_plist()
         plist_.push_back(g.get());
 }
 
-GeneratorsImpl::
-GeneratorsImpl()
+GeneratorRegistryImpl::
+GeneratorRegistryImpl()
 {
     insert(makeAdocGenerator());
     insert(makeXMLGenerator());
     insert(makeHTMLGenerator());
 }
 
 Generator const*
-GeneratorsImpl::
+GeneratorRegistryImpl::
 find(
     std::string_view id) const noexcept
 {
+    std::lock_guard<std::mutex> lock(mutex_);
     for (auto const& li : list_)
     {
         if(li->id() == id)
@@ -64,30 +66,34 @@ find(
 }
 
 Expected<void>
-GeneratorsImpl::
+GeneratorRegistryImpl::
 insert(
     std::unique_ptr<Generator> G)
 {
-    MRDOCS_CHECK(find(G->id()) == nullptr, formatError("generator id=\"{}\" already exists", G->id()));
+    if (!G)
+    {
+        return Unexpected(formatError("cannot install null generator"));
+    }
+    std::lock_guard<std::mutex> lock(mutex_);
+    for (auto const& li : list_)
+    {
+        if (li->id() == G->id())
+        {
+            return Unexpected(formatError("generator id=\"{}\" already exists", G->id()));
+        }
+    }
     list_.emplace_back(std::move(G));
     refresh_plist();
     return {};
 }
 
 //------------------------------------------------
 
-GeneratorsImpl&
-getGeneratorsImpl() noexcept
+GeneratorRegistryImpl&
+getGeneratorRegistryImpl() noexcept
 {
-    static GeneratorsImpl impl;
+    static GeneratorRegistryImpl impl;
     return impl;
 }
 
-Generators const&
-getGenerators() noexcept
-{
-    return getGeneratorsImpl();
-}
-
 } // mrdocs
-
diff --git a/src/lib/Support/GeneratorRegistryImpl.hpp b/src/lib/Support/GeneratorRegistryImpl.hpp
@@ -4,36 +4,39 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 // Copyright (c) 2023 Vinnie Falco (vinnie.falco@gmail.com)
+// Copyright (c) 2023 Alan de Freitas (alandefreitas@gmail.com)
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
 
-#ifndef MRDOCS_LIB_SUPPORT_GENERATORSIMPL_HPP
-#define MRDOCS_LIB_SUPPORT_GENERATORSIMPL_HPP
+#ifndef MRDOCS_LIB_SUPPORT_GENERATORREGISTRYIMPL_HPP
+#define MRDOCS_LIB_SUPPORT_GENERATORREGISTRYIMPL_HPP
 
 #include <mrdocs/Platform.hpp>
-#include <mrdocs/Generators.hpp>
+#include <lib/Support/GeneratorRegistry.hpp>
 #include <mrdocs/Support/Error.hpp>
 #include <llvm/ADT/SmallVector.h>
 #include <memory>
+#include <mutex>
 #include <vector>
 
 
 namespace mrdocs {
 
-/** Implementaiton of Generators.
+/** Implementation of GeneratorRegistry.
 */
 class MRDOCS_VISIBLE
-    GeneratorsImpl : public Generators
+    GeneratorRegistryImpl : public GeneratorRegistry
 {
+    mutable std::mutex mutex_;
     llvm::SmallVector<Generator const*, 3> plist_;
     llvm::SmallVector<
         std::unique_ptr<Generator>> list_;
 
     void refresh_plist();
 
 public:
-    GeneratorsImpl();
+    GeneratorRegistryImpl();
 
     iterator
     begin() const noexcept override
@@ -57,10 +60,10 @@ class MRDOCS_VISIBLE
     insert(std::unique_ptr<Generator> G);
 };
 
-/** Return a reference to the global GeneratorsImpl instance.
+/** Return a reference to the global GeneratorRegistryImpl instance.
 */
-GeneratorsImpl&
-getGeneratorsImpl() noexcept;
+GeneratorRegistryImpl&
+getGeneratorRegistryImpl() noexcept;
 
 } // mrdocs
 
diff --git a/src/test/TestRunner.cpp b/src/test/TestRunner.cpp
@@ -23,7 +23,7 @@
 #include <lib/Support/Path.hpp>
 #include <lib/Support/Report.hpp>
 #include <mrdocs/Config.hpp>
-#include <mrdocs/Generators.hpp>
+#include <mrdocs/Generator.hpp>
 #include <mrdocs/Support/Error.hpp>
 #include <test_suite/diff.hpp>
 #include <llvm/Support/CommandLine.h>
@@ -37,7 +37,7 @@ namespace mrdocs {
 
 TestRunner::
 TestRunner(std::string_view generator)
-    : gen_(getGenerators().find(generator))
+    : gen_(findGenerator(generator))
 {
     MRDOCS_ASSERT(gen_ != nullptr);
 }
diff --git a/src/test/lib/Support/Generator.cpp b/src/test/lib/Support/Generator.cpp
diff --git a/src/tool/GenerateAction.cpp b/src/tool/GenerateAction.cpp
