contrib/llvm-project/clang/lib/Format/WhitespaceManager.h

   1 //===--- WhitespaceManager.h - Format C++ code ------------------*- 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 /// \file
  10 /// WhitespaceManager class manages whitespace around tokens and their
  11 /// replacements.
  12 ///
  13 //===----------------------------------------------------------------------===//
  14
  15 #ifndef LLVM_CLANG_LIB_FORMAT_WHITESPACEMANAGER_H
  16 #define LLVM_CLANG_LIB_FORMAT_WHITESPACEMANAGER_H
  17
  18 #include "TokenAnnotator.h"
  19 #include "clang/Basic/SourceManager.h"
  20 #include "clang/Format/Format.h"
  21 #include <string>
  22
  23 namespace clang {
  24 namespace format {
  25
  26 /// Manages the whitespaces around tokens and their replacements.
  27 ///
  28 /// This includes special handling for certain constructs, e.g. the alignment of
  29 /// trailing line comments.
  30 ///
  31 /// To guarantee correctness of alignment operations, the \c WhitespaceManager
  32 /// must be informed about every token in the source file; for each token, there
  33 /// must be exactly one call to either \c replaceWhitespace or
  34 /// \c addUntouchableToken.
  35 ///
  36 /// There may be multiple calls to \c breakToken for a given token.
  37 class WhitespaceManager {
  38 public:
  39   WhitespaceManager(const SourceManager &SourceMgr, const FormatStyle &Style,
  40                     bool UseCRLF)
  41       : SourceMgr(SourceMgr), Style(Style), UseCRLF(UseCRLF) {}
  42
  43   bool useCRLF() const { return UseCRLF; }
  44
  45   /// Replaces the whitespace in front of \p Tok. Only call once for
  46   /// each \c AnnotatedToken.
  47   ///
  48   /// \p StartOfTokenColumn is the column at which the token will start after
  49   /// this replacement. It is needed for determining how \p Spaces is turned
  50   /// into tabs and spaces for some format styles.
  51   void replaceWhitespace(FormatToken &Tok, unsigned Newlines, unsigned Spaces,
  52                          unsigned StartOfTokenColumn,
  53                          bool InPPDirective = false);
  54
  55   /// Adds information about an unchangeable token's whitespace.
  56   ///
  57   /// Needs to be called for every token for which \c replaceWhitespace
  58   /// was not called.
  59   void addUntouchableToken(const FormatToken &Tok, bool InPPDirective);
  60
  61   llvm::Error addReplacement(const tooling::Replacement &Replacement);
  62
  63   /// Inserts or replaces whitespace in the middle of a token.
  64   ///
  65   /// Inserts \p PreviousPostfix, \p Newlines, \p Spaces and \p CurrentPrefix
  66   /// (in this order) at \p Offset inside \p Tok, replacing \p ReplaceChars
  67   /// characters.
  68   ///
  69   /// Note: \p Spaces can be negative to retain information about initial
  70   /// relative column offset between a line of a block comment and the start of
  71   /// the comment. This negative offset may be compensated by trailing comment
  72   /// alignment here. In all other cases negative \p Spaces will be truncated to
  73   /// 0.
  74   ///
  75   /// When \p InPPDirective is true, escaped newlines are inserted. \p Spaces is
  76   /// used to align backslashes correctly.
  77   void replaceWhitespaceInToken(const FormatToken &Tok, unsigned Offset,
  78                                 unsigned ReplaceChars,
  79                                 StringRef PreviousPostfix,
  80                                 StringRef CurrentPrefix, bool InPPDirective,
  81                                 unsigned Newlines, int Spaces);
  82
  83   /// Returns all the \c Replacements created during formatting.
  84   const tooling::Replacements &generateReplacements();
  85
  86   /// Represents a change before a token, a break inside a token,
  87   /// or the layout of an unchanged token (or whitespace within).
  88   struct Change {
  89     /// Functor to sort changes in original source order.
  90     class IsBeforeInFile {
  91     public:
  92       IsBeforeInFile(const SourceManager &SourceMgr) : SourceMgr(SourceMgr) {}
  93       bool operator()(const Change &C1, const Change &C2) const;
  94
  95     private:
  96       const SourceManager &SourceMgr;
  97     };
  98
  99     /// Creates a \c Change.
 100     ///
 101     /// The generated \c Change will replace the characters at
 102     /// \p OriginalWhitespaceRange with a concatenation of
 103     /// \p PreviousLinePostfix, \p NewlinesBefore line breaks, \p Spaces spaces
 104     /// and \p CurrentLinePrefix.
 105     ///
 106     /// \p StartOfTokenColumn and \p InPPDirective will be used to lay out
 107     /// trailing comments and escaped newlines.
 108     Change(const FormatToken &Tok, bool CreateReplacement,
 109            SourceRange OriginalWhitespaceRange, int Spaces,
 110            unsigned StartOfTokenColumn, unsigned NewlinesBefore,
 111            StringRef PreviousLinePostfix, StringRef CurrentLinePrefix,
 112            bool ContinuesPPDirective, bool IsInsideToken);
 113
 114     // The kind of the token whose whitespace this change replaces, or in which
 115     // this change inserts whitespace.
 116     // FIXME: Currently this is not set correctly for breaks inside comments, as
 117     // the \c BreakableToken is still doing its own alignment.
 118     const FormatToken *Tok;
 119
 120     bool CreateReplacement;
 121     // Changes might be in the middle of a token, so we cannot just keep the
 122     // FormatToken around to query its information.
 123     SourceRange OriginalWhitespaceRange;
 124     unsigned StartOfTokenColumn;
 125     unsigned NewlinesBefore;
 126     std::string PreviousLinePostfix;
 127     std::string CurrentLinePrefix;
 128     bool ContinuesPPDirective;
 129
 130     // The number of spaces in front of the token or broken part of the token.
 131     // This will be adapted when aligning tokens.
 132     // Can be negative to retain information about the initial relative offset
 133     // of the lines in a block comment. This is used when aligning trailing
 134     // comments. Uncompensated negative offset is truncated to 0.
 135     int Spaces;
 136
 137     // If this change is inside of a token but not at the start of the token or
 138     // directly after a newline.
 139     bool IsInsideToken;
 140
 141     // \c IsTrailingComment, \c TokenLength, \c PreviousEndOfTokenColumn and
 142     // \c EscapedNewlineColumn will be calculated in
 143     // \c calculateLineBreakInformation.
 144     bool IsTrailingComment;
 145     unsigned TokenLength;
 146     unsigned PreviousEndOfTokenColumn;
 147     unsigned EscapedNewlineColumn;
 148
 149     // These fields are used to retain correct relative line indentation in a
 150     // block comment when aligning trailing comments.
 151     //
 152     // If this Change represents a continuation of a block comment,
 153     // \c StartOfBlockComment is pointer to the first Change in the block
 154     // comment. \c IndentationOffset is a relative column offset to this
 155     // change, so that the correct column can be reconstructed at the end of
 156     // the alignment process.
 157     const Change *StartOfBlockComment;
 158     int IndentationOffset;
 159
 160     // A combination of indent level and nesting level, which are used in
 161     // tandem to compute lexical scope, for the purposes of deciding
 162     // when to stop consecutive alignment runs.
 163     std::pair<unsigned, unsigned> indentAndNestingLevel() const {
 164       return std::make_pair(Tok->IndentLevel, Tok->NestingLevel);
 165     }
 166   };
 167
 168 private:
 169   /// Calculate \c IsTrailingComment, \c TokenLength for the last tokens
 170   /// or token parts in a line and \c PreviousEndOfTokenColumn and
 171   /// \c EscapedNewlineColumn for the first tokens or token parts in a line.
 172   void calculateLineBreakInformation();
 173
 174   /// \brief Align consecutive C/C++ preprocessor macros over all \c Changes.
 175   void alignConsecutiveMacros();
 176
 177   /// Align consecutive assignments over all \c Changes.
 178   void alignConsecutiveAssignments();
 179
 180   /// Align consecutive declarations over all \c Changes.
 181   void alignConsecutiveDeclarations();
 182
 183   /// Align trailing comments over all \c Changes.
 184   void alignTrailingComments();
 185
 186   /// Align trailing comments from change \p Start to change \p End at
 187   /// the specified \p Column.
 188   void alignTrailingComments(unsigned Start, unsigned End, unsigned Column);
 189
 190   /// Align escaped newlines over all \c Changes.
 191   void alignEscapedNewlines();
 192
 193   /// Align escaped newlines from change \p Start to change \p End at
 194   /// the specified \p Column.
 195   void alignEscapedNewlines(unsigned Start, unsigned End, unsigned Column);
 196
 197   /// Fill \c Replaces with the replacements for all effective changes.
 198   void generateChanges();
 199
 200   /// Stores \p Text as the replacement for the whitespace in \p Range.
 201   void storeReplacement(SourceRange Range, StringRef Text);
 202   void appendNewlineText(std::string &Text, unsigned Newlines);
 203   void appendEscapedNewlineText(std::string &Text, unsigned Newlines,
 204                                 unsigned PreviousEndOfTokenColumn,
 205                                 unsigned EscapedNewlineColumn);
 206   void appendIndentText(std::string &Text, unsigned IndentLevel,
 207                         unsigned Spaces, unsigned WhitespaceStartColumn);
 208
 209   SmallVector<Change, 16> Changes;
 210   const SourceManager &SourceMgr;
 211   tooling::Replacements Replaces;
 212   const FormatStyle &Style;
 213   bool UseCRLF;
 214 };
 215
 216 } // namespace format
 217 } // namespace clang
 218
 219 #endif