standalone tagfile generation

#feat

Author: alandefreitas

src/lib/Gen/hbs/HandlebarsGenerator.cpp

@@ -28,10 +28,9 @@
 #include <fstream>
 #include <sstream>
 
-namespace clang {
-namespace mrdocs {
-namespace hbs {
+namespace clang::mrdocs::hbs {
 
+namespace {
 std::function<void(OutputRef&, std::string_view)>
 createEscapeFn(HandlebarsGenerator const& gen)
 {
@@ -65,15 +64,15 @@ createExecutors(
 HandlebarsCorpus
 createDomCorpus(
     HandlebarsGenerator const& gen,
-    Corpus const& corpus)
-{
+    Corpus const& corpus) {
     return {
         corpus,
         gen.fileExtension(),
         [&gen](HandlebarsCorpus const& c, doc::Node const& n) {
             return gen.toString(c, n);
         }};
 }
+} // (anon)
 
 //------------------------------------------------
 //
@@ -89,21 +88,10 @@ build(
 {
     if (!corpus.config->multipage)
     {
-        auto e = Generator::build(outputPath, corpus);
-        if (e.has_value() && !corpus.config->tagfile.empty())
-        {
-            // Generate tagfile if specified
-            auto const singlePagePath = getSinglePageFullPath(outputPath, fileExtension());
-            MRDOCS_CHECK_OR(singlePagePath, Unexpected(singlePagePath.error()));
-            HandlebarsCorpus hbsCorpus = createDomCorpus(*this, corpus);
-            MRDOCS_TRY(auto tagFileWriter, TagfileWriter::create(
-                    hbsCorpus,
-                    corpus.config->tagfile,
-                    files::getFileName(*singlePagePath)));
-            tagFileWriter.build();
-        }
-
-        return e;
+        MRDOCS_TRY(Generator::build(outputPath, corpus));
+        MRDOCS_CHECK_OR(!corpus.config->tagfile.empty(), {});
+        MRDOCS_TRY(buildTagfile(corpus.config->tagfile, corpus));
+        return {};
     }
 
     // Create corpus and executors
@@ -117,21 +105,74 @@ build(
     // Wait for all executors to finish and check errors
     auto errors = ex.wait();
     MRDOCS_CHECK_OR(errors.empty(), Unexpected(errors));
-
     report::info("Generated {} pages", visitor.count());
 
-    if (! corpus.config->tagfile.empty())
+    MRDOCS_CHECK_OR(!corpus.config->tagfile.empty(), {});
+    MRDOCS_TRY(buildTagfile(corpus.config->tagfile, corpus));
+    return {};
+}
+
+Expected<void>
+HandlebarsGenerator::
+buildTagfile(
+    std::ostream& os,
+    Corpus const& corpus) const
+{
+    HandlebarsCorpus domCorpus = createDomCorpus(*this, corpus);
+    RawOstream raw_os(os);
+    if (corpus.config->multipage)
     {
         MRDOCS_TRY(auto tagFileWriter, TagfileWriter::create(
-                domCorpus,
-                corpus.config->tagfile,
-                outputPath));
+                        domCorpus,
+                        raw_os));
+        tagFileWriter.build();
+    }
+    else
+    {
+        // Get the name of the single page output file
+        auto const singlePagePath = getSinglePageFullPath(corpus.config->output, fileExtension());
+        MRDOCS_CHECK_OR(singlePagePath, Unexpected(singlePagePath.error()));
+        auto const singlePathFilename = files::getFileName(*singlePagePath);
+        MRDOCS_TRY(auto tagFileWriter, TagfileWriter::create(
+                                domCorpus,
+                                raw_os,
+                                singlePathFilename));
         tagFileWriter.build();
     }
-
     return {};
 }
 
+Expected<void>
+HandlebarsGenerator::
+buildTagfile(
+    std::string_view const fileName,
+    Corpus const& corpus) const
+{
+    std::string const dir = files::getParentDir(fileName);
+    MRDOCS_TRY(files::createDirectory(dir));
+    std::ofstream os;
+    try
+    {
+        os.open(std::string(fileName),
+            std::ios_base::binary |
+                std::ios_base::out |
+                std::ios_base::trunc // | std::ios_base::noreplace
+            );
+    }
+    catch(std::exception const& ex)
+    {
+        return Unexpected(formatError("std::ofstream threw \"{}\"", ex.what()));
+    }
+    try
+    {
+        return buildTagfile(os, corpus);
+    }
+    catch(std::exception const& ex)
+    {
+        return Unexpected(formatError("buildOne threw \"{}\"", ex.what()));
+    }
+}
+
 Expected<void>
 HandlebarsGenerator::
 buildOne(
@@ -178,6 +219,4 @@ escape(OutputRef& out, std::string_view str) const
     out << str;
 }
 
-} // hbs
-} // mrdocs
-} // clang
+} // clang::mrdocs::hbs

src/lib/Gen/hbs/HandlebarsGenerator.hpp

@@ -67,6 +67,20 @@ class HandlebarsGenerator
         std::ostream& os,
         Corpus const& corpus) const override;
 
+    /** Build a tagfile for the corpus.
+     */
+    Expected<void>
+    buildTagfile(
+        std::ostream& os,
+        Corpus const& corpus) const;
+
+    /** Build a tagfile for the corpus and store the result in a file.
+     */
+    Expected<void>
+    buildTagfile(
+        std::string_view fileName,
+        Corpus const& corpus) const;
+
     /** Convert a Javadoc node to a string.
     */
     virtual
@@ -76,7 +90,7 @@ class HandlebarsGenerator
         return {};
     }
 
