xref: /llvm-project/clang/include/clang/Rewrite/Core/HTMLRewrite.h (revision 0d150db214e2aa13a825b563c7238e1243d61db1)
1 //==- HTMLRewrite.h - Translate source code into prettified HTML ---*- C++ -*-//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 //
9 //  This file defines a set of functions used for translating source code
10 //  into beautified HTML.
11 //
12 //===----------------------------------------------------------------------===//
13 
14 #ifndef LLVM_CLANG_REWRITE_CORE_HTMLREWRITE_H
15 #define LLVM_CLANG_REWRITE_CORE_HTMLREWRITE_H
16 
17 #include "clang/Basic/SourceLocation.h"
18 #include <string>
19 
20 namespace llvm {
21 class RewriteBuffer;
22 } // namespace llvm
23 
24 namespace clang {
25 
26 class Rewriter;
27 class Preprocessor;
28 
29 namespace html {
30   struct RelexRewriteCache;
31   using RelexRewriteCacheRef = std::shared_ptr<RelexRewriteCache>;
32 
33   /// If you need to rewrite the same file multiple times, you can instantiate
34   /// a RelexRewriteCache and refer functions such as SyntaxHighlight()
35   /// and HighlightMacros() to it so that to avoid re-lexing the file each time.
36   /// The cache may outlive the rewriter as long as cached FileIDs and source
37   /// locations continue to make sense for the translation unit as a whole.
38   RelexRewriteCacheRef instantiateRelexRewriteCache();
39 
40   /// HighlightRange - Highlight a range in the source code with the specified
41   /// start/end tags.  B/E must be in the same file.  This ensures that
42   /// start/end tags are placed at the start/end of each line if the range is
43   /// multiline.
44   void HighlightRange(Rewriter &R, SourceLocation B, SourceLocation E,
45                       const char *StartTag, const char *EndTag,
46                       bool IsTokenRange = true);
47 
48   /// HighlightRange - Highlight a range in the source code with the specified
49   /// start/end tags.  The Start/end of the range must be in the same file.
50   /// This ensures that start/end tags are placed at the start/end of each line
51   /// if the range is multiline.
52   inline void HighlightRange(Rewriter &R, SourceRange Range,
53                              const char *StartTag, const char *EndTag) {
54     HighlightRange(R, Range.getBegin(), Range.getEnd(), StartTag, EndTag);
55   }
56 
57   /// HighlightRange - This is the same as the above method, but takes
58   /// decomposed file locations.
59   void HighlightRange(llvm::RewriteBuffer &RB, unsigned B, unsigned E,
60                       const char *BufferStart, const char *StartTag,
61                       const char *EndTag);
62 
63   /// EscapeText - HTMLize a specified file so that special characters are
64   /// are translated so that they are not interpreted as HTML tags.
65   void EscapeText(Rewriter& R, FileID FID,
66                   bool EscapeSpaces = false, bool ReplaceTabs = false);
67 
68   /// EscapeText - HTMLized the provided string so that special characters
69   ///  in 's' are not interpreted as HTML tags.  Unlike the version of
70   ///  EscapeText that rewrites a file, this version by default replaces tabs
71   ///  with spaces.
72   std::string EscapeText(StringRef s,
73                          bool EscapeSpaces = false, bool ReplaceTabs = false);
74 
75   void AddLineNumbers(Rewriter& R, FileID FID);
76 
77   void AddHeaderFooterInternalBuiltinCSS(Rewriter &R, FileID FID,
78                                          StringRef title);
79 
80   /// SyntaxHighlight - Relex the specified FileID and annotate the HTML with
81   /// information about keywords, comments, etc.
82   void SyntaxHighlight(Rewriter &R, FileID FID, const Preprocessor &PP,
83                        RelexRewriteCacheRef Cache = nullptr);
84 
85   /// HighlightMacros - This uses the macro table state from the end of the
86   /// file, to reexpand macros and insert (into the HTML) information about the
87   /// macro expansions.  This won't be perfectly perfect, but it will be
88   /// reasonably close.
89   void HighlightMacros(Rewriter &R, FileID FID, const Preprocessor &PP,
90                        RelexRewriteCacheRef Cache = nullptr);
91 
92 } // end html namespace
93 } // end clang namespace
94 
95 #endif
96