Rewrite/Core/HTMLRewrite.h

0001 //==- HTMLRewrite.h - Translate source code into prettified HTML ---*- C++ -*-//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008 //
0009 //  This file defines a set of functions used for translating source code
0010 //  into beautified HTML.
0011 //
0012 //===----------------------------------------------------------------------===//
0013
0014 #ifndef LLVM_CLANG_REWRITE_CORE_HTMLREWRITE_H
0015 #define LLVM_CLANG_REWRITE_CORE_HTMLREWRITE_H
0016
0017 #include "clang/Basic/SourceLocation.h"
0018 #include <string>
0019
0020 namespace llvm {
0021 class RewriteBuffer;
0022 } // namespace llvm
0023
0024 namespace clang {
0025
0026 class Rewriter;
0027 class Preprocessor;
0028
0029 namespace html {
0030   struct RelexRewriteCache;
0031   using RelexRewriteCacheRef = std::shared_ptr<RelexRewriteCache>;
0032
0033   /// If you need to rewrite the same file multiple times, you can instantiate
0034   /// a RelexRewriteCache and refer functions such as SyntaxHighlight()
0035   /// and HighlightMacros() to it so that to avoid re-lexing the file each time.
0036   /// The cache may outlive the rewriter as long as cached FileIDs and source
0037   /// locations continue to make sense for the translation unit as a whole.
0038   RelexRewriteCacheRef instantiateRelexRewriteCache();
0039
0040   /// HighlightRange - Highlight a range in the source code with the specified
0041   /// start/end tags.  B/E must be in the same file.  This ensures that
0042   /// start/end tags are placed at the start/end of each line if the range is
0043   /// multiline.
0044   void HighlightRange(Rewriter &R, SourceLocation B, SourceLocation E,
0045                       const char *StartTag, const char *EndTag,
0046                       bool IsTokenRange = true);
0047
0048   /// HighlightRange - Highlight a range in the source code with the specified
0049   /// start/end tags.  The Start/end of the range must be in the same file.
0050   /// This ensures that start/end tags are placed at the start/end of each line
0051   /// if the range is multiline.
0052   inline void HighlightRange(Rewriter &R, SourceRange Range,
0053                              const char *StartTag, const char *EndTag) {
0054     HighlightRange(R, Range.getBegin(), Range.getEnd(), StartTag, EndTag);
0055   }
0056
0057   /// HighlightRange - This is the same as the above method, but takes
0058   /// decomposed file locations.
0059   void HighlightRange(llvm::RewriteBuffer &RB, unsigned B, unsigned E,
0060                       const char *BufferStart, const char *StartTag,
0061                       const char *EndTag);
0062
0063   /// EscapeText - HTMLize a specified file so that special characters are
0064   /// are translated so that they are not interpreted as HTML tags.
0065   void EscapeText(Rewriter& R, FileID FID,
0066                   bool EscapeSpaces = false, bool ReplaceTabs = false);
0067
0068   /// EscapeText - HTMLized the provided string so that special characters
0069   ///  in 's' are not interpreted as HTML tags.  Unlike the version of
0070   ///  EscapeText that rewrites a file, this version by default replaces tabs
0071   ///  with spaces.
0072   std::string EscapeText(StringRef s,
0073                          bool EscapeSpaces = false, bool ReplaceTabs = false);
0074
0075   void AddLineNumbers(Rewriter& R, FileID FID);
0076
0077   void AddHeaderFooterInternalBuiltinCSS(Rewriter &R, FileID FID,
0078                                          StringRef title);
0079
0080   /// SyntaxHighlight - Relex the specified FileID and annotate the HTML with
0081   /// information about keywords, comments, etc.
0082   void SyntaxHighlight(Rewriter &R, FileID FID, const Preprocessor &PP,
0083                        RelexRewriteCacheRef Cache = nullptr);
0084
0085   /// HighlightMacros - This uses the macro table state from the end of the
0086   /// file, to reexpand macros and insert (into the HTML) information about the
0087   /// macro expansions.  This won't be perfectly perfect, but it will be
0088   /// reasonably close.
0089   void HighlightMacros(Rewriter &R, FileID FID, const Preprocessor &PP,
0090                        RelexRewriteCacheRef Cache = nullptr);
0091
0092 } // end html namespace
0093 } // end clang namespace
0094
0095 #endif