-    /** Output a escaped string to the output stream.
+    /** Output an escaped string to the output stream.
     */
     virtual
     void

src/lib/Lib/TagfileWriter.cpp

@@ -31,36 +31,23 @@ namespace mrdocs {
 TagfileWriter::
 TagfileWriter(
     hbs::HandlebarsCorpus const& corpus,
-    os_ptr os,
+    llvm::raw_ostream& os,
     std::string_view const defaultFilename
     ) noexcept
     : corpus_(corpus)
-    , os_(std::move(os))
-    , tags_(*os_)
+    , os_(os)
+    , tags_(os)
     , defaultFilename_(defaultFilename)
-{
-    tags_.nesting(false);
-}
+{}
 
 Expected<TagfileWriter>
 TagfileWriter::
 create(
     hbs::HandlebarsCorpus const& corpus,
-        std::string_view tagfile,
-        std::string_view defaultFilename)
+    llvm::raw_ostream& os,
+    std::string_view defaultFilename)
 {
-    std::error_code ec;
-
-    auto os = std::make_unique<llvm::raw_fd_ostream>(
-        tagfile.data(),
-        ec,
-        llvm::sys::fs::OF_None);
-
-    if (ec)
-    {
-        return Unexpected(formatError("llvm::raw_fd_ostream(\"{}\") failed with error: {}", tagfile, ec.message()));
-    }
-    return TagfileWriter(corpus, std::move(os), defaultFilename);
+    return TagfileWriter(corpus, os, defaultFilename);
 }
 
 void
@@ -76,15 +63,15 @@ void
 TagfileWriter::
 initialize()
 {
-    (*os_) << "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n";
-    (*os_) << "<tagfile>\n";
+    os_ << "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n";
+    os_ << "<tagfile>\n";
 }
 
 void
 TagfileWriter::
 finalize()
 {
-    (*os_) << "</tagfile>\n";
+    os_ << "</tagfile>\n";
 }
 
 

src/lib/Lib/TagfileWriter.hpp

@@ -34,13 +34,13 @@ class TagfileWriter
     using os_ptr = std::unique_ptr<llvm::raw_fd_ostream>;
 
     hbs::HandlebarsCorpus const& corpus_;
-    os_ptr os_;
+    llvm::raw_ostream& os_;
     xml::XMLTags tags_;
     std::string defaultFilename_;
 
     TagfileWriter(
         hbs::HandlebarsCorpus const& corpus,
-        os_ptr os,
+        llvm::raw_ostream& os,
         std::string_view defaultFilename) noexcept;
 
 public:
@@ -49,8 +49,13 @@ class TagfileWriter
         This static function creates a TagfileWriter instance using the provided
         HandlebarsCorpus, tagfile, and default filename.
 
+        This overload provides a default filename for symbols. This is useful
+        when generating a tagfile for single page output, as there's a single
+        page to reference before the anchors. All symbols are references to
+        the same file with different anchors.
+
         @param corpus The HandlebarsCorpus to use for the writer.
-        @param tagfile The name of the tagfile to write to.
+        @param os The output stream to write the tagfile to.
         @param defaultFilename The default filename to use for a symbol if none
         is provided. Typically, the relative path to a single page output file.
         This parameter is ignored in multipage mode.
@@ -60,9 +65,31 @@ class TagfileWriter
     Expected<TagfileWriter>
     create(
         hbs::HandlebarsCorpus const& corpus,
-        std::string_view tagfile,
+        llvm::raw_ostream& os,
         std::string_view defaultFilename);
 
+    /** Create a TagfileWriter instance without a reference to a default filename.
+
+        This static function creates a TagfileWriter instance using the provided
+        HandlebarsCorpus and tagfile.
+
+        This overload provides no default filename for symbols. This is useful
+        when generating a tagfile for multipage output, as there's no single
+        page to reference. All symbols are references to other files.
+
+        @param corpus The HandlebarsCorpus to use for the writer.
+        @param os The output stream to write the tagfile to.
+        @return An Expected object containing the TagfileWriter instance or an error.
+     */
+    static
+    Expected<TagfileWriter>
+    create(
+        hbs::HandlebarsCorpus const& corpus,
+        llvm::raw_ostream& os)
+    {
+        return create(corpus, os, {});
+    }
+
     /** Build the tagfile.
 
         This function builds the tagfile by initializing the output,