class BreakableLineCommentSection

Declaration

class BreakableLineCommentSection : public BreakableComment { /* full declaration omitted */ };

Description

Base class for tokens / ranges of tokens that can allow breaking within the tokens - for example, to avoid whitespace beyond the column limit, or to reflow text. Generally, a breakable token consists of logical lines, addressed by a line index. For example, in a sequence of line comments, each line comment is its own logical line; similarly, for a block comment, each line in the block comment is on its own logical line. There are two methods to compute the layout of the token: - getRangeLength measures the number of columns needed for a range of text within a logical line, and - getContentStartColumn returns the start column at which we want the content of a logical line to start (potentially after introducing a line break). The mechanism to adapt the layout of the breakable token is organised around the concept of a \c Split, which is a whitespace range that signifies a position of the content of a token where a reformatting might be done. Operating with splits is divided into two operations: - getSplit, for finding a split starting at a position, - insertBreak, for executing the split using a whitespace manager. There is a pair of operations that are used to compress a long whitespace range with a single space if that will bring the line length under the column limit: - getLineLengthAfterCompression, for calculating the size in columns of the line after a whitespace range has been compressed, and - compressWhitespace, for executing the whitespace compression using a whitespace manager; note that the compressed whitespace may be in the middle of the original line and of the reformatted line. For tokens where the whitespace before each line needs to be also reformatted, for example for tokens supporting reflow, there are analogous operations that might be executed before the main line breaking occurs: - getReflowSplit, for finding a split such that the content preceding it needs to be specially reflown, - reflow, for executing the split using a whitespace manager, - introducesBreakBefore, for checking if reformatting the beginning of the content introduces a line break before it, - adaptStartOfLine, for executing the reflow using a whitespace manager. For tokens that require the whitespace after the last line to be reformatted, for example in multiline jsdoc comments that require the trailing '*/' to be on a line of itself, there are analogous operations that might be executed after the last line has been reformatted: - getSplitAfterLastLine, for finding a split after the last line that needs to be reflown, - replaceWhitespaceAfterLastLine, for executing the reflow using a whitespace manager.

Declared at: clang/lib/Format/BreakableToken.h:436

Inherits from: BreakableComment

Member Variables

private SmallVector<llvm::StringRef, 16> OriginalPrefix
private SmallVector<std::string, 16> Prefix
Prefix[i] + SpacesToAdd[i] contains the intended leading "//" with trailing spaces to account for the indentation of content within the comment at line i after formatting. It can be different than the original prefix. When the original line starts like this: //content Then the OriginalPrefix[i] is "//", but the Prefix[i] is "// " in the LLVM style. When the line starts like: // content And we want to remove the spaces the OriginalPrefix[i] is "// " and Prefix[i] is "//".
private SmallVector<int, 16> PrefixSpaceChange
How many spaces are added or removed from the OriginalPrefix to form Prefix.
private clang::format::FormatToken* LastLineTok = nullptr
The distinction is because if the token of the last line of this breakable token is distinct from the initial token, this breakable token owns the whitespace before the token of the last line, and the whitespace manager must be able to modify it.

Inherited from BreakableComment:

protected Lines
protected Content
protected Tokens
protected ContentColumn
protected StartColumn
protected ReflowPrefix = " "

Inherited from BreakableToken:

protected Tok
protected InPPDirective
protected Encoding
protected Style

Method Overview

  • public BreakableLineCommentSection(const clang::format::FormatToken & Token, unsigned int StartColumn, bool InPPDirective, encoding::Encoding Encoding, const clang::format::FormatStyle & Style)
  • public void adaptStartOfLine(unsigned int LineIndex, clang::format::WhitespaceManager & Whitespaces) const
  • public unsigned int getContentStartColumn(unsigned int LineIndex, bool Break) const
  • public unsigned int getRangeLength(unsigned int LineIndex, unsigned int Offset, StringRef::size_type Length, unsigned int StartColumn) const
  • public clang::format::BreakableToken::Split getReflowSplit(unsigned int LineIndex, const llvm::Regex & CommentPragmasRegex) const
  • public void insertBreak(unsigned int LineIndex, unsigned int TailOffset, clang::format::BreakableToken::Split Split, unsigned int ContentIndent, clang::format::WhitespaceManager & Whitespaces) const
  • public bool mayReflow(unsigned int LineIndex, const llvm::Regex & CommentPragmasRegex) const
  • public void reflow(unsigned int LineIndex, clang::format::WhitespaceManager & Whitespaces) const
  • public void updateNextToken(clang::format::LineState & State) const

