contrib/llvm/tools/clang/include/clang/Format/Format.h

   1 //===--- Format.h - Format C++ code -----------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 ///
  10 /// \file
  11 /// Various functions to configurably format source code.
  12 ///
  13 //===----------------------------------------------------------------------===//
  14
  15 #ifndef LLVM_CLANG_FORMAT_FORMAT_H
  16 #define LLVM_CLANG_FORMAT_FORMAT_H
  17
  18 #include "clang/Frontend/FrontendAction.h"
  19 #include "clang/Tooling/Refactoring.h"
  20 #include <system_error>
  21
  22 namespace clang {
  23
  24 class Lexer;
  25 class SourceManager;
  26 class DiagnosticConsumer;
  27
  28 namespace format {
  29
  30 enum class ParseError { Success = 0, Error, Unsuitable };
  31 class ParseErrorCategory final : public std::error_category {
  32 public:
  33   const char *name() const LLVM_NOEXCEPT override;
  34   std::string message(int EV) const override;
  35 };
  36 const std::error_category &getParseCategory();
  37 std::error_code make_error_code(ParseError e);
  38
  39 /// \brief The \c FormatStyle is used to configure the formatting to follow
  40 /// specific guidelines.
  41 struct FormatStyle {
  42   /// \brief Supported languages. When stored in a configuration file, specifies
  43   /// the language, that the configuration targets. When passed to the
  44   /// reformat() function, enables syntax features specific to the language.
  45   enum LanguageKind {
  46     /// Do not use.
  47     LK_None,
  48     /// Should be used for C, C++, ObjectiveC, ObjectiveC++.
  49     LK_Cpp,
  50     /// Should be used for JavaScript.
  51     LK_JavaScript,
  52     /// Should be used for Protocol Buffers
  53     /// (https://developers.google.com/protocol-buffers/).
  54     LK_Proto
  55   };
  56
  57   /// \brief Language, this format style is targeted at.
  58   LanguageKind Language;
  59
  60   /// \brief The column limit.
  61   ///
  62   /// A column limit of \c 0 means that there is no column limit. In this case,
  63   /// clang-format will respect the input's line breaking decisions within
  64   /// statements unless they contradict other rules.
  65   unsigned ColumnLimit;
  66
  67   /// \brief The maximum number of consecutive empty lines to keep.
  68   unsigned MaxEmptyLinesToKeep;
  69
  70   /// \brief If true, empty lines at the start of blocks are kept.
  71   bool KeepEmptyLinesAtTheStartOfBlocks;
  72
  73   /// \brief The penalty for each line break introduced inside a comment.
  74   unsigned PenaltyBreakComment;
  75
  76   /// \brief The penalty for each line break introduced inside a string literal.
  77   unsigned PenaltyBreakString;
  78
  79   /// \brief The penalty for each character outside of the column limit.
  80   unsigned PenaltyExcessCharacter;
  81
  82   /// \brief The penalty for breaking before the first \c <<.
  83   unsigned PenaltyBreakFirstLessLess;
  84
  85   /// \brief The penalty for breaking a function call after "call(".
  86   unsigned PenaltyBreakBeforeFirstCallParameter;
  87
  88   /// \brief The & and * alignment style.
  89   enum PointerAlignmentStyle {
  90     /// Align pointer to the left.
  91     PAS_Left,
  92     /// Align pointer to the right.
  93     PAS_Right,
  94     /// Align pointer in the middle.
  95     PAS_Middle
  96   };
  97
  98   /// Pointer and reference alignment style.
  99   PointerAlignmentStyle PointerAlignment;
 100
 101   /// \brief If \c true, analyze the formatted file for the most common
 102   /// alignment of & and *. \c PointerAlignment is then used only as fallback.
 103   bool DerivePointerAlignment;
 104
 105   /// \brief The extra indent or outdent of access modifiers, e.g. \c public:.
 106   int AccessModifierOffset;
 107
 108   /// \brief Supported language standards.
 109   enum LanguageStandard {
 110     /// Use C++03-compatible syntax.
 111     LS_Cpp03,
 112     /// Use features of C++11 (e.g. \c A<A<int>> instead of
 113     /// <tt>A<A<int> ></tt>).
 114     LS_Cpp11,
 115     /// Automatic detection based on the input.
 116     LS_Auto
 117   };
 118
 119   /// \brief Format compatible with this standard, e.g. use
 120   /// <tt>A<A<int> ></tt> instead of \c A<A<int>> for LS_Cpp03.
 121   LanguageStandard Standard;
 122
 123   /// \brief Indent case labels one level from the switch statement.
 124   ///
 125   /// When \c false, use the same indentation level as for the switch statement.
 126   /// Switch statement body is always indented one level more than case labels.
 127   bool IndentCaseLabels;
 128
 129   /// \brief Indent if a function definition or declaration is wrapped after the
 130   /// type.
 131   bool IndentWrappedFunctionNames;
 132
 133   /// \brief Different ways to indent namespace contents.
 134   enum NamespaceIndentationKind {
 135     /// Don't indent in namespaces.
 136     NI_None,
 137     /// Indent only in inner namespaces (nested in other namespaces).
 138     NI_Inner,
 139     /// Indent in all namespaces.
 140     NI_All
 141   };
 142
 143   /// \brief The indentation used for namespaces.
 144   NamespaceIndentationKind NamespaceIndentation;
 145
 146   /// \brief The number of spaces before trailing line comments
 147   /// (\c // - comments).
 148   ///
 149   /// This does not affect trailing block comments (\c /**/ - comments) as those
 150   /// commonly have different usage patterns and a number of special cases.
 151   unsigned SpacesBeforeTrailingComments;
 152
 153   /// \brief If \c false, a function call's or function definition's parameters
 154   /// will either all be on the same line or will have one line each.
 155   bool BinPackParameters;
 156
 157   /// \brief If \c true, clang-format detects whether function calls and
 158   /// definitions are formatted with one parameter per line.
 159   ///
 160   /// Each call can be bin-packed, one-per-line or inconclusive. If it is
 161   /// inconclusive, e.g. completely on one line, but a decision needs to be
 162   /// made, clang-format analyzes whether there are other bin-packed cases in
 163   /// the input file and act accordingly.
 164   ///
 165   /// NOTE: This is an experimental flag, that might go away or be renamed. Do
 166   /// not use this in config files, etc. Use at your own risk.
 167   bool ExperimentalAutoDetectBinPacking;
 168
 169   /// \brief Allow putting all parameters of a function declaration onto
 170   /// the next line even if \c BinPackParameters is \c false.
 171   bool AllowAllParametersOfDeclarationOnNextLine;
 172
 173   /// \brief Penalty for putting the return type of a function onto its own
 174   /// line.
 175   unsigned PenaltyReturnTypeOnItsOwnLine;
 176
 177   /// \brief If the constructor initializers don't fit on a line, put each
 178   /// initializer on its own line.
 179   bool ConstructorInitializerAllOnOneLineOrOnePerLine;
 180
 181   /// \brief Always break constructor initializers before commas and align
 182   /// the commas with the colon.
 183   bool BreakConstructorInitializersBeforeComma;
 184
 185   /// \brief Allows contracting simple braced statements to a single line.
 186   ///
 187   /// E.g., this allows <tt>if (a) { return; }</tt> to be put on a single line.
 188   bool AllowShortBlocksOnASingleLine;
 189
 190   /// \brief If \c true, <tt>if (a) return;</tt> can be put on a single
 191   /// line.
 192   bool AllowShortIfStatementsOnASingleLine;
 193
 194   /// \brief If \c true, <tt>while (true) continue;</tt> can be put on a
 195   /// single line.
 196   bool AllowShortLoopsOnASingleLine;
 197
 198   /// \brief Different styles for merging short functions containing at most one
 199   /// statement.
 200   enum ShortFunctionStyle {
 201     /// \brief Never merge functions into a single line.
 202     SFS_None,
 203     /// \brief Only merge functions defined inside a class.
 204     SFS_Inline,
 205     /// \brief Merge all functions fitting on a single line.
 206     SFS_All,
 207   };
 208
 209   /// \brief Dependent on the value, <tt>int f() { return 0; }</tt> can be put
 210   /// on a single line.
 211   ShortFunctionStyle AllowShortFunctionsOnASingleLine;
 212
 213   /// \brief Add a space after \c @property in Objective-C, i.e. use
 214   /// <tt>\@property (readonly)</tt> instead of <tt>\@property(readonly)</tt>.
 215   bool ObjCSpaceAfterProperty;
 216
 217   /// \brief Add a space in front of an Objective-C protocol list, i.e. use
 218   /// <tt>Foo <Protocol></tt> instead of \c Foo<Protocol>.
 219   bool ObjCSpaceBeforeProtocolList;
 220
 221   /// \brief If \c true, aligns trailing comments.
 222   bool AlignTrailingComments;
 223
 224   /// \brief If \c true, aligns escaped newlines as far left as possible.
 225   /// Otherwise puts them into the right-most column.
 226   bool AlignEscapedNewlinesLeft;
 227
 228   /// \brief The number of columns to use for indentation.
 229   unsigned IndentWidth;
 230
 231   /// \brief The number of columns used for tab stops.
 232   unsigned TabWidth;
 233
 234   /// \brief The number of characters to use for indentation of constructor
 235   /// initializer lists.
 236   unsigned ConstructorInitializerIndentWidth;
 237
 238   /// \brief If \c true, always break after the <tt>template<...></tt> of a
 239   /// template declaration.
 240   bool AlwaysBreakTemplateDeclarations;
 241
 242   /// \brief If \c true, always break before multiline string literals.
 243   bool AlwaysBreakBeforeMultilineStrings;
 244
 245   /// \brief Different ways to use tab in formatting.
 246   enum UseTabStyle {
 247     /// Never use tab.
 248     UT_Never,
 249     /// Use tabs only for indentation.
 250     UT_ForIndentation,
 251     /// Use tabs whenever we need to fill whitespace that spans at least from
 252     /// one tab stop to the next one.
 253     UT_Always
 254   };
 255
 256   /// \brief The way to use tab characters in the resulting file.
 257   UseTabStyle UseTab;
 258
 259   /// \brief If \c true, binary operators will be placed after line breaks.
 260   bool BreakBeforeBinaryOperators;
 261
 262   /// \brief If \c true, ternary operators will be placed after line breaks.
 263   bool BreakBeforeTernaryOperators;
 264
 265   /// \brief Different ways to attach braces to their surrounding context.
 266   enum BraceBreakingStyle {
 267     /// Always attach braces to surrounding context.
 268     BS_Attach,
 269     /// Like \c Attach, but break before braces on function, namespace and
 270     /// class definitions.
 271     BS_Linux,
 272     /// Like \c Attach, but break before function definitions.
 273     BS_Stroustrup,
 274     /// Always break before braces.
 275     BS_Allman,
 276     /// Always break before braces and add an extra level of indentation to
 277     /// braces of control statements, not to those of class, function
 278     /// or other definitions.
 279     BS_GNU
 280   };
 281
 282   /// \brief The brace breaking style to use.
 283   BraceBreakingStyle BreakBeforeBraces;
 284
 285   /// \brief If \c true, format braced lists as best suited for C++11 braced
 286   /// lists.
 287   ///
 288   /// Important differences:
 289   /// - No spaces inside the braced list.
 290   /// - No line break before the closing brace.
 291   /// - Indentation with the continuation indent, not with the block indent.
 292   ///
 293   /// Fundamentally, C++11 braced lists are formatted exactly like function
 294   /// calls would be formatted in their place. If the braced list follows a name
 295   /// (e.g. a type or variable name), clang-format formats as if the \c {} were
 296   /// the parentheses of a function call with that name. If there is no name,
 297   /// a zero-length name is assumed.
 298   bool Cpp11BracedListStyle;
 299
 300   /// \brief If \c true, spaces will be inserted after '(' and before ')'.
 301   bool SpacesInParentheses;
 302
 303   /// \brief If \c true, spaces will be inserted after '<' and before '>' in
 304   /// template argument lists
 305   bool SpacesInAngles;
 306
 307   /// \brief If \c true, spaces may be inserted into '()'.
 308   bool SpaceInEmptyParentheses;
 309
 310   /// \brief If \c true, spaces are inserted inside container literals (e.g.
 311   /// ObjC and Javascript array and dict literals).
 312   bool SpacesInContainerLiterals;
 313
 314   /// \brief If \c true, spaces may be inserted into C style casts.
 315   bool SpacesInCStyleCastParentheses;
 316
 317   /// \brief Different ways to put a space before opening parentheses.
 318   enum SpaceBeforeParensOptions {
 319     /// Never put a space before opening parentheses.
 320     SBPO_Never,
 321     /// Put a space before opening parentheses only after control statement
 322     /// keywords (<tt>for/if/while...</tt>).
 323     SBPO_ControlStatements,
 324     /// Always put a space before opening parentheses, except when it's
 325     /// prohibited by the syntax rules (in function-like macro definitions) or
 326     /// when determined by other style rules (after unary operators, opening
 327     /// parentheses, etc.)
 328     SBPO_Always
 329   };
 330
 331   /// \brief Defines in which cases to put a space before opening parentheses.
 332   SpaceBeforeParensOptions SpaceBeforeParens;
 333
 334   /// \brief If \c false, spaces will be removed before assignment operators.
 335   bool SpaceBeforeAssignmentOperators;
 336
 337   /// \brief Indent width for line continuations.
 338   unsigned ContinuationIndentWidth;
 339
 340   /// \brief A regular expression that describes comments with special meaning,
 341   /// which should not be split into lines or otherwise changed.
 342   std::string CommentPragmas;
 343
 344   /// \brief Disables formatting at all.
 345   bool DisableFormat;
 346
 347   /// \brief A vector of macros that should be interpreted as foreach loops
 348   /// instead of as function calls.
 349   ///
 350   /// These are expected to be macros of the form:
 351   /// \code
 352   /// FOREACH(<variable-declaration>, ...)
 353   ///   <loop-body>
 354   /// \endcode
 355   ///
 356   /// For example: BOOST_FOREACH.
 357   std::vector<std::string> ForEachMacros;
 358
 359   bool operator==(const FormatStyle &R) const {
 360     return AccessModifierOffset == R.AccessModifierOffset &&
 361            ConstructorInitializerIndentWidth ==
 362                R.ConstructorInitializerIndentWidth &&
 363            AlignEscapedNewlinesLeft == R.AlignEscapedNewlinesLeft &&
 364            AlignTrailingComments == R.AlignTrailingComments &&
 365            AllowAllParametersOfDeclarationOnNextLine ==
 366                R.AllowAllParametersOfDeclarationOnNextLine &&
 367            AllowShortFunctionsOnASingleLine ==
 368                R.AllowShortFunctionsOnASingleLine &&
 369            AllowShortBlocksOnASingleLine == R.AllowShortBlocksOnASingleLine &&
 370            AllowShortIfStatementsOnASingleLine ==
 371                R.AllowShortIfStatementsOnASingleLine &&
 372            AllowShortLoopsOnASingleLine == R.AllowShortLoopsOnASingleLine &&
 373            AlwaysBreakTemplateDeclarations ==
 374                R.AlwaysBreakTemplateDeclarations &&
 375            AlwaysBreakBeforeMultilineStrings ==
 376                R.AlwaysBreakBeforeMultilineStrings &&
 377            BinPackParameters == R.BinPackParameters &&
 378            BreakBeforeBinaryOperators == R.BreakBeforeBinaryOperators &&
 379            BreakBeforeTernaryOperators == R.BreakBeforeTernaryOperators &&
 380            BreakBeforeBraces == R.BreakBeforeBraces &&
 381            BreakConstructorInitializersBeforeComma ==
 382                R.BreakConstructorInitializersBeforeComma &&
 383            ColumnLimit == R.ColumnLimit &&
 384            ConstructorInitializerAllOnOneLineOrOnePerLine ==
 385                R.ConstructorInitializerAllOnOneLineOrOnePerLine &&
 386            DerivePointerAlignment == R.DerivePointerAlignment &&
 387            ExperimentalAutoDetectBinPacking ==
 388                R.ExperimentalAutoDetectBinPacking &&
 389            IndentCaseLabels == R.IndentCaseLabels &&
 390            IndentWrappedFunctionNames == R.IndentWrappedFunctionNames &&
 391            IndentWidth == R.IndentWidth && Language == R.Language &&
 392            MaxEmptyLinesToKeep == R.MaxEmptyLinesToKeep &&
 393            KeepEmptyLinesAtTheStartOfBlocks ==
 394                R.KeepEmptyLinesAtTheStartOfBlocks &&
 395            NamespaceIndentation == R.NamespaceIndentation &&
 396            ObjCSpaceAfterProperty == R.ObjCSpaceAfterProperty &&
 397            ObjCSpaceBeforeProtocolList == R.ObjCSpaceBeforeProtocolList &&
 398            PenaltyBreakComment == R.PenaltyBreakComment &&
 399            PenaltyBreakFirstLessLess == R.PenaltyBreakFirstLessLess &&
 400            PenaltyBreakString == R.PenaltyBreakString &&
 401            PenaltyExcessCharacter == R.PenaltyExcessCharacter &&
 402            PenaltyReturnTypeOnItsOwnLine == R.PenaltyReturnTypeOnItsOwnLine &&
 403            PointerAlignment == R.PointerAlignment &&
 404            SpacesBeforeTrailingComments == R.SpacesBeforeTrailingComments &&
 405            Cpp11BracedListStyle == R.Cpp11BracedListStyle &&
 406            Standard == R.Standard && TabWidth == R.TabWidth &&
 407            UseTab == R.UseTab && SpacesInParentheses == R.SpacesInParentheses &&
 408            SpacesInAngles == R.SpacesInAngles &&
 409            SpaceInEmptyParentheses == R.SpaceInEmptyParentheses &&
 410            SpacesInContainerLiterals == R.SpacesInContainerLiterals &&
 411            SpacesInCStyleCastParentheses == R.SpacesInCStyleCastParentheses &&
 412            SpaceBeforeParens == R.SpaceBeforeParens &&
 413            SpaceBeforeAssignmentOperators == R.SpaceBeforeAssignmentOperators &&
 414            ContinuationIndentWidth == R.ContinuationIndentWidth &&
 415            CommentPragmas == R.CommentPragmas &&
 416            ForEachMacros == R.ForEachMacros;
 417   }
 418 };
 419
 420 /// \brief Returns a format style complying with the LLVM coding standards:
 421 /// http://llvm.org/docs/CodingStandards.html.
 422 FormatStyle getLLVMStyle();
 423
 424 /// \brief Returns a format style complying with one of Google's style guides:
 425 /// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml.
 426 /// http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml.
 427 /// https://developers.google.com/protocol-buffers/docs/style.
 428 FormatStyle getGoogleStyle(FormatStyle::LanguageKind Language);
 429
 430 /// \brief Returns a format style complying with Chromium's style guide:
 431 /// http://www.chromium.org/developers/coding-style.
 432 FormatStyle getChromiumStyle(FormatStyle::LanguageKind Language);
 433
 434 /// \brief Returns a format style complying with Mozilla's style guide:
 435 /// https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style.
 436 FormatStyle getMozillaStyle();
 437
 438 /// \brief Returns a format style complying with Webkit's style guide:
 439 /// http://www.webkit.org/coding/coding-style.html
 440 FormatStyle getWebKitStyle();
 441
 442 /// \brief Returns a format style complying with GNU Coding Standards:
 443 /// http://www.gnu.org/prep/standards/standards.html
 444 FormatStyle getGNUStyle();
 445
 446 /// \brief Returns style indicating formatting should be not applied at all.
 447 FormatStyle getNoStyle();
 448
 449 /// \brief Gets a predefined style for the specified language by name.
 450 ///
 451 /// Currently supported names: LLVM, Google, Chromium, Mozilla. Names are
 452 /// compared case-insensitively.
 453 ///
 454 /// Returns \c true if the Style has been set.
 455 bool getPredefinedStyle(StringRef Name, FormatStyle::LanguageKind Language,
 456                         FormatStyle *Style);
 457
 458 /// \brief Parse configuration from YAML-formatted text.
 459 ///
 460 /// Style->Language is used to get the base style, if the \c BasedOnStyle
 461 /// option is present.
 462 ///
 463 /// When \c BasedOnStyle is not present, options not present in the YAML
 464 /// document, are retained in \p Style.
 465 std::error_code parseConfiguration(StringRef Text, FormatStyle *Style);
 466
 467 /// \brief Gets configuration in a YAML string.
 468 std::string configurationAsText(const FormatStyle &Style);
 469
 470 /// \brief Reformats the given \p Ranges in the token stream coming out of
 471 /// \c Lex.
 472 ///
 473 /// Each range is extended on either end to its next bigger logic unit, i.e.
 474 /// everything that might influence its formatting or might be influenced by its
 475 /// formatting.
 476 ///
 477 /// Returns the \c Replacements necessary to make all \p Ranges comply with
 478 /// \p Style.
 479 tooling::Replacements reformat(const FormatStyle &Style, Lexer &Lex,
 480                                SourceManager &SourceMgr,
 481                                std::vector<CharSourceRange> Ranges);
 482
 483 /// \brief Reformats the given \p Ranges in \p Code.
 484 ///
 485 /// Otherwise identical to the reformat() function consuming a \c Lexer.
 486 tooling::Replacements reformat(const FormatStyle &Style, StringRef Code,
 487                                std::vector<tooling::Range> Ranges,
 488                                StringRef FileName = "<stdin>");
 489
 490 /// \brief Returns the \c LangOpts that the formatter expects you to set.
 491 ///
 492 /// \param Standard determines lexing mode: LC_Cpp11 and LS_Auto turn on C++11
 493 /// lexing mode, LS_Cpp03 - C++03 mode.
 494 LangOptions getFormattingLangOpts(
 495     FormatStyle::LanguageStandard Standard = FormatStyle::LS_Cpp11);
 496
 497 /// \brief Description to be used for help text for a llvm::cl option for
 498 /// specifying format style. The description is closely related to the operation
 499 /// of getStyle().
 500 extern const char *StyleOptionHelpDescription;
 501
 502 /// \brief Construct a FormatStyle based on \c StyleName.
 503 ///
 504 /// \c StyleName can take several forms:
 505 /// \li "{<key>: <value>, ...}" - Set specic style parameters.
 506 /// \li "<style name>" - One of the style names supported by
 507 /// getPredefinedStyle().
 508 /// \li "file" - Load style configuration from a file called '.clang-format'
 509 /// located in one of the parent directories of \c FileName or the current
 510 /// directory if \c FileName is empty.
 511 ///
 512 /// \param[in] StyleName Style name to interpret according to the description
 513 /// above.
 514 /// \param[in] FileName Path to start search for .clang-format if \c StyleName
 515 /// == "file".
 516 /// \param[in] FallbackStyle The name of a predefined style used to fallback to
 517 /// in case the style can't be determined from \p StyleName.
 518 ///
 519 /// \returns FormatStyle as specified by \c StyleName. If no style could be
 520 /// determined, the default is LLVM Style (see getLLVMStyle()).
 521 FormatStyle getStyle(StringRef StyleName, StringRef FileName,
 522                      StringRef FallbackStyle);
 523
 524 } // end namespace format
 525 } // end namespace clang
 526
 527 namespace std {
 528 template <>
 529 struct is_error_code_enum<clang::format::ParseError> : std::true_type {};
 530 }
 531
 532 #endif // LLVM_CLANG_FORMAT_FORMAT_H