safe names and adoc pagination

vinniefalco · vinniefalco · commit 9dbb5054a1e7 · 2023-04-24T12:28:10.000-07:00
diff --git a/.gitignore b/.gitignore
@@ -6,5 +6,6 @@ bin64/
 build/
 temp/
 test/
+tests/py
 tests/**/*.adoc
 tests/**/*.bad.xml
diff --git a/include/mrdox/Config.hpp b/include/mrdox/Config.hpp
@@ -49,8 +49,9 @@ class MRDOX_VISIBLE
     Config& operator=(Config const&) = delete;
 
 protected:
-    std::string sourceRoot_;
     llvm::SmallString<0> configDir_;
+    llvm::SmallString<0> outputPath_;
+    std::string sourceRoot_;
     bool includePrivate_ = false;
     bool verbose_ = true;
 
@@ -74,7 +75,6 @@ class MRDOX_VISIBLE
     // VFALCO these naked data members are temporary...
     //
     tooling::ArgumentsAdjuster ArgAdjuster;
-    std::string OutDirectory;
     bool IgnoreMappingFailures = false;
 
     //--------------------------------------------
@@ -113,6 +113,14 @@ class MRDOX_VISIBLE
         return sourceRoot_;
     }
 
+    /** Return the output directory or filename.
+    */
+    llvm::StringRef
+    outputPath() const noexcept
+    {
+        return outputPath_;
+    }
+
     /** Return true if private members are documented.
     */
     bool
@@ -160,6 +168,14 @@ class MRDOX_VISIBLE
         includePrivate_ = includePrivate;
     }
 
+    /** Set the output directory or file path.
+    */
+    MRDOX_DECL
+    virtual
+    void
+    setOutputPath(
+        llvm::StringRef outputPath) = 0;
+
     /** Set the directory where the input files are stored.
 
         Symbol documentation will not be emitted unless
diff --git a/include/mrdox/Corpus.hpp b/include/mrdox/Corpus.hpp
@@ -103,14 +103,10 @@ class MRDOX_VISIBLE
     /** Visit the specified symbol ID or node.
     */
     /** @{ */
-    MRDOX_DECL [[nodiscard]] bool visit(
-        SymbolID id, Visitor& f) const;
-    MRDOX_DECL [[nodiscard]] bool visit(
-        Scope const& I, Visitor& f) const;
-    MRDOX_DECL [[nodiscard]] bool visitWithOverloads(
-        Scope const& I, Visitor& f) const;
-    MRDOX_DECL [[nodiscard]] bool visit(
-        Info const& I, Visitor& f) const;
+    MRDOX_DECL bool visit(SymbolID id, Visitor& f) const;
+    MRDOX_DECL bool visit(Scope const& I, Visitor& f) const;
+    MRDOX_DECL bool visitWithOverloads(Scope const& I, Visitor& f) const;
+    MRDOX_DECL bool visit(Info const& I, Visitor& f) const;
     /** @} */
 
     //--------------------------------------------
diff --git a/include/mrdox/Metadata/Overloads.hpp b/include/mrdox/Metadata/Overloads.hpp
@@ -46,6 +46,15 @@ struct OverloadsSet
 
 /** Create an overload set for all functions in a scope.
 */
