1 //===--- Format.h - Format C++ code -----------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
11 /// Various functions to configurably format source code.
13 //===----------------------------------------------------------------------===//
15 #ifndef LLVM_CLANG_FORMAT_FORMAT_H
16 #define LLVM_CLANG_FORMAT_FORMAT_H
18 #include "clang/Basic/LangOptions.h"
19 #include "clang/Tooling/Core/Replacement.h"
20 #include "llvm/ADT/ArrayRef.h"
21 #include <system_error>
27 class DiagnosticConsumer;
31 enum class ParseError { Success = 0, Error, Unsuitable };
32 class ParseErrorCategory final : public std::error_category {
34 const char *name() const LLVM_NOEXCEPT override;
35 std::string message(int EV) const override;
37 const std::error_category &getParseCategory();
38 std::error_code make_error_code(ParseError e);
40 /// \brief The ``FormatStyle`` is used to configure the formatting to follow
41 /// specific guidelines.
43 /// \brief The extra indent or outdent of access modifiers, e.g. ``public:``.
44 int AccessModifierOffset;
46 /// \brief Different styles for aligning after open brackets.
47 enum BracketAlignmentStyle {
48 /// \brief Align parameters on the open bracket, e.g.:
50 /// someLongFunction(argument1,
54 /// \brief Don't align, instead use ``ContinuationIndentWidth``, e.g.:
56 /// someLongFunction(argument1,
60 /// \brief Always break after an open bracket, if the parameters don't fit
61 /// on a single line, e.g.:
64 /// argument1, argument2);
69 /// \brief If ``true``, horizontally aligns arguments after an open bracket.
71 /// This applies to round brackets (parentheses), angle brackets and square
73 BracketAlignmentStyle AlignAfterOpenBracket;
75 /// \brief If ``true``, aligns consecutive assignments.
77 /// This will align the assignment operators of consecutive lines. This
78 /// will result in formattings like
84 bool AlignConsecutiveAssignments;
86 /// \brief If ``true``, aligns consecutive declarations.
88 /// This will align the declaration names of consecutive lines. This
89 /// will result in formattings like
93 /// std::string ccc = 23;
95 bool AlignConsecutiveDeclarations;
97 /// \brief If ``true``, aligns escaped newlines as far left as possible.
98 /// Otherwise puts them into the right-most column.
99 bool AlignEscapedNewlinesLeft;
101 /// \brief If ``true``, horizontally align operands of binary and ternary
104 /// Specifically, this aligns operands of a single expression that needs to be
105 /// split over multiple lines, e.g.:
107 /// int aaa = bbbbbbbbbbbbbbb +
112 /// \brief If ``true``, aligns trailing comments.
113 bool AlignTrailingComments;
115 /// \brief Allow putting all parameters of a function declaration onto
116 /// the next line even if ``BinPackParameters`` is ``false``.
117 bool AllowAllParametersOfDeclarationOnNextLine;
119 /// \brief Allows contracting simple braced statements to a single line.
121 /// E.g., this allows ``if (a) { return; }`` to be put on a single line.
122 bool AllowShortBlocksOnASingleLine;
124 /// \brief If ``true``, short case labels will be contracted to a single line.
125 bool AllowShortCaseLabelsOnASingleLine;
127 /// \brief Different styles for merging short functions containing at most one
129 enum ShortFunctionStyle {
130 /// \brief Never merge functions into a single line.
132 /// \brief Only merge empty functions.
134 /// \brief Only merge functions defined inside a class. Implies "empty".
136 /// \brief Merge all functions fitting on a single line.
140 /// \brief Dependent on the value, ``int f() { return 0; }`` can be put on a
142 ShortFunctionStyle AllowShortFunctionsOnASingleLine;
144 /// \brief If ``true``, ``if (a) return;`` can be put on a single line.
145 bool AllowShortIfStatementsOnASingleLine;
147 /// \brief If ``true``, ``while (true) continue;`` can be put on a single
149 bool AllowShortLoopsOnASingleLine;
151 /// \brief Different ways to break after the function definition return type.
152 enum DefinitionReturnTypeBreakingStyle {
153 /// Break after return type automatically.
154 /// ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
156 /// Always break after the return type.
158 /// Always break after the return types of top-level functions.
162 /// \brief Different ways to break after the function definition or
163 /// declaration return type.
164 enum ReturnTypeBreakingStyle {
165 /// Break after return type automatically.
166 /// ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
168 /// Always break after the return type.
170 /// Always break after the return types of top-level functions.
172 /// Always break after the return type of function definitions.
174 /// Always break after the return type of top-level definitions.
175 RTBS_TopLevelDefinitions,
178 /// \brief The function definition return type breaking style to use. This
179 /// option is deprecated and is retained for backwards compatibility.
180 DefinitionReturnTypeBreakingStyle AlwaysBreakAfterDefinitionReturnType;
182 /// \brief The function declaration return type breaking style to use.
183 ReturnTypeBreakingStyle AlwaysBreakAfterReturnType;
185 /// \brief If ``true``, always break before multiline string literals.
187 /// This flag is mean to make cases where there are multiple multiline strings
188 /// in a file look more consistent. Thus, it will only take effect if wrapping
189 /// the string at that point leads to it being indented
190 /// ``ContinuationIndentWidth`` spaces from the start of the line.
191 bool AlwaysBreakBeforeMultilineStrings;
193 /// \brief If ``true``, always break after the ``template<...>`` of a template
195 bool AlwaysBreakTemplateDeclarations;
197 /// \brief If ``false``, a function call's arguments will either be all on the
198 /// same line or will have one line each.
199 bool BinPackArguments;
201 /// \brief If ``false``, a function declaration's or function definition's
202 /// parameters will either all be on the same line or will have one line each.
203 bool BinPackParameters;
205 /// \brief The style of breaking before or after binary operators.
206 enum BinaryOperatorStyle {
207 /// Break after operators.
209 /// Break before operators that aren't assignments.
211 /// Break before operators.
215 /// \brief The way to wrap binary operators.
216 BinaryOperatorStyle BreakBeforeBinaryOperators;
218 /// \brief Different ways to attach braces to their surrounding context.
219 enum BraceBreakingStyle {
220 /// Always attach braces to surrounding context.
222 /// Like ``Attach``, but break before braces on function, namespace and
223 /// class definitions.
225 /// Like ``Attach``, but break before braces on enum, function, and record
228 /// Like ``Attach``, but break before function definitions, ``catch``, and
231 /// Always break before braces.
233 /// Always break before braces and add an extra level of indentation to
234 /// braces of control statements, not to those of class, function
235 /// or other definitions.
237 /// Like ``Attach``, but break before functions.
239 /// Configure each individual brace in `BraceWrapping`.
243 /// \brief The brace breaking style to use.
244 BraceBreakingStyle BreakBeforeBraces;
246 /// \brief Precise control over the wrapping of braces.
247 struct BraceWrappingFlags {
248 /// \brief Wrap class definitions.
250 /// \brief Wrap control statements (``if``/``for``/``while``/``switch``/..).
251 bool AfterControlStatement;
252 /// \brief Wrap enum definitions.
254 /// \brief Wrap function definitions.
256 /// \brief Wrap namespace definitions.
258 /// \brief Wrap ObjC definitions (``@autoreleasepool``, interfaces, ..).
259 bool AfterObjCDeclaration;
260 /// \brief Wrap struct definitions.
262 /// \brief Wrap union definitions.
264 /// \brief Wrap before ``catch``.
266 /// \brief Wrap before ``else``.
268 /// \brief Indent the wrapped braces themselves.
272 /// \brief Control of individual brace wrapping cases.
274 /// If ``BreakBeforeBraces`` is set to ``BS_Custom``, use this to specify how
275 /// each individual brace case should be handled. Otherwise, this is ignored.
276 BraceWrappingFlags BraceWrapping;
278 /// \brief If ``true``, ternary operators will be placed after line breaks.
279 bool BreakBeforeTernaryOperators;
281 /// \brief Always break constructor initializers before commas and align
282 /// the commas with the colon.
283 bool BreakConstructorInitializersBeforeComma;
285 /// \brief Break after each annotation on a field in Java files.
286 bool BreakAfterJavaFieldAnnotations;
288 /// \brief Allow breaking string literals when formatting.
289 bool BreakStringLiterals;
291 /// \brief The column limit.
293 /// A column limit of ``0`` means that there is no column limit. In this case,
294 /// clang-format will respect the input's line breaking decisions within
295 /// statements unless they contradict other rules.
296 unsigned ColumnLimit;
298 /// \brief A regular expression that describes comments with special meaning,
299 /// which should not be split into lines or otherwise changed.
300 std::string CommentPragmas;
302 /// \brief If the constructor initializers don't fit on a line, put each
303 /// initializer on its own line.
304 bool ConstructorInitializerAllOnOneLineOrOnePerLine;
306 /// \brief The number of characters to use for indentation of constructor
307 /// initializer lists.
308 unsigned ConstructorInitializerIndentWidth;
310 /// \brief Indent width for line continuations.
311 unsigned ContinuationIndentWidth;
313 /// \brief If ``true``, format braced lists as best suited for C++11 braced
316 /// Important differences:
317 /// - No spaces inside the braced list.
318 /// - No line break before the closing brace.
319 /// - Indentation with the continuation indent, not with the block indent.
321 /// Fundamentally, C++11 braced lists are formatted exactly like function
322 /// calls would be formatted in their place. If the braced list follows a name
323 /// (e.g. a type or variable name), clang-format formats as if the ``{}`` were
324 /// the parentheses of a function call with that name. If there is no name,
325 /// a zero-length name is assumed.
326 bool Cpp11BracedListStyle;
328 /// \brief If ``true``, analyze the formatted file for the most common
329 /// alignment of ``&`` and ``*``. ``PointerAlignment`` is then used only as
331 bool DerivePointerAlignment;
333 /// \brief Disables formatting completely.
336 /// \brief If ``true``, clang-format detects whether function calls and
337 /// definitions are formatted with one parameter per line.
339 /// Each call can be bin-packed, one-per-line or inconclusive. If it is
340 /// inconclusive, e.g. completely on one line, but a decision needs to be
341 /// made, clang-format analyzes whether there are other bin-packed cases in
342 /// the input file and act accordingly.
344 /// NOTE: This is an experimental flag, that might go away or be renamed. Do
345 /// not use this in config files, etc. Use at your own risk.
346 bool ExperimentalAutoDetectBinPacking;
348 /// \brief A vector of macros that should be interpreted as foreach loops
349 /// instead of as function calls.
351 /// These are expected to be macros of the form:
353 /// FOREACH(<variable-declaration>, ...)
357 /// In the .clang-format configuration file, this can be configured like:
359 /// ForEachMacros: ['RANGES_FOR', 'FOREACH']
362 /// For example: BOOST_FOREACH.
363 std::vector<std::string> ForEachMacros;
365 /// \brief See documentation of ``IncludeCategories``.
366 struct IncludeCategory {
367 /// \brief The regular expression that this category matches.
369 /// \brief The priority to assign to this category.
371 bool operator==(const IncludeCategory &Other) const {
372 return Regex == Other.Regex && Priority == Other.Priority;
376 /// \brief Regular expressions denoting the different ``#include`` categories
377 /// used for ordering ``#includes``.
379 /// These regular expressions are matched against the filename of an include
380 /// (including the <> or "") in order. The value belonging to the first
381 /// matching regular expression is assigned and ``#includes`` are sorted first
382 /// according to increasing category number and then alphabetically within
385 /// If none of the regular expressions match, INT_MAX is assigned as
386 /// category. The main header for a source file automatically gets category 0.
387 /// so that it is generally kept at the beginning of the ``#includes``
388 /// (http://llvm.org/docs/CodingStandards.html#include-style). However, you
389 /// can also assign negative priorities if you have certain headers that
390 /// always need to be first.
392 /// To configure this in the .clang-format file, use:
394 /// IncludeCategories:
395 /// - Regex: '^"(llvm|llvm-c|clang|clang-c)/'
397 /// - Regex: '^(<|"(gtest|isl|json)/)'
402 std::vector<IncludeCategory> IncludeCategories;
404 /// \brief Indent case labels one level from the switch statement.
406 /// When ``false``, use the same indentation level as for the switch statement.
407 /// Switch statement body is always indented one level more than case labels.
408 bool IndentCaseLabels;
410 /// \brief The number of columns to use for indentation.
411 unsigned IndentWidth;
413 /// \brief Indent if a function definition or declaration is wrapped after the
415 bool IndentWrappedFunctionNames;
417 /// \brief If true, empty lines at the start of blocks are kept.
418 bool KeepEmptyLinesAtTheStartOfBlocks;
420 /// \brief Supported languages.
422 /// When stored in a configuration file, specifies the language, that the
423 /// configuration targets. When passed to the ``reformat()`` function, enables
424 /// syntax features specific to the language.
428 /// Should be used for C, C++, ObjectiveC, ObjectiveC++.
430 /// Should be used for Java.
432 /// Should be used for JavaScript.
434 /// Should be used for Protocol Buffers
435 /// (https://developers.google.com/protocol-buffers/).
437 /// Should be used for TableGen code.
441 /// \brief Language, this format style is targeted at.
442 LanguageKind Language;
444 /// \brief A regular expression matching macros that start a block.
445 std::string MacroBlockBegin;
447 /// \brief A regular expression matching macros that end a block.
448 std::string MacroBlockEnd;
450 /// \brief The maximum number of consecutive empty lines to keep.
451 unsigned MaxEmptyLinesToKeep;
453 /// \brief Different ways to indent namespace contents.
454 enum NamespaceIndentationKind {
455 /// Don't indent in namespaces.
457 /// Indent only in inner namespaces (nested in other namespaces).
459 /// Indent in all namespaces.
463 /// \brief The indentation used for namespaces.
464 NamespaceIndentationKind NamespaceIndentation;
466 /// \brief The number of characters to use for indentation of ObjC blocks.
467 unsigned ObjCBlockIndentWidth;
469 /// \brief Add a space after ``@property`` in Objective-C, i.e. use
470 /// ``@property (readonly)`` instead of ``@property(readonly)``.
471 bool ObjCSpaceAfterProperty;
473 /// \brief Add a space in front of an Objective-C protocol list, i.e. use
474 /// ``Foo <Protocol>`` instead of ``Foo<Protocol>``.
475 bool ObjCSpaceBeforeProtocolList;
477 /// \brief The penalty for breaking a function call after ``call(``.
478 unsigned PenaltyBreakBeforeFirstCallParameter;
480 /// \brief The penalty for each line break introduced inside a comment.
481 unsigned PenaltyBreakComment;
483 /// \brief The penalty for breaking before the first ``<<``.
484 unsigned PenaltyBreakFirstLessLess;
486 /// \brief The penalty for each line break introduced inside a string literal.
487 unsigned PenaltyBreakString;
489 /// \brief The penalty for each character outside of the column limit.
490 unsigned PenaltyExcessCharacter;
492 /// \brief Penalty for putting the return type of a function onto its own
494 unsigned PenaltyReturnTypeOnItsOwnLine;
496 /// \brief The ``&`` and ``*`` alignment style.
497 enum PointerAlignmentStyle {
498 /// Align pointer to the left.
500 /// Align pointer to the right.
502 /// Align pointer in the middle.
506 /// \brief Pointer and reference alignment style.
507 PointerAlignmentStyle PointerAlignment;
509 /// \brief If ``true``, clang-format will attempt to re-flow comments.
512 /// \brief If ``true``, clang-format will sort ``#includes``.
515 /// \brief If ``true``, a space may be inserted after C style casts.
516 bool SpaceAfterCStyleCast;
518 /// \brief If ``false``, spaces will be removed before assignment operators.
519 bool SpaceBeforeAssignmentOperators;
521 /// \brief Different ways to put a space before opening parentheses.
522 enum SpaceBeforeParensOptions {
523 /// Never put a space before opening parentheses.
525 /// Put a space before opening parentheses only after control statement
526 /// keywords (``for/if/while...``).
527 SBPO_ControlStatements,
528 /// Always put a space before opening parentheses, except when it's
529 /// prohibited by the syntax rules (in function-like macro definitions) or
530 /// when determined by other style rules (after unary operators, opening
531 /// parentheses, etc.)
535 /// \brief Defines in which cases to put a space before opening parentheses.
536 SpaceBeforeParensOptions SpaceBeforeParens;
538 /// \brief If ``true``, spaces may be inserted into ``()``.
539 bool SpaceInEmptyParentheses;
541 /// \brief The number of spaces before trailing line comments
542 /// (``//`` - comments).
544 /// This does not affect trailing block comments (``/*`` - comments) as
545 /// those commonly have different usage patterns and a number of special
547 unsigned SpacesBeforeTrailingComments;
549 /// \brief If ``true``, spaces will be inserted after ``<`` and before ``>``
550 /// in template argument lists.
553 /// \brief If ``true``, spaces are inserted inside container literals (e.g.
554 /// ObjC and Javascript array and dict literals).
555 bool SpacesInContainerLiterals;
557 /// \brief If ``true``, spaces may be inserted into C style casts.
558 bool SpacesInCStyleCastParentheses;
560 /// \brief If ``true``, spaces will be inserted after ``(`` and before ``)``.
561 bool SpacesInParentheses;
563 /// \brief If ``true``, spaces will be inserted after ``[`` and before ``]``.
564 bool SpacesInSquareBrackets;
566 /// \brief Supported language standards.
567 enum LanguageStandard {
568 /// Use C++03-compatible syntax.
570 /// Use features of C++11 (e.g. ``A<A<int>>`` instead of ``A<A<int> >``).
572 /// Automatic detection based on the input.
576 /// \brief Format compatible with this standard, e.g. use ``A<A<int> >``
577 /// instead of ``A<A<int>>`` for ``LS_Cpp03``.
578 LanguageStandard Standard;
580 /// \brief The number of columns used for tab stops.
583 /// \brief Different ways to use tab in formatting.
587 /// Use tabs only for indentation.
589 /// Use tabs whenever we need to fill whitespace that spans at least from
590 /// one tab stop to the next one.
594 /// \brief The way to use tab characters in the resulting file.
597 bool operator==(const FormatStyle &R) const {
598 return AccessModifierOffset == R.AccessModifierOffset &&
599 AlignAfterOpenBracket == R.AlignAfterOpenBracket &&
600 AlignConsecutiveAssignments == R.AlignConsecutiveAssignments &&
601 AlignConsecutiveDeclarations == R.AlignConsecutiveDeclarations &&
602 AlignEscapedNewlinesLeft == R.AlignEscapedNewlinesLeft &&
603 AlignOperands == R.AlignOperands &&
604 AlignTrailingComments == R.AlignTrailingComments &&
605 AllowAllParametersOfDeclarationOnNextLine ==
606 R.AllowAllParametersOfDeclarationOnNextLine &&
607 AllowShortBlocksOnASingleLine == R.AllowShortBlocksOnASingleLine &&
608 AllowShortCaseLabelsOnASingleLine ==
609 R.AllowShortCaseLabelsOnASingleLine &&
610 AllowShortFunctionsOnASingleLine ==
611 R.AllowShortFunctionsOnASingleLine &&
612 AllowShortIfStatementsOnASingleLine ==
613 R.AllowShortIfStatementsOnASingleLine &&
614 AllowShortLoopsOnASingleLine == R.AllowShortLoopsOnASingleLine &&
615 AlwaysBreakAfterReturnType == R.AlwaysBreakAfterReturnType &&
616 AlwaysBreakBeforeMultilineStrings ==
617 R.AlwaysBreakBeforeMultilineStrings &&
618 AlwaysBreakTemplateDeclarations ==
619 R.AlwaysBreakTemplateDeclarations &&
620 BinPackArguments == R.BinPackArguments &&
621 BinPackParameters == R.BinPackParameters &&
622 BreakBeforeBinaryOperators == R.BreakBeforeBinaryOperators &&
623 BreakBeforeBraces == R.BreakBeforeBraces &&
624 BreakBeforeTernaryOperators == R.BreakBeforeTernaryOperators &&
625 BreakConstructorInitializersBeforeComma ==
626 R.BreakConstructorInitializersBeforeComma &&
627 BreakAfterJavaFieldAnnotations == R.BreakAfterJavaFieldAnnotations &&
628 BreakStringLiterals == R.BreakStringLiterals &&
629 ColumnLimit == R.ColumnLimit && CommentPragmas == R.CommentPragmas &&
630 ConstructorInitializerAllOnOneLineOrOnePerLine ==
631 R.ConstructorInitializerAllOnOneLineOrOnePerLine &&
632 ConstructorInitializerIndentWidth ==
633 R.ConstructorInitializerIndentWidth &&
634 ContinuationIndentWidth == R.ContinuationIndentWidth &&
635 Cpp11BracedListStyle == R.Cpp11BracedListStyle &&
636 DerivePointerAlignment == R.DerivePointerAlignment &&
637 DisableFormat == R.DisableFormat &&
638 ExperimentalAutoDetectBinPacking ==
639 R.ExperimentalAutoDetectBinPacking &&
640 ForEachMacros == R.ForEachMacros &&
641 IncludeCategories == R.IncludeCategories &&
642 IndentCaseLabels == R.IndentCaseLabels &&
643 IndentWidth == R.IndentWidth && Language == R.Language &&
644 IndentWrappedFunctionNames == R.IndentWrappedFunctionNames &&
645 KeepEmptyLinesAtTheStartOfBlocks ==
646 R.KeepEmptyLinesAtTheStartOfBlocks &&
647 MacroBlockBegin == R.MacroBlockBegin &&
648 MacroBlockEnd == R.MacroBlockEnd &&
649 MaxEmptyLinesToKeep == R.MaxEmptyLinesToKeep &&
650 NamespaceIndentation == R.NamespaceIndentation &&
651 ObjCBlockIndentWidth == R.ObjCBlockIndentWidth &&
652 ObjCSpaceAfterProperty == R.ObjCSpaceAfterProperty &&
653 ObjCSpaceBeforeProtocolList == R.ObjCSpaceBeforeProtocolList &&
654 PenaltyBreakBeforeFirstCallParameter ==
655 R.PenaltyBreakBeforeFirstCallParameter &&
656 PenaltyBreakComment == R.PenaltyBreakComment &&
657 PenaltyBreakFirstLessLess == R.PenaltyBreakFirstLessLess &&
658 PenaltyBreakString == R.PenaltyBreakString &&
659 PenaltyExcessCharacter == R.PenaltyExcessCharacter &&
660 PenaltyReturnTypeOnItsOwnLine == R.PenaltyReturnTypeOnItsOwnLine &&
661 PointerAlignment == R.PointerAlignment &&
662 SpaceAfterCStyleCast == R.SpaceAfterCStyleCast &&
663 SpaceBeforeAssignmentOperators == R.SpaceBeforeAssignmentOperators &&
664 SpaceBeforeParens == R.SpaceBeforeParens &&
665 SpaceInEmptyParentheses == R.SpaceInEmptyParentheses &&
666 SpacesBeforeTrailingComments == R.SpacesBeforeTrailingComments &&
667 SpacesInAngles == R.SpacesInAngles &&
668 SpacesInContainerLiterals == R.SpacesInContainerLiterals &&
669 SpacesInCStyleCastParentheses == R.SpacesInCStyleCastParentheses &&
670 SpacesInParentheses == R.SpacesInParentheses &&
671 SpacesInSquareBrackets == R.SpacesInSquareBrackets &&
672 Standard == R.Standard && TabWidth == R.TabWidth &&
677 /// \brief Returns a format style complying with the LLVM coding standards:
678 /// http://llvm.org/docs/CodingStandards.html.
679 FormatStyle getLLVMStyle();
681 /// \brief Returns a format style complying with one of Google's style guides:
682 /// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml.
683 /// http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml.
684 /// https://developers.google.com/protocol-buffers/docs/style.
685 FormatStyle getGoogleStyle(FormatStyle::LanguageKind Language);
687 /// \brief Returns a format style complying with Chromium's style guide:
688 /// http://www.chromium.org/developers/coding-style.
689 FormatStyle getChromiumStyle(FormatStyle::LanguageKind Language);
691 /// \brief Returns a format style complying with Mozilla's style guide:
692 /// https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style.
693 FormatStyle getMozillaStyle();
695 /// \brief Returns a format style complying with Webkit's style guide:
696 /// http://www.webkit.org/coding/coding-style.html
697 FormatStyle getWebKitStyle();
699 /// \brief Returns a format style complying with GNU Coding Standards:
700 /// http://www.gnu.org/prep/standards/standards.html
701 FormatStyle getGNUStyle();
703 /// \brief Returns style indicating formatting should be not applied at all.
704 FormatStyle getNoStyle();
706 /// \brief Gets a predefined style for the specified language by name.
708 /// Currently supported names: LLVM, Google, Chromium, Mozilla. Names are
709 /// compared case-insensitively.
711 /// Returns ``true`` if the Style has been set.
712 bool getPredefinedStyle(StringRef Name, FormatStyle::LanguageKind Language,
715 /// \brief Parse configuration from YAML-formatted text.
717 /// Style->Language is used to get the base style, if the ``BasedOnStyle``
718 /// option is present.
720 /// When ``BasedOnStyle`` is not present, options not present in the YAML
721 /// document, are retained in \p Style.
722 std::error_code parseConfiguration(StringRef Text, FormatStyle *Style);
724 /// \brief Gets configuration in a YAML string.
725 std::string configurationAsText(const FormatStyle &Style);
727 /// \brief Returns the replacements necessary to sort all ``#include`` blocks
728 /// that are affected by ``Ranges``.
729 tooling::Replacements sortIncludes(const FormatStyle &Style, StringRef Code,
730 ArrayRef<tooling::Range> Ranges,
732 unsigned *Cursor = nullptr);
734 /// \brief Reformats the given \p Ranges in the file \p ID.
736 /// Each range is extended on either end to its next bigger logic unit, i.e.
737 /// everything that might influence its formatting or might be influenced by its
740 /// Returns the ``Replacements`` necessary to make all \p Ranges comply with
743 /// If ``IncompleteFormat`` is non-null, its value will be set to true if any
744 /// of the affected ranges were not formatted due to a non-recoverable syntax
746 tooling::Replacements reformat(const FormatStyle &Style,
747 SourceManager &SourceMgr, FileID ID,
748 ArrayRef<CharSourceRange> Ranges,
749 bool *IncompleteFormat = nullptr);
751 /// \brief Reformats the given \p Ranges in \p Code.
753 /// Otherwise identical to the reformat() function using a file ID.
754 tooling::Replacements reformat(const FormatStyle &Style, StringRef Code,
755 ArrayRef<tooling::Range> Ranges,
756 StringRef FileName = "<stdin>",
757 bool *IncompleteFormat = nullptr);
759 /// \brief Returns the ``LangOpts`` that the formatter expects you to set.
761 /// \param Style determines specific settings for lexing mode.
762 LangOptions getFormattingLangOpts(const FormatStyle &Style = getLLVMStyle());
764 /// \brief Description to be used for help text for a ``llvm::cl`` option for
765 /// specifying format style. The description is closely related to the operation
766 /// of ``getStyle()``.
767 extern const char *StyleOptionHelpDescription;
769 /// \brief Construct a FormatStyle based on ``StyleName``.
771 /// ``StyleName`` can take several forms:
772 /// * "{<key>: <value>, ...}" - Set specic style parameters.
773 /// * "<style name>" - One of the style names supported by
774 /// getPredefinedStyle().
775 /// * "file" - Load style configuration from a file called ``.clang-format``
776 /// located in one of the parent directories of ``FileName`` or the current
777 /// directory if ``FileName`` is empty.
779 /// \param[in] StyleName Style name to interpret according to the description
781 /// \param[in] FileName Path to start search for .clang-format if ``StyleName``
783 /// \param[in] FallbackStyle The name of a predefined style used to fallback to
784 /// in case the style can't be determined from \p StyleName.
786 /// \returns FormatStyle as specified by ``StyleName``. If no style could be
787 /// determined, the default is LLVM Style (see ``getLLVMStyle()``).
788 FormatStyle getStyle(StringRef StyleName, StringRef FileName,
789 StringRef FallbackStyle);
791 } // end namespace format
792 } // end namespace clang
796 struct is_error_code_enum<clang::format::ParseError> : std::true_type {};
799 #endif // LLVM_CLANG_FORMAT_FORMAT_H