Inherited from BreakableComment:

Inherited from BreakableToken:

Methods

BreakableLineCommentSection(
    const clang::format::FormatToken& Token,
    unsigned int StartColumn,
    bool InPPDirective,
    encoding::Encoding Encoding,
    const clang::format::FormatStyle& Style)

Declared at: clang/lib/Format/BreakableToken.h:438

Parameters

const clang::format::FormatToken& Token
unsigned int StartColumn
bool InPPDirective
encoding::Encoding Encoding
const clang::format::FormatStyle& Style

void adaptStartOfLine(
    unsigned int LineIndex,
    clang::format::WhitespaceManager& Whitespaces)
    const

Description

Replaces the whitespace between \p LineIndex-1 and \p LineIndex.

Declared at: clang/lib/Format/BreakableToken.h:453

Parameters

unsigned int LineIndex
clang::format::WhitespaceManager& Whitespaces

unsigned int getContentStartColumn(
    unsigned int LineIndex,
    bool Break) const

Description

Returns the column at which content in line \p LineIndex starts, assuming no reflow. If \p Break is true, returns the column at which the line should start after the line break. If \p Break is false, returns the column at which the line itself will start.

Declared at: clang/lib/Format/BreakableToken.h:445

Parameters

unsigned int LineIndex
bool Break

unsigned int getRangeLength(
    unsigned int LineIndex,
    unsigned int Offset,
    StringRef::size_type Length,
    unsigned int StartColumn) const

Description

Returns the number of columns required to format the text in the byte range [\p Offset, \p Offset \c + \p Length). \p Offset is the byte offset from the start of the content of the line at \p LineIndex. \p StartColumn is the column at which the text starts in the formatted file, needed to compute tab stops correctly.

Declared at: clang/lib/Format/BreakableToken.h:442

Parameters

unsigned int LineIndex
unsigned int Offset
StringRef::size_type Length
unsigned int StartColumn

clang::format::BreakableToken::Split
getReflowSplit(
    unsigned int LineIndex,
    const llvm::Regex& CommentPragmasRegex) const

Description

Returns a whitespace range (offset, length) of the content at \p LineIndex such that the content of that line is reflown to the end of the previous one. Returning (StringRef::npos, 0) indicates reflowing is not possible. The range will include any whitespace preceding the specified line's content. If the split is not contained within one token, for example when reflowing line comments, returns (0, <length >).

Declared at: clang/lib/Format/BreakableToken.h:449

Parameters

unsigned int LineIndex
const llvm::Regex& CommentPragmasRegex

void insertBreak(
    unsigned int LineIndex,
    unsigned int TailOffset,
    clang::format::BreakableToken::Split Split,
    unsigned int ContentIndent,
    clang::format::WhitespaceManager& Whitespaces)
    const

Description

Emits the previously retrieved \p Split via \p Whitespaces.

Declared at: clang/lib/Format/BreakableToken.h:446

Parameters

unsigned int LineIndex
unsigned int TailOffset
clang::format::BreakableToken::Split Split
unsigned int ContentIndent
clang::format::WhitespaceManager& Whitespaces

bool mayReflow(
    unsigned int LineIndex,
    const llvm::Regex& CommentPragmasRegex) const

Declared at: clang/lib/Format/BreakableToken.h:456

Parameters

unsigned int LineIndex
const llvm::Regex& CommentPragmasRegex

void reflow(unsigned int LineIndex,
            clang::format::WhitespaceManager&
                Whitespaces) const

Description

Reflows the current line into the end of the previous one.

Declared at: clang/lib/Format/BreakableToken.h:451

Parameters

unsigned int LineIndex
clang::format::WhitespaceManager& Whitespaces

void updateNextToken(
    clang::format::LineState& State) const

Description

Updates the next token of \p State to the next token after this one. This can be used when this token manages a set of underlying tokens as a unit and is responsible for the formatting of the them.

Declared at: clang/lib/Format/BreakableToken.h:455

Parameters

clang::format::LineState& State