| //===--- ContinuationIndenter.h - Format C++ code ---------------*- C++ -*-===// | |
| // | |
| // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. | |
| // See https://llvm.org/LICENSE.txt for license information. | |
| // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception | |
| // | |
| //===----------------------------------------------------------------------===// | |
| /// | |
| /// \file | |
| /// This file implements an indenter that manages the indentation of | |
| /// continuations. | |
| /// | |
| //===----------------------------------------------------------------------===// | |
| #ifndef LLVM_CLANG_LIB_FORMAT_CONTINUATIONINDENTER_H | |
| #define LLVM_CLANG_LIB_FORMAT_CONTINUATIONINDENTER_H | |
| #include "Encoding.h" | |
| #include "FormatToken.h" | |
| namespace clang { | |
| class SourceManager; | |
| namespace format { | |
| class AnnotatedLine; | |
| class BreakableToken; | |
| struct FormatToken; | |
| struct LineState; | |
| struct ParenState; | |
| struct RawStringFormatStyleManager; | |
| class WhitespaceManager; | |
| struct RawStringFormatStyleManager { | |
| llvm::StringMap<FormatStyle> DelimiterStyle; | |
| llvm::StringMap<FormatStyle> EnclosingFunctionStyle; | |
| RawStringFormatStyleManager(const FormatStyle &CodeStyle); | |
| std::optional<FormatStyle> getDelimiterStyle(StringRef Delimiter) const; | |
| std::optional<FormatStyle> | |
| getEnclosingFunctionStyle(StringRef EnclosingFunction) const; | |
| }; | |
| /// Represents the spaces at the start of a line, keeping track of what the | |
| /// spaces are for. | |
| struct IndentationAndAlignment { | |
| unsigned Total; | |
| /// The column that the position of the start of the line is calculated | |
| /// from. It can be more than Total. | |
| unsigned IndentedFrom; | |
| /// Add spaces for right-justifying the token. The IndentedFrom field does not | |
| /// change. | |
| /// | |
| /// This example in Objective-C shows why the field should not change. The | |
| /// token `xx` is right-justified with this method to align the `:` | |
| /// symbols. The `:` symbols should remain aligned through the step that | |
| /// aligns assignments. That step uses the IndentedFrom field to tell what | |
| /// lines to move. Not changing the field in this method ensures that the 2 | |
| /// lines move together. | |
| /// | |
| /// [x // | |
| /// xxxx:0 | |
| /// xx:0]; | |
| IndentationAndAlignment addPadding(unsigned Spaces) const; | |
| /// Adding indentation is more common than padding. So the operator does that. | |
| IndentationAndAlignment operator+(unsigned Spaces) const; | |
| IndentationAndAlignment operator-(unsigned Spaces) const; | |
| IndentationAndAlignment &operator+=(unsigned Spaces); | |
| IndentationAndAlignment(unsigned Total, unsigned IndentedFrom); | |
| IndentationAndAlignment(unsigned Spaces); | |
| bool operator<(const IndentationAndAlignment &Other) const; | |
| }; | |
| class ContinuationIndenter { | |
| public: | |
| /// Constructs a \c ContinuationIndenter to format \p Line starting in | |
| /// column \p FirstIndent. | |
| ContinuationIndenter(const FormatStyle &Style, | |
| const AdditionalKeywords &Keywords, | |
| const SourceManager &SourceMgr, | |
| WhitespaceManager &Whitespaces, | |
| encoding::Encoding Encoding, | |
| bool BinPackInconclusiveFunctions); | |
| /// Get the initial state, i.e. the state after placing \p Line's | |
| /// first token at \p FirstIndent. When reformatting a fragment of code, as in | |
| /// the case of formatting inside raw string literals, \p FirstStartColumn is | |
| /// the column at which the state of the parent formatter is. | |
| LineState getInitialState(unsigned FirstIndent, unsigned FirstStartColumn, | |
| const AnnotatedLine *Line, bool DryRun); | |
| // FIXME: canBreak and mustBreak aren't strictly indentation-related. Find a | |
| // better home. | |
| /// Returns \c true, if a line break after \p State is allowed. | |
| bool canBreak(const LineState &State); | |
| /// Returns \c true, if a line break after \p State is mandatory. | |
| bool mustBreak(const LineState &State); | |
| /// Appends the next token to \p State and updates information | |
| /// necessary for indentation. | |
| /// | |
| /// Puts the token on the current line if \p Newline is \c false and adds a | |
| /// line break and necessary indentation otherwise. | |
| /// | |
| /// If \p DryRun is \c false, also creates and stores the required | |
| /// \c Replacement. | |
| unsigned addTokenToState(LineState &State, bool Newline, bool DryRun, | |
| unsigned ExtraSpaces = 0); | |
| /// Get the column limit for this line. This is the style's column | |
| /// limit, potentially reduced for preprocessor definitions. | |
| unsigned getColumnLimit(const LineState &State) const; | |
| private: | |
| /// Mark the next token as consumed in \p State and modify its stacks | |
| /// accordingly. | |
| unsigned moveStateToNextToken(LineState &State, bool DryRun, bool Newline); | |
| /// Update 'State' according to the next token's fake left parentheses. | |
| void moveStatePastFakeLParens(LineState &State, bool Newline); | |
| /// Update 'State' according to the next token's fake r_parens. | |
| void moveStatePastFakeRParens(LineState &State); | |
| /// Update 'State' according to the next token being one of "(<{[". | |
| void moveStatePastScopeOpener(LineState &State, bool Newline); | |
| /// Update 'State' according to the next token being one of ")>}]". | |
| void moveStatePastScopeCloser(LineState &State); | |
| /// Update 'State' with the next token opening a nested block. | |
| void moveStateToNewBlock(LineState &State, bool NewLine); | |
| /// Reformats a raw string literal. | |
| /// | |
| /// \returns An extra penalty induced by reformatting the token. | |
| unsigned reformatRawStringLiteral(const FormatToken &Current, | |
| LineState &State, | |
| const FormatStyle &RawStringStyle, | |
| bool DryRun, bool Newline); | |
| /// If the current token is at the end of the current line, handle | |
| /// the transition to the next line. | |
| unsigned handleEndOfLine(const FormatToken &Current, LineState &State, | |
| bool DryRun, bool AllowBreak, bool Newline); | |
| /// If \p Current is a raw string that is configured to be reformatted, | |
| /// return the style to be used. | |
| std::optional<FormatStyle> getRawStringStyle(const FormatToken &Current, | |
| const LineState &State); | |
| /// If the current token sticks out over the end of the line, break | |
| /// it if possible. | |
| /// | |
| /// \returns A pair (penalty, exceeded), where penalty is the extra penalty | |
| /// when tokens are broken or lines exceed the column limit, and exceeded | |
| /// indicates whether the algorithm purposefully left lines exceeding the | |
| /// column limit. | |
| /// | |
| /// The returned penalty will cover the cost of the additional line breaks | |
| /// and column limit violation in all lines except for the last one. The | |
| /// penalty for the column limit violation in the last line (and in single | |
| /// line tokens) is handled in \c addNextStateToQueue. | |
| /// | |
| /// \p Strict indicates whether reflowing is allowed to leave characters | |
| /// protruding the column limit; if true, lines will be split strictly within | |
| /// the column limit where possible; if false, words are allowed to protrude | |
| /// over the column limit as long as the penalty is less than the penalty | |
| /// of a break. | |
| std::pair<unsigned, bool> breakProtrudingToken(const FormatToken &Current, | |
| LineState &State, | |
| bool AllowBreak, bool DryRun, | |
| bool Strict); | |
| /// Returns the \c BreakableToken starting at \p Current, or nullptr | |
| /// if the current token cannot be broken. | |
| std::unique_ptr<BreakableToken> | |
| createBreakableToken(const FormatToken &Current, LineState &State, | |
| bool AllowBreak); | |
| /// Appends the next token to \p State and updates information | |
| /// necessary for indentation. | |
| /// | |
| /// Puts the token on the current line. | |
| /// | |
| /// If \p DryRun is \c false, also creates and stores the required | |
| /// \c Replacement. | |
| void addTokenOnCurrentLine(LineState &State, bool DryRun, | |
| unsigned ExtraSpaces); | |
| /// Appends the next token to \p State and updates information | |
| /// necessary for indentation. | |
| /// | |
| /// Adds a line break and necessary indentation. | |
| /// | |
| /// If \p DryRun is \c false, also creates and stores the required | |
| /// \c Replacement. | |
| unsigned addTokenOnNewLine(LineState &State, bool DryRun); | |
| /// Calculate the new column for a line wrap before the next token. | |
| IndentationAndAlignment getNewLineColumn(const LineState &State); | |
| /// Adds a multiline token to the \p State. | |
| /// | |
| /// \returns Extra penalty for the first line of the literal: last line is | |
| /// handled in \c addNextStateToQueue, and the penalty for other lines doesn't | |
| /// matter, as we don't change them. | |
| unsigned addMultilineToken(const FormatToken &Current, LineState &State); | |
| /// Returns \c true if the next token starts a multiline string | |
| /// literal. | |
| /// | |
| /// This includes implicitly concatenated strings, strings that will be broken | |
| /// by clang-format and string literals with escaped newlines. | |
| bool nextIsMultilineString(const LineState &State); | |
| FormatStyle Style; | |
| const AdditionalKeywords &Keywords; | |
| const SourceManager &SourceMgr; | |
| WhitespaceManager &Whitespaces; | |
| encoding::Encoding Encoding; | |
| bool BinPackInconclusiveFunctions; | |
| llvm::Regex CommentPragmasRegex; | |
| const RawStringFormatStyleManager RawStringFormats; | |
| }; | |
| struct ParenState { | |
| ParenState(const FormatToken *Tok, IndentationAndAlignment Indent, | |
| unsigned LastSpace, bool AvoidBinPacking, bool NoLineBreak) | |
| : Tok(Tok), Indent(Indent), AlignedTo(nullptr), LastSpace(LastSpace), | |
| NestedBlockIndent(Indent.Total), BreakBeforeClosingBrace(false), | |
| BreakBeforeClosingParen(false), BreakBeforeClosingAngle(false), | |
| AvoidBinPacking(AvoidBinPacking), BreakBeforeParameter(false), | |
| NoLineBreak(NoLineBreak), NoLineBreakInOperand(false), | |
| LastOperatorWrapped(true), ContainsLineBreak(false), | |
| ContainsUnwrappedBuilder(false), AlignColons(true), | |
| ObjCSelectorNameFound(false), HasMultipleNestedBlocks(false), | |
| NestedBlockInlined(false), IsInsideObjCArrayLiteral(false), | |
| IsCSharpGenericTypeConstraint(false), IsChainedConditional(false), | |
| IsWrappedConditional(false), UnindentOperator(false) {} | |
| /// The token opening this parenthesis level, or nullptr if this level is | |
| /// opened by fake parenthesis. | |
| /// | |
| /// Not considered for memoization as it will always have the same value at | |
| /// the same token. | |
| const FormatToken *Tok; | |
| /// The position to which a specific parenthesis level needs to be | |
| /// indented. | |
| IndentationAndAlignment Indent; | |
| /// The token in one of the previous lines this state wants to align to. | |
| const FormatToken *AlignedTo; | |
| /// The position of the last space on each level. | |
| /// | |
| /// Used e.g. to break like: | |
| /// functionCall(Parameter, otherCall( | |
| /// OtherParameter)); | |
| unsigned LastSpace; | |
| /// If a block relative to this parenthesis level gets wrapped, indent | |
| /// it this much. | |
| unsigned NestedBlockIndent; | |
| /// The position the first "<<" operator encountered on each level. | |
| /// | |
| /// Used to align "<<" operators. 0 if no such operator has been encountered | |
| /// on a level. | |
| unsigned FirstLessLess = 0; | |
| /// The column of a \c ? in a conditional expression; | |
| unsigned QuestionColumn = 0; | |
| /// The position of the colon in an ObjC method declaration/call. | |
| unsigned ColonPos = 0; | |
| /// The start of the most recent function in a builder-type call. | |
| unsigned StartOfFunctionCall = 0; | |
| /// Contains the start of array subscript expressions, so that they | |
| /// can be aligned. | |
| unsigned StartOfArraySubscripts = 0; | |
| /// If a nested name specifier was broken over multiple lines, this | |
| /// contains the start column of the second line. Otherwise 0. | |
| unsigned NestedNameSpecifierContinuation = 0; | |
| /// If a call expression was broken over multiple lines, this | |
| /// contains the start column of the second line. Otherwise 0. | |
| unsigned CallContinuation = 0; | |
| /// The column of the first variable name in a variable declaration. | |
| /// | |
| /// Used to align further variables if necessary. | |
| unsigned VariablePos = 0; | |
| /// Whether a newline needs to be inserted before the block's closing | |
| /// brace. | |
| /// | |
| /// We only want to insert a newline before the closing brace if there also | |
| /// was a newline after the beginning left brace. | |
| bool BreakBeforeClosingBrace : 1; | |
| /// Whether a newline needs to be inserted before the block's closing | |
| /// paren. | |
| /// | |
| /// We only want to insert a newline before the closing paren if there also | |
| /// was a newline after the beginning left paren. | |
| bool BreakBeforeClosingParen : 1; | |
| /// Whether a newline needs to be inserted before a closing angle `>`. | |
| bool BreakBeforeClosingAngle : 1; | |
| /// Avoid bin packing, i.e. multiple parameters/elements on multiple | |
| /// lines, in this context. | |
| bool AvoidBinPacking : 1; | |
| /// Break after the next comma (or all the commas in this context if | |
| /// \c AvoidBinPacking is \c true). | |
| bool BreakBeforeParameter : 1; | |
| /// Line breaking in this context would break a formatting rule. | |
| bool NoLineBreak : 1; | |
| /// Same as \c NoLineBreak, but is restricted until the end of the | |
| /// operand (including the next ","). | |
| bool NoLineBreakInOperand : 1; | |
| /// True if the last binary operator on this level was wrapped to the | |
| /// next line. | |
| bool LastOperatorWrapped : 1; | |
| /// \c true if this \c ParenState already contains a line-break. | |
| /// | |
| /// The first line break in a certain \c ParenState causes extra penalty so | |
| /// that clang-format prefers similar breaks, i.e. breaks in the same | |
| /// parenthesis. | |
| bool ContainsLineBreak : 1; | |
| /// \c true if this \c ParenState contains multiple segments of a | |
| /// builder-type call on one line. | |
| bool ContainsUnwrappedBuilder : 1; | |
| /// \c true if the colons of the curren ObjC method expression should | |
| /// be aligned. | |
| /// | |
| /// Not considered for memoization as it will always have the same value at | |
| /// the same token. | |
| bool AlignColons : 1; | |
| /// \c true if at least one selector name was found in the current | |
| /// ObjC method expression. | |
| /// | |
| /// Not considered for memoization as it will always have the same value at | |
| /// the same token. | |
| bool ObjCSelectorNameFound : 1; | |
| /// \c true if there are multiple nested blocks inside these parens. | |
| /// | |
| /// Not considered for memoization as it will always have the same value at | |
| /// the same token. | |
| bool HasMultipleNestedBlocks : 1; | |
| /// The start of a nested block (e.g. lambda introducer in C++ or | |
| /// "function" in JavaScript) is not wrapped to a new line. | |
| bool NestedBlockInlined : 1; | |
| /// \c true if the current \c ParenState represents an Objective-C | |
| /// array literal. | |
| bool IsInsideObjCArrayLiteral : 1; | |
| bool IsCSharpGenericTypeConstraint : 1; | |
| /// true if the current \c ParenState represents the false branch of a chained | |
| /// conditional expression (e.g. else-if) | |
| bool IsChainedConditional : 1; | |
| /// true if there conditionnal was wrapped on the first operator (the question | |
| /// mark) | |
| bool IsWrappedConditional : 1; | |
| /// Indicates the indent should be reduced by the length of the operator. | |
| bool UnindentOperator : 1; | |
| bool operator<(const ParenState &Other) const { | |
| if (Indent.Total != Other.Indent.Total) | |
| return Indent.Total < Other.Indent.Total; | |
| if (LastSpace != Other.LastSpace) | |
| return LastSpace < Other.LastSpace; | |
| if (NestedBlockIndent != Other.NestedBlockIndent) | |
| return NestedBlockIndent < Other.NestedBlockIndent; | |
| if (FirstLessLess != Other.FirstLessLess) | |
| return FirstLessLess < Other.FirstLessLess; | |
| if (AlignedTo != Other.AlignedTo) | |
| return AlignedTo < Other.AlignedTo; | |
| if (BreakBeforeClosingBrace != Other.BreakBeforeClosingBrace) | |
| return BreakBeforeClosingBrace; | |
| if (BreakBeforeClosingParen != Other.BreakBeforeClosingParen) | |
| return BreakBeforeClosingParen; | |
| if (BreakBeforeClosingAngle != Other.BreakBeforeClosingAngle) | |
| return BreakBeforeClosingAngle; | |
| if (QuestionColumn != Other.QuestionColumn) | |
| return QuestionColumn < Other.QuestionColumn; | |
| if (AvoidBinPacking != Other.AvoidBinPacking) | |
| return AvoidBinPacking; | |
| if (BreakBeforeParameter != Other.BreakBeforeParameter) | |
| return BreakBeforeParameter; | |
| if (NoLineBreak != Other.NoLineBreak) | |
| return NoLineBreak; | |
| if (LastOperatorWrapped != Other.LastOperatorWrapped) | |
| return LastOperatorWrapped; | |
| if (ColonPos != Other.ColonPos) | |
| return ColonPos < Other.ColonPos; | |
| if (StartOfFunctionCall != Other.StartOfFunctionCall) | |
| return StartOfFunctionCall < Other.StartOfFunctionCall; | |
| if (StartOfArraySubscripts != Other.StartOfArraySubscripts) | |
| return StartOfArraySubscripts < Other.StartOfArraySubscripts; | |
| if (CallContinuation != Other.CallContinuation) | |
| return CallContinuation < Other.CallContinuation; | |
| if (VariablePos != Other.VariablePos) | |
| return VariablePos < Other.VariablePos; | |
| if (ContainsLineBreak != Other.ContainsLineBreak) | |
| return ContainsLineBreak; | |
| if (ContainsUnwrappedBuilder != Other.ContainsUnwrappedBuilder) | |
| return ContainsUnwrappedBuilder; | |
| if (NestedBlockInlined != Other.NestedBlockInlined) | |
| return NestedBlockInlined; | |
| if (IsCSharpGenericTypeConstraint != Other.IsCSharpGenericTypeConstraint) | |
| return IsCSharpGenericTypeConstraint; | |
| if (IsChainedConditional != Other.IsChainedConditional) | |
| return IsChainedConditional; | |
| if (IsWrappedConditional != Other.IsWrappedConditional) | |
| return IsWrappedConditional; | |
| if (UnindentOperator != Other.UnindentOperator) | |
| return UnindentOperator; | |
| return Indent < Other.Indent; | |
| } | |
| }; | |
| /// The current state when indenting a unwrapped line. | |
| /// | |
| /// As the indenting tries different combinations this is copied by value. | |
| struct LineState { | |
| /// The number of used columns in the current line. | |
| unsigned Column; | |
| /// The token that needs to be next formatted. | |
| FormatToken *NextToken; | |
| /// \c true if \p NextToken should not continue this line. | |
| bool NoContinuation; | |
| /// The \c NestingLevel at the start of this line. | |
| unsigned StartOfLineLevel; | |
| /// The lowest \c NestingLevel on the current line. | |
| unsigned LowestLevelOnLine; | |
| /// The start column of the string literal, if we're in a string | |
| /// literal sequence, 0 otherwise. | |
| unsigned StartOfStringLiteral; | |
| /// Disallow line breaks for this line. | |
| bool NoLineBreak; | |
| /// A stack keeping track of properties applying to parenthesis | |
| /// levels. | |
| SmallVector<ParenState> Stack; | |
| /// Ignore the stack of \c ParenStates for state comparison. | |
| /// | |
| /// In long and deeply nested unwrapped lines, the current algorithm can | |
| /// be insufficient for finding the best formatting with a reasonable amount | |
| /// of time and memory. Setting this flag will effectively lead to the | |
| /// algorithm not analyzing some combinations. However, these combinations | |
| /// rarely contain the optimal solution: In short, accepting a higher | |
| /// penalty early would need to lead to different values in the \c | |
| /// ParenState stack (in an otherwise identical state) and these different | |
| /// values would need to lead to a significant amount of avoided penalty | |
| /// later. | |
| /// | |
| /// FIXME: Come up with a better algorithm instead. | |
| bool IgnoreStackForComparison; | |
| /// The indent of the first token. | |
| unsigned FirstIndent; | |
| /// The line that is being formatted. | |
| /// | |
| /// Does not need to be considered for memoization because it doesn't change. | |
| const AnnotatedLine *Line; | |
| /// Comparison operator to be able to used \c LineState in \c map. | |
| bool operator<(const LineState &Other) const { | |
| if (NextToken != Other.NextToken) | |
| return NextToken < Other.NextToken; | |
| if (Column != Other.Column) | |
| return Column < Other.Column; | |
| if (NoContinuation != Other.NoContinuation) | |
| return NoContinuation; | |
| if (StartOfLineLevel != Other.StartOfLineLevel) | |
| return StartOfLineLevel < Other.StartOfLineLevel; | |
| if (LowestLevelOnLine != Other.LowestLevelOnLine) | |
| return LowestLevelOnLine < Other.LowestLevelOnLine; | |
| if (StartOfStringLiteral != Other.StartOfStringLiteral) | |
| return StartOfStringLiteral < Other.StartOfStringLiteral; | |
| if (IgnoreStackForComparison || Other.IgnoreStackForComparison) | |
| return false; | |
| return Stack < Other.Stack; | |
| } | |
| }; | |
| } // end namespace format | |
| } // end namespace clang | |
| #endif |