fix(HandlebarsGenerator): escape reserved chars

cppalliance · Nov 22, 2024 · a89e82f · a89e82f
1 parent ece7e7d
commit a89e82f
Show file tree

Hide file tree

Showing 200 changed files with 1,828 additions and 1,746 deletions.
diff --git a/share/mrdocs/addons/generator/adoc/layouts/index.adoc.hbs b/share/mrdocs/addons/generator/adoc/layouts/index.adoc.hbs
@@ -1,5 +1,5 @@
 {{! The section with a symbol in single page output or the symbol page in multi page output }}
 {{#if relfileprefix}}:relfileprefix: {{relfileprefix}}{{/if}}
 
-[#{{sectionref}}]
+[#{{{sectionref}}}]
 {{> symbol symbol=symbol}}
diff --git a/share/mrdocs/addons/generator/adoc/layouts/wrapper.adoc.hbs b/share/mrdocs/addons/generator/adoc/layouts/wrapper.adoc.hbs
@@ -4,6 +4,6 @@
 :mrdocs:
 {{/unless}}
 {{! Content generated with index.hbs }}
-{{contents}}
+{{{contents}}}
 
 [.small]#Created with https://www.mrdocs.com[MrDocs]#
diff --git a/share/mrdocs/addons/generator/adoc/partials/markup/a.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/markup/a.adoc.hbs
@@ -1 +1 @@
-xref:{{href}}[{{> @partial-block }}]
+xref:{{{href}}}[{{> @partial-block }}]
diff --git a/share/mrdocs/addons/generator/adoc/partials/symbols/alias.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/symbols/alias.adoc.hbs
@@ -1,7 +1,7 @@
 {{!-- alias --}}
 ={{#unless @root.config.multipage}}={{/unless}} {{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
 
-{{symbol.doc.brief}}
+{{{symbol.doc.brief}}}
 
 =={{#unless @root.config.multipage}}={{/unless}} Synopsis
 

diff --git a/share/mrdocs/addons/generator/adoc/partials/symbols/concept.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/symbols/concept.adoc.hbs
@@ -1,7 +1,7 @@
 {{!-- concept --}}
 = {{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
 
-{{symbol.doc.brief}}
+{{{symbol.doc.brief}}}
 
 == Synopsis
 

diff --git a/share/mrdocs/addons/generator/adoc/partials/symbols/enum.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/symbols/enum.adoc.hbs
@@ -1,7 +1,7 @@
 {{!-- enum --}}
 ={{#unless @root.config.multipage}}={{/unless}} {{#if symbol.name}}{{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}{{else}}Unnamed enum{{/if}}
 
-{{symbol.doc.brief}}
+{{{symbol.doc.brief}}}
 
 =={{#unless @root.config.multipage}}={{/unless}} Synopsis
 
@@ -18,7 +18,7 @@
 |===
 |Name |Description
 {{#each symbol.members}}
-|xref:{{ref}}[`pass:v[{{>types/declarator-id . nolink=true}}]`] | {{~doc.brief}}
+|xref:{{{ref}}}[`pass:v[{{>types/declarator-id . nolink=true}}]`] | {{~doc.brief}}
 {{/each}}
 |===
 {{/if}}

diff --git a/share/mrdocs/addons/generator/adoc/partials/symbols/enumerator.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/symbols/enumerator.adoc.hbs
@@ -1,7 +1,7 @@
 {{!-- enumerator --}}
 ={{#unless @root.config.multipage}}={{/unless}} {{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
 
-{{symbol.doc.brief}}
+{{{symbol.doc.brief}}}
 
 =={{#unless @root.config.multipage}}={{/unless}} Synopsis
 

diff --git a/share/mrdocs/addons/generator/adoc/partials/symbols/field.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/symbols/field.adoc.hbs
@@ -1,7 +1,7 @@
 {{!-- field --}}
 ={{#unless @root.config.multipage}}={{/unless}} {{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
 
-{{symbol.doc.brief}}
+{{{symbol.doc.brief}}}
 
 =={{#unless @root.config.multipage}}={{/unless}} Synopsis
 

diff --git a/share/mrdocs/addons/generator/adoc/partials/symbols/friend.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/symbols/friend.adoc.hbs
@@ -1,7 +1,7 @@
 {{!-- friend --}}
 ={{#unless @root.config.multipage}}={{/unless}} {{#if symbol.symbol}}{{>types/nested-name-specifier symbol=symbol.symbol.parent includeNamespace=true}}{{symbol.symbol.name}}{{else}}{{symbol.type.name}}{{/if}}
 
-{{symbol.doc.brief}}
+{{{symbol.doc.brief}}}
 
 =={{#unless @root.config.multipage}}={{/unless}} Synopsis
 

diff --git a/share/mrdocs/addons/generator/adoc/partials/symbols/function.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/symbols/function.adoc.hbs
@@ -1,7 +1,7 @@
 {{!-- function --}}
 ={{#unless @root.config.multipage}}={{/unless}} {{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
 
-{{symbol.doc.brief}}
+{{{symbol.doc.brief}}}
 
 =={{#unless @root.config.multipage}}={{/unless}} Synopsis
 

diff --git a/share/mrdocs/addons/generator/adoc/partials/symbols/guide.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/symbols/guide.adoc.hbs
@@ -1,7 +1,7 @@
 {{!-- guides --}}
 ={{#unless @root.config.multipage}}={{/unless}} {{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
 
-{{symbol.doc.brief}}
+{{{symbol.doc.brief}}}
 
 =={{#unless @root.config.multipage}}={{/unless}} Synopsis
 

diff --git a/share/mrdocs/addons/generator/adoc/partials/symbols/record.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/symbols/record.adoc.hbs
@@ -1,7 +1,7 @@
 {{!-- record --}}
 ={{#unless @root.config.multipage}}={{/unless}} {{#if symbol.name}}{{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}{{else}}Unnamed class{{/if}}
 
-{{symbol.doc.brief}}
+{{{symbol.doc.brief}}}
 
 =={{#unless @root.config.multipage}}={{/unless}} Synopsis
 

diff --git a/share/mrdocs/addons/generator/adoc/partials/symbols/typedef.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/symbols/typedef.adoc.hbs
@@ -1,7 +1,7 @@
 {{!-- typedef --}}
 ={{#unless @root.config.multipage}}={{/unless}} {{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
 
-{{symbol.doc.brief}}
+{{{symbol.doc.brief}}}
 
 =={{#unless @root.config.multipage}}={{/unless}} Synopsis
 

diff --git a/share/mrdocs/addons/generator/adoc/partials/symbols/using.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/symbols/using.adoc.hbs
@@ -1,7 +1,7 @@
 {{!-- symbols/using.adoc.hbs --}}
 ={{#unless @root.config.multipage}}={{/unless}} {{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
 
-{{symbol.doc.brief}}
+{{{symbol.doc.brief}}}
 
 =={{#unless @root.config.multipage}}={{/unless}} Synopsis
 

diff --git a/share/mrdocs/addons/generator/adoc/partials/symbols/variable.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/symbols/variable.adoc.hbs
@@ -1,7 +1,7 @@
 {{!-- variable --}}
 ={{#unless @root.config.multipage}}={{/unless}} {{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
 
-{{symbol.doc.brief}}
+{{{symbol.doc.brief}}}
 
 =={{#unless @root.config.multipage}}={{/unless}} Synopsis
 

diff --git a/share/mrdocs/addons/generator/common/partials/types/info-member.hbs b/share/mrdocs/addons/generator/common/partials/types/info-member.hbs
@@ -5,10 +5,10 @@
 {{~/markup/td}}
 {{#>markup/td~}}
     {{#if (ne kind "overload")~}}
-        {{~doc.brief}}
+        {{{~doc.brief}}}
     {{else~}}
         {{#each (unique (pluck (pluck members "doc") "brief"))~}}
-            {{.}}
+            {{{.}}}
         {{/each~}}
     {{/if}}
 {{~/markup/td}}

diff --git a/share/mrdocs/addons/generator/html/layouts/wrapper.html.hbs b/share/mrdocs/addons/generator/html/layouts/wrapper.html.hbs
@@ -6,7 +6,7 @@
 <body>
 <div>
     {{! Content generated with index.hbs }}
-    {{contents}}
+    {{{contents}}}
 </div>
 <div>
     <h4>Created with <a href="https://www.mrdocs.com">MrDocs</a></h4>

diff --git a/share/mrdocs/addons/generator/html/partials/markup/a.html.hbs b/share/mrdocs/addons/generator/html/partials/markup/a.html.hbs
@@ -1 +1 @@
-<a href="{{href}}">{{> @partial-block }}</a>
+<a href="{{{href}}}">{{> @partial-block }}</a>
diff --git a/share/mrdocs/addons/generator/html/partials/symbols/concept.html.hbs b/share/mrdocs/addons/generator/html/partials/symbols/concept.html.hbs
@@ -2,7 +2,7 @@
 <div {{#if sectionref}}id="{{sectionref}}"{{/if}}>
     <div>
         <h2>{{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}</h2>
-        {{symbol.doc.brief}}
+        {{{symbol.doc.brief}}}
     </div>
     <div>
         <h3>Synopsis</h3>

diff --git a/src/lib/Gen/adoc/AdocGenerator.cpp b/src/lib/Gen/adoc/AdocGenerator.cpp
@@ -11,6 +11,7 @@
 
 #include "AdocGenerator.hpp"
 #include "DocVisitor.hpp"
+#include <mrdocs/Support/Handlebars.hpp>
 
 namespace clang {
 namespace mrdocs {
@@ -31,6 +32,24 @@ toString(hbs::HandlebarsCorpus const& c, doc::Node const& I) const
     return s;
 }
 
+void
+AdocGenerator::
+escape(OutputRef& os, std::string_view str) const
+{
+    static constexpr std::string_view formattingChars = "\\`*_{}[]()#+-.!|";
+    bool const needsEscape = str.find_first_of(formattingChars) != std::string_view::npos;
+    if (needsEscape)
+    {
+        os << "pass:[";
+        os << str;
+        os << "]";
+    }
+    else
+    {
+        os << str;
+    }
+}
+
 } // adoc
 
 std::unique_ptr<Generator>

diff --git a/src/lib/Gen/adoc/AdocGenerator.hpp b/src/lib/Gen/adoc/AdocGenerator.hpp
@@ -31,6 +31,9 @@ class AdocGenerator
     toString(
         hbs::HandlebarsCorpus const&,
         doc::Node const&) const override;
+
+    void
+    escape(OutputRef& os, std::string_view str) const override;
 };
 
 } // adoc

diff --git a/src/lib/Gen/hbs/Builder.cpp b/src/lib/Gen/hbs/Builder.cpp
@@ -73,8 +73,10 @@ loadPartials(
 
 Builder::
 Builder(
-    HandlebarsCorpus const& corpus)
+    HandlebarsCorpus const& corpus,
+    std::function<void(OutputRef&, std::string_view)> escapeFn)
     : domCorpus(corpus)
+    , escapeFn_(std::move(escapeFn))
 {
     namespace fs = std::filesystem;
 
@@ -156,7 +158,7 @@ callTemplate(
     auto pathName = files::appendPath(layoutDir(), name);
     MRDOCS_TRY(auto fileText, files::getFileText(pathName));
     HandlebarsOptions options;
-    options.noEscape = true;
+    options.escapeFunction = escapeFn_;
     Expected<std::string, HandlebarsError> exp =
         hbs_.try_render(fileText, context, options);
     if (!exp)
@@ -285,7 +287,7 @@ renderWrapped(
     auto pathName = files::appendPath(layoutDir(), wrapperFile);
     MRDOCS_TRY(auto fileText, files::getFileText(pathName));
     HandlebarsOptions options;
-    options.noEscape = true;
+    options.escapeFunction = escapeFn_;
     OutputRef outRef(os);
     Expected<void, HandlebarsError> exp =
         hbs_.try_render_to(

diff --git a/src/lib/Gen/hbs/Builder.hpp b/src/lib/Gen/hbs/Builder.hpp
@@ -33,6 +33,7 @@ class Builder
 {
     js::Context ctx_;
     Handlebars hbs_;
+    std::function<void(OutputRef&, std::string_view)> escapeFn_;
 
     std::string
     getRelPrefix(std::size_t depth);
@@ -41,7 +42,9 @@ class Builder
     HandlebarsCorpus const& domCorpus;
 
     explicit
-    Builder(HandlebarsCorpus const& corpus);
+    Builder(
+        HandlebarsCorpus const& corpus,
+        std::function<void(OutputRef&, std::string_view)> escapeFn);
 
     /** Render the contents for a symbol.
 

diff --git a/src/lib/Gen/hbs/HandlebarsGenerator.cpp b/src/lib/Gen/hbs/HandlebarsGenerator.cpp
@@ -22,8 +22,17 @@ namespace clang {
 namespace mrdocs {
 namespace hbs {
 
+std::function<void(OutputRef&, std::string_view)>
+createEscapeFn(HandlebarsGenerator const& gen)
+{
+    return [&gen](OutputRef out, std::string_view str) {
+        return gen.escape(out, str);
+    };
+}
+
 Expected<ExecutorGroup<Builder>>
 createExecutors(
+    HandlebarsGenerator const& gen,
     HandlebarsCorpus const& hbsCorpus)
 {
     auto const& config = hbsCorpus->config;
@@ -33,7 +42,7 @@ createExecutors(
     {
         try
         {
-           group.emplace(hbsCorpus);
+           group.emplace(hbsCorpus, createEscapeFn(gen));
         }
         catch(Exception const& ex)
         {
@@ -75,7 +84,7 @@ build(
 
     // Create corpus and executors
     HandlebarsCorpus domCorpus = createDomCorpus(*this, corpus);
-    MRDOCS_TRY(ExecutorGroup<Builder> ex, createExecutors(domCorpus));
+    MRDOCS_TRY(ExecutorGroup<Builder> ex, createExecutors(*this, domCorpus));
 
     // Visit the corpus
     MultiPageVisitor visitor(ex, outputPath, corpus);
@@ -95,7 +104,7 @@ buildOne(
 {
     // Create corpus and executors
     HandlebarsCorpus domCorpus = createDomCorpus(*this, corpus);
-    MRDOCS_TRY(ExecutorGroup<Builder> ex, createExecutors(domCorpus));
+    MRDOCS_TRY(ExecutorGroup<Builder> ex, createExecutors(*this, domCorpus));
 
     // Embedded mode
     if (corpus.config->embedded)
@@ -112,7 +121,7 @@ buildOne(
     }
 
     // Wrapped mode
-    Builder inlineBuilder(domCorpus);
+    Builder inlineBuilder(domCorpus, createEscapeFn(*this));
     return inlineBuilder.renderWrapped(os, [&]() -> Expected<void> {
         // This helper will write contents directly to ostream
         SinglePageVisitor visitor(ex, corpus, os);
@@ -126,6 +135,13 @@ buildOne(
     });
 }
 
+void
+HandlebarsGenerator::
+escape(OutputRef& out, std::string_view str) const
+{
+    out << str;
+}
+
 } // hbs
 } // mrdocs
 } // clang
diff --git a/src/lib/Gen/hbs/HandlebarsGenerator.hpp b/src/lib/Gen/hbs/HandlebarsGenerator.hpp
@@ -20,6 +20,9 @@
 
 namespace clang {
 namespace mrdocs {
+
+class OutputRef;
+
 namespace hbs {
 
 class HandlebarsGenerator
@@ -72,6 +75,12 @@ class HandlebarsGenerator
     {
         return {};
     }
+
+    /** Output a escaped string to the output stream.
+    */
+    virtual
+    void
+    escape(OutputRef& os, std::string_view str) const;
 };
 
 } // hbs

diff --git a/src/lib/Gen/html/HTMLGenerator.cpp b/src/lib/Gen/html/HTMLGenerator.cpp
@@ -11,6 +11,7 @@
 
 #include "HTMLGenerator.hpp"
 #include "DocVisitor.hpp"
+#include <mrdocs/Support/Handlebars.hpp>
 
 namespace clang {
 namespace mrdocs {
@@ -31,6 +32,13 @@ toString(hbs::HandlebarsCorpus const& c, doc::Node const& I) const
     return s;
 }
 
+void
+HTMLGenerator::
+escape(OutputRef& os, std::string_view str) const
+{
+    HTMLEscape(os, str);
+}
+
 } // html
 
 //------------------------------------------------

diff --git a/src/lib/Gen/html/HTMLGenerator.hpp b/src/lib/Gen/html/HTMLGenerator.hpp
@@ -31,6 +31,9 @@ class HTMLGenerator
     toString(
         hbs::HandlebarsCorpus const&,
         doc::Node const&) const override;
+
+    void
+    escape(OutputRef& os, std::string_view str) const override;
 };
 
 } // html
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		xref:{{href}}[{{> @partial-block }}]
		xref:{{{href}}}[{{> @partial-block }}]
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		<a href="{{href}}">{{> @partial-block }}</a>
		<a href="{{{href}}}">{{> @partial-block }}</a>