+MRDOX_DECL
+OverloadsSet
+makeOverloadsSet(
+    Corpus const& corpus,
+    Scope const& scope);
+
+/** Create an overload set for all functions in a scope.
+*/
+MRDOX_DECL
 OverloadsSet
 makeOverloadsSet(
     Corpus const& corpus,
diff --git a/include/mrdox/Metadata/Symbols.hpp b/include/mrdox/Metadata/Symbols.hpp
@@ -59,6 +59,7 @@ enum class InfoType
     are compared with lowercase letters coming
     before uppercase letters.
 */
+MRDOX_DECL
 std::strong_ordering
 compareSymbolNames(
     llvm::StringRef symbolName0,
diff --git a/include/mrdox/MetadataFwd.hpp b/include/mrdox/MetadataFwd.hpp
@@ -21,6 +21,8 @@
 namespace clang {
 namespace mrdox {
 
+class Corpus;
+
 struct BaseRecordInfo;
 struct EnumValueInfo;
 struct EnumInfo;
diff --git a/source/lib/ConfigImpl.cpp b/source/lib/ConfigImpl.cpp
@@ -55,6 +55,17 @@ ConfigImpl(
 {
 }
 
+void
+ConfigImpl::
+setOutputPath(
+    llvm::StringRef outputPath)
+{
+    namespace path = llvm::sys::path;
+    outputPath_ = outputPath;
+    path::remove_dots(outputPath_, true);
+    path::make_preferred(outputPath_);
+}
+
 void
 ConfigImpl::
 setSourceRoot(
diff --git a/source/lib/ConfigImpl.hpp b/source/lib/ConfigImpl.hpp
@@ -44,6 +44,10 @@ class ConfigImpl
     ConfigImpl(
         llvm::StringRef configDir);
 
+    void
+    setOutputPath(
+        llvm::StringRef outputPath) override;
+
     void
     setSourceRoot(
         llvm::StringRef dirPath) override;
diff --git a/source/lib/Metadata/Overloads.cpp b/source/lib/Metadata/Overloads.cpp
@@ -17,21 +17,21 @@
 namespace clang {
 namespace mrdox {
 
+template<class Pred>
+static
 OverloadsSet
-makeOverloadsSet(
+makeOverloadsSetImpl(
     Corpus const& corpus,
     Scope const& scope,
-    AccessSpecifier access)
+    Pred&& pred)
 {
     OverloadsSet result;
-    result.access = access;
-
     std::vector<FunctionInfo const*> temp;
     temp.reserve(scope.Functions.size());
     for(auto const& ref : scope.Functions)
     {
         auto const& I = corpus.get<FunctionInfo>(ref.id);
-        if(I.Access == access)
+        if(pred(I))
             temp.push_back(&I);
     }
     if(temp.empty())
@@ -62,5 +62,30 @@ makeOverloadsSet(
     return result;
 }
 
+OverloadsSet
+makeOverloadsSet(
+    Corpus const& corpus,
+    Scope const& scope)
+{
+    return makeOverloadsSetImpl(corpus, scope,
+        [](FunctionInfo const& I)
+        {
+            return true;
+        });
+}
+
+OverloadsSet
+makeOverloadsSet(
+    Corpus const& corpus,
+    Scope const& scope,
+    AccessSpecifier access)
+{
+    return makeOverloadsSetImpl(corpus, scope,
+        [access](FunctionInfo const& I)
+        {
+            return I.Access == access;
+        });
+}
+
 } // mrdox
 } // clang
diff --git a/source/lib/_adoc/AdocGenerator.cpp b/source/lib/_adoc/AdocGenerator.cpp
@@ -13,6 +13,7 @@
 #include "AdocMultiPageWriter.hpp"
 #include "AdocPagesBuilder.hpp"
 #include "AdocSinglePageWriter.hpp"
+#include "SafeNames.hpp"
 
 namespace clang {
 namespace mrdox {
@@ -31,56 +32,7 @@ buildPages(
     Corpus const& corpus,
     Reporter& R) const
 {
-    namespace fs = llvm::sys::fs;
-    namespace path = llvm::sys::path;
-
-#if 0
-    // Track which directories we already tried to create.
-    llvm::StringSet<> CreatedDirs;
-
-    // Collect all output by file name and create the necessary directories.
-    llvm::StringMap<std::vector<mrdox::Info*>> FileToInfos;
-    for (const auto& Group : corpus.InfoMap)
-    {
-        mrdox::Info* Info = Group.getValue().get();
-
-        llvm::SmallString<128> Path;
-        llvm::sys::path::native(RootDir, Path);
-        llvm::sys::path::append(Path, Info->getRelativeFilePath(""));
-        if (!CreatedDirs.contains(Path)) {
-            if (std::error_code Err = llvm::sys::fs::create_directories(Path);
-                Err != std::error_code()) {
-                return llvm::createStringError(Err, "Failed to create directory '%s'.",
-                    Path.c_str());
-            }
-            CreatedDirs.insert(Path);
-        }
-
-        llvm::sys::path::append(Path, Info->getFileBaseName() + ".adoc");
-        FileToInfos[Path].push_back(Info);
-    }
-
-    for (const auto& Group : FileToInfos) {
-        std::error_code FileErr;
-        llvm::raw_fd_ostream InfoOS(Group.getKey(), FileErr,
-            llvm::sys::fs::OF_None);
-        if (FileErr) {
-            return llvm::createStringError(FileErr, "Error opening file '%s'",
-                Group.getKey().str().c_str());
-        }
-
-        for (const auto& Info : Group.getValue()) {
-            if (llvm::Error Err = generateDocForInfo(Info, InfoOS, config)) {
-                return Err;
-            }
-        }
-    }
-    return true;
-#endif
-    AdocPagesBuilder builder(corpus);
-    builder.scan();
-
-    return llvm::Error::success();
+    return AdocPagesBuilder(outputPath, corpus, R).build();
 }
 
 llvm::Error
diff --git a/source/lib/_adoc/AdocMultiPageWriter.cpp b/source/lib/_adoc/AdocMultiPageWriter.cpp
@@ -20,68 +20,63 @@ AdocMultiPageWriter(
     llvm::raw_ostream& os,
     llvm::raw_fd_ostream* fd_os,
     Corpus const& corpus,
+    SafeNames const& names,
     Reporter& R) noexcept
     : AdocWriter(os, fd_os, corpus, R)
+    , names_(names)
 {
 }
 
-llvm::Error
+void
 AdocMultiPageWriter::
-build()
-{
-    Assert(sect_.level == 0);
-    sect_.level = 1;
-    sect_.markup = "=";
-    os_ <<
-        "= Reference\n"
-        ":role: mrdox\n";
-    (void)corpus_.visit(globalNamespaceID, *this);
-    closeSection();
-    return llvm::Error::success();
-}
-
-bool
-AdocMultiPageWriter::
-visit(
-    NamespaceInfo const& I)
-{
-    return corpus_.visit(I.Children, *this);
-}
-
-bool
-AdocMultiPageWriter::
-visit(
+build(
     RecordInfo const& I)
 {
+    writeTitle(I);
+    os_ << '\n';
     write(I);
-    return corpus_.visit(I.Children, *this);
 }
 
-bool
+void
 AdocMultiPageWriter::
-visit(
+build(
     FunctionInfo const& I)
 {
+    writeTitle(I);
+    os_ << '\n';
     write(I);
-    return true;
 }
 
-bool
+void
 AdocMultiPageWriter::
-visit(
+build(
     TypedefInfo const& I)
 {
+    writeTitle(I);
+    os_ << '\n';
     write(I);
-    return true;
 }
 
-bool
+void
 AdocMultiPageWriter::
-visit(
+build(
     EnumInfo const& I)
 {
+    writeTitle(I);
+    os_ << '\n';
     write(I);
-    return true;
+}
+
+void
+AdocMultiPageWriter::
+writeTitle(Info const& I)
+{
+    Assert(sect_.level == 0);
+    sect_.level = 1;
+    sect_.markup = "=";
+    os_ <<
+        "= " << I.Name << "\n"
+        ":role: mrdox\n";
 }
 
 } // adoc
diff --git a/source/lib/_adoc/AdocMultiPageWriter.hpp b/source/lib/_adoc/AdocMultiPageWriter.hpp
@@ -12,6 +12,7 @@
 #define MRDOX_LIB_ADOC_ADOCMULTIPAGEWRITER_HPP
 
 #include "AdocWriter.hpp"
+#include "SafeNames.hpp"
 #include <mrdox/Corpus.hpp>
 
 namespace clang {
@@ -20,23 +21,24 @@ namespace adoc {
 
 class AdocMultiPageWriter
     : public AdocWriter
-    , public Corpus::Visitor
 {
+    SafeNames const& names_;
+
 public:
     AdocMultiPageWriter(
         llvm::raw_ostream& os,
         llvm::raw_fd_ostream* fd_os,
         Corpus const& corpus,
+        SafeNames const& names,
         Reporter& R) noexcept;
 
-    llvm::Error build();
+    void build(RecordInfo const&);
+    void build(FunctionInfo const&);
+    void build(TypedefInfo const&);
+    void build(EnumInfo const&);
 
 private:
-    bool visit(NamespaceInfo const&) override;
-    bool visit(RecordInfo const&) override;
-    bool visit(FunctionInfo const&) override;
-    bool visit(TypedefInfo const&) override;
-    bool visit(EnumInfo const&) override;
+    void writeTitle(Info const& I);
 };
 
 } // adoc
diff --git a/source/lib/_adoc/AdocPagesBuilder.cpp b/source/lib/_adoc/AdocPagesBuilder.cpp
diff --git a/source/lib/_adoc/AdocPagesBuilder.hpp b/source/lib/_adoc/AdocPagesBuilder.hpp
diff --git a/source/lib/_adoc/AdocSinglePageWriter.cpp b/source/lib/_adoc/AdocSinglePageWriter.cpp
diff --git a/source/lib/_adoc/SafeNames.cpp b/source/lib/_adoc/SafeNames.cpp
diff --git a/source/lib/_adoc/SafeNames.hpp b/source/lib/_adoc/SafeNames.hpp
diff --git a/source/tool/ToolMain.cpp b/source/tool/ToolMain.cpp
