llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT--> @llvm/pr-subscribers-clang-format Author: Lakshdeep Singh (lakshsidhu04) <details> <summary>Changes</summary> This adds a new style option to control indentation of goto labels. Includes documentation. --- Patch is 212.85 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/166730.diff 6 Files Affected: - (modified) clang/docs/ClangFormatStyleOptions.rst (+20) - (added) clang/docs/ClangFormatStyleOptions.rst.bak (+7491) - (modified) clang/include/clang/Format/Format.h (+19-1) - (modified) clang/lib/Format/.clang-format (+1) - (modified) clang/lib/Format/Format.cpp (+3) - (modified) clang/lib/Format/UnwrappedLineFormatter.cpp (+11-1) ``````````diff diff --git a/clang/docs/ClangFormatStyleOptions.rst b/clang/docs/ClangFormatStyleOptions.rst index 0b4a4849f6ccc..1ce9d77d01f04 100644 --- a/clang/docs/ClangFormatStyleOptions.rst +++ b/clang/docs/ClangFormatStyleOptions.rst @@ -4542,6 +4542,26 @@ the configuration (without a prefix: ``Auto``). return 1; return 1; } } +.. _IndentGotoLabelsToCurrentScope: + +**IndentGotoLabelsToCurrentScope** (``Boolean``) :versionbadge:`clang-format 19` :ref:`¶ <IndentGotoLabelsToCurrentScope>` + If true, aligns labels according to the current indentation level + instead of flushing them to the left margin. + + + .. code-block:: c++ + + true: false: + int main() { int main() { + for (int i = 0; i < 5; i++) for (int i = 0; i < 5; i++) + for (int j = 0; j < 5; j++) { for (int j = 0; j < 5; j++) { + // some code // some code + goto end_double_loop; goto end_double_loop; + } } + } } + end_double_loop: {} end_double_loop: {} + } } + .. _IndentPPDirectives: **IndentPPDirectives** (``PPDirectiveIndentStyle``) :versionbadge:`clang-format 6` :ref:`¶ <IndentPPDirectives>` diff --git a/clang/docs/ClangFormatStyleOptions.rst.bak b/clang/docs/ClangFormatStyleOptions.rst.bak new file mode 100644 index 0000000000000..71699309332a8 --- /dev/null +++ b/clang/docs/ClangFormatStyleOptions.rst.bak @@ -0,0 +1,7491 @@ +.. + !!!!NOTE!!!! + This file is automatically generated, in part. Do not edit the style options + in this file directly. Instead, modify them in include/clang/Format/Format.h + and run the docs/tools/dump_format_style.py script to update this file. + +.. raw:: html + + <style type="text/css"> + .versionbadge { background-color: #1c913d; height: 20px; display: inline-block; min-width: 120px; text-align: center; border-radius: 5px; color: #FFFFFF; font-family: "Verdana,Geneva,DejaVu Sans,sans-serif"; } + </style> + +.. role:: versionbadge + +========================== +Clang-Format Style Options +========================== + +:doc:`ClangFormatStyleOptions` describes configurable formatting style options +supported by :doc:`LibFormat` and :doc:`ClangFormat`. + +When using :program:`clang-format` command line utility or +``clang::format::reformat(...)`` functions from code, one can either use one of +the predefined styles (LLVM, Google, Chromium, Mozilla, WebKit, Microsoft) or +create a custom style by configuring specific style options. + + +Configuring Style with clang-format +=================================== + +:program:`clang-format` supports two ways to provide custom style options: +directly specify style configuration in the ``-style=`` command line option or +use ``-style=file`` and put style configuration in the ``.clang-format`` or +``_clang-format`` file in the project directory. + +When using ``-style=file``, :program:`clang-format` for each input file will +try to find the ``.clang-format`` file located in the closest parent directory +of the input file. When the standard input is used, the search is started from +the current directory. + +When using ``-style=file:<format_file_path>``, :program:`clang-format` for +each input file will use the format file located at `<format_file_path>`. +The path may be absolute or relative to the working directory. + +The ``.clang-format`` file uses YAML format: + +.. code-block:: yaml + + key1: value1 + key2: value2 + # A comment. + ... + +The configuration file can consist of several sections each having different +``Language:`` parameter denoting the programming language this section of the +configuration is targeted at. See the description of the **Language** option +below for the list of supported languages. The first section may have no +language set, it will set the default style options for all languages. +Configuration sections for specific language will override options set in the +default section. + +When :program:`clang-format` formats a file, it auto-detects the language using +the file name. When formatting standard input or a file that doesn't have the +extension corresponding to its language, ``-assume-filename=`` option can be +used to override the file name :program:`clang-format` uses to detect the +language. + +An example of a configuration file for multiple languages: + +.. code-block:: yaml + + --- + # We'll use defaults from the LLVM style, but with 4 columns indentation. + BasedOnStyle: LLVM + IndentWidth: 4 + --- + Language: Cpp + # Force pointers to the type for C++. + DerivePointerAlignment: false + PointerAlignment: Left + --- + Language: JavaScript + # Use 100 columns for JS. + ColumnLimit: 100 + --- + Language: Proto + # Don't format .proto files. + DisableFormat: true + --- + Language: CSharp + # Use 100 columns for C#. + ColumnLimit: 100 + ... + +An easy way to get a valid ``.clang-format`` file containing all configuration +options of a certain predefined style is: + +.. code-block:: console + + clang-format -style=llvm -dump-config > .clang-format + +When specifying configuration in the ``-style=`` option, the same configuration +is applied for all input files. The format of the configuration is: + +.. code-block:: console + + -style='{key1: value1, key2: value2, ...}' + + +Disabling Formatting on a Piece of Code +======================================= + +Clang-format understands also special comments that switch formatting in a +delimited range. The code between a comment ``// clang-format off`` or +``/* clang-format off */`` up to a comment ``// clang-format on`` or +``/* clang-format on */`` will not be formatted. The comments themselves will be +formatted (aligned) normally. Also, a colon (``:``) and additional text may +follow ``// clang-format off`` or ``// clang-format on`` to explain why +clang-format is turned off or back on. + +.. code-block:: c++ + + int formatted_code; + // clang-format off + void unformatted_code ; + // clang-format on + void formatted_code_again; + +In addition, the ``OneLineFormatOffRegex`` option gives you a concise way to +disable formatting for all of the lines that match the regular expression. + + +Configuring Style in Code +========================= + +When using ``clang::format::reformat(...)`` functions, the format is specified +by supplying the `clang::format::FormatStyle +<https://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html>`_ +structure. + + +Configurable Format Style Options +================================= + +This section lists the supported style options. Value type is specified for +each option. For enumeration types possible values are specified both as a C++ +enumeration member (with a prefix, e.g. ``LS_Auto``), and as a value usable in +the configuration (without a prefix: ``Auto``). + +.. _BasedOnStyle: + +**BasedOnStyle** (``String``) :ref:`¶ <BasedOnStyle>` + The style used for all options not specifically set in the configuration. + + This option is supported only in the :program:`clang-format` configuration + (both within ``-style='{...}'`` and the ``.clang-format`` file). + + Possible values: + + * ``LLVM`` + A style complying with the `LLVM coding standards + <https://llvm.org/docs/CodingStandards.html>`_ + * ``Google`` + A style complying with `Google's C++ style guide + <https://google.github.io/styleguide/cppguide.html>`_ + * ``Chromium`` + A style complying with `Chromium's style guide + <https://chromium.googlesource.com/chromium/src/+/refs/heads/main/styleguide/styleguide.md>`_ + * ``Mozilla`` + A style complying with `Mozilla's style guide + <https://firefox-source-docs.mozilla.org/code-quality/coding-style/index.html>`_ + * ``WebKit`` + A style complying with `WebKit's style guide + <https://www.webkit.org/coding/coding-style.html>`_ + * ``Microsoft`` + A style complying with `Microsoft's style guide + <https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference>`_ + * ``GNU`` + A style complying with the `GNU coding standards + <https://www.gnu.org/prep/standards/standards.html>`_ + * ``InheritParentConfig`` + Not a real style, but allows to use the ``.clang-format`` file from the + parent directory (or its parent if there is none). If there is no parent + file found it falls back to the ``fallback`` style, and applies the changes + to that. + + With this option you can overwrite some parts of your main style for your + subdirectories. This is also possible through the command line, e.g.: + ``--style={BasedOnStyle: InheritParentConfig, ColumnLimit: 20}`` + +.. START_FORMAT_STYLE_OPTIONS + +.. _AccessModifierOffset: + +**AccessModifierOffset** (``Integer``) :versionbadge:`clang-format 3.3` :ref:`¶ <AccessModifierOffset>` + The extra indent or outdent of access modifiers, e.g. ``public:``. + +.. _AlignAfterOpenBracket: + +**AlignAfterOpenBracket** (``Boolean``) :versionbadge:`clang-format 3.8` :ref:`¶ <AlignAfterOpenBracket>` + If ``true``, horizontally aligns arguments after an open bracket. + + + .. code-block:: c++ + + true: vs. false + someLongFunction(argument1, someLongFunction(argument1, + argument2); argument2); + + + .. note:: + + As of clang-format 22 this option is a bool with the previous + option of ``Align`` replaced with ``true``, ``DontAlign`` replaced + with ``false``, and the options of ``AlwaysBreak`` and ``BlockIndent`` + replaced with ``true`` and with setting of new style options using + ``BreakAfterOpenBracketBracedList``, ``BreakAfterOpenBracketFunction``, + ``BreakAfterOpenBracketIf``, ``BreakBeforeCloseBracketBracedList``, + ``BreakBeforeCloseBracketFunction``, and ``BreakBeforeCloseBracketIf``. + + This applies to round brackets (parentheses), angle brackets and square + brackets. + +.. _AlignArrayOfStructures: + +**AlignArrayOfStructures** (``ArrayInitializerAlignmentStyle``) :versionbadge:`clang-format 13` :ref:`¶ <AlignArrayOfStructures>` + If not ``None``, when using initialization for an array of structs + aligns the fields into columns. + + + .. note:: + + As of clang-format 15 this option only applied to arrays with equal + number of columns per row. + + Possible values: + + * ``AIAS_Left`` (in configuration: ``Left``) + Align array column and left justify the columns e.g.: + + .. code-block:: c++ + + struct test demo[] = + { + {56, 23, "hello"}, + {-1, 93463, "world"}, + {7, 5, "!!" } + }; + + * ``AIAS_Right`` (in configuration: ``Right``) + Align array column and right justify the columns e.g.: + + .. code-block:: c++ + + struct test demo[] = + { + {56, 23, "hello"}, + {-1, 93463, "world"}, + { 7, 5, "!!"} + }; + + * ``AIAS_None`` (in configuration: ``None``) + Don't align array initializer columns. + + + +.. _AlignConsecutiveAssignments: + +**AlignConsecutiveAssignments** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 3.8` :ref:`¶ <AlignConsecutiveAssignments>` + Style of aligning consecutive assignments. + + ``Consecutive`` will result in formattings like: + + .. code-block:: c++ + + int a = 1; + int somelongname = 2; + double c = 3; + + Nested configuration flags: + + Alignment options. + + They can also be read as a whole for compatibility. The choices are: + + * ``None`` + * ``Consecutive`` + * ``AcrossEmptyLines`` + * ``AcrossComments`` + * ``AcrossEmptyLinesAndComments`` + + For example, to align across empty lines and not across comments, either + of these work. + + .. code-block:: c++ + + AlignConsecutiveAssignments: AcrossEmptyLines + + AlignConsecutiveAssignments: + Enabled: true + AcrossEmptyLines: true + AcrossComments: false + + * ``bool Enabled`` Whether aligning is enabled. + + .. code-block:: c++ + + #define SHORT_NAME 42 + #define LONGER_NAME 0x007f + #define EVEN_LONGER_NAME (2) + #define foo(x) (x * x) + #define bar(y, z) (y + z) + + int a = 1; + int somelongname = 2; + double c = 3; + + int aaaa : 1; + int b : 12; + int ccc : 8; + + int aaaa = 12; + float b = 23; + std::string ccc; + + * ``bool AcrossEmptyLines`` Whether to align across empty lines. + + .. code-block:: c++ + + true: + int a = 1; + int somelongname = 2; + double c = 3; + + int d = 3; + + false: + int a = 1; + int somelongname = 2; + double c = 3; + + int d = 3; + + * ``bool AcrossComments`` Whether to align across comments. + + .. code-block:: c++ + + true: + int d = 3; + /* A comment. */ + double e = 4; + + false: + int d = 3; + /* A comment. */ + double e = 4; + + * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments + like ``+=`` are aligned along with ``=``. + + .. code-block:: c++ + + true: + a &= 2; + bbb = 2; + + false: + a &= 2; + bbb = 2; + + * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations + are aligned. + + .. code-block:: c++ + + true: + unsigned int f1(void); + void f2(void); + size_t f3(void); + + false: + unsigned int f1(void); + void f2(void); + size_t f3(void); + + * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are + aligned. + + .. code-block:: c++ + + true: + unsigned i; + int &r; + int *p; + int (*f)(); + + false: + unsigned i; + int &r; + int *p; + int (*f)(); + + * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment + operators are left-padded to the same length as long ones in order to + put all assignment operators to the right of the left hand side. + + .. code-block:: c++ + + true: + a >>= 2; + bbb = 2; + + a = 2; + bbb >>= 2; + + false: + a >>= 2; + bbb = 2; + + a = 2; + bbb >>= 2; + + +.. _AlignConsecutiveBitFields: + +**AlignConsecutiveBitFields** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 11` :ref:`¶ <AlignConsecutiveBitFields>` + Style of aligning consecutive bit fields. + + ``Consecutive`` will align the bitfield separators of consecutive lines. + This will result in formattings like: + + .. code-block:: c++ + + int aaaa : 1; + int b : 12; + int ccc : 8; + + Nested configuration flags: + + Alignment options. + + They can also be read as a whole for compatibility. The choices are: + + * ``None`` + * ``Consecutive`` + * ``AcrossEmptyLines`` + * ``AcrossComments`` + * ``AcrossEmptyLinesAndComments`` + + For example, to align across empty lines and not across comments, either + of these work. + + .. code-block:: c++ + + AlignConsecutiveBitFields: AcrossEmptyLines + + AlignConsecutiveBitFields: + Enabled: true + AcrossEmptyLines: true + AcrossComments: false + + * ``bool Enabled`` Whether aligning is enabled. + + .. code-block:: c++ + + #define SHORT_NAME 42 + #define LONGER_NAME 0x007f + #define EVEN_LONGER_NAME (2) + #define foo(x) (x * x) + #define bar(y, z) (y + z) + + int a = 1; + int somelongname = 2; + double c = 3; + + int aaaa : 1; + int b : 12; + int ccc : 8; + + int aaaa = 12; + float b = 23; + std::string ccc; + + * ``bool AcrossEmptyLines`` Whether to align across empty lines. + + .. code-block:: c++ + + true: + int a = 1; + int somelongname = 2; + double c = 3; + + int d = 3; + + false: + int a = 1; + int somelongname = 2; + double c = 3; + + int d = 3; + + * ``bool AcrossComments`` Whether to align across comments. + + .. code-block:: c++ + + true: + int d = 3; + /* A comment. */ + double e = 4; + + false: + int d = 3; + /* A comment. */ + double e = 4; + + * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments + like ``+=`` are aligned along with ``=``. + + .. code-block:: c++ + + true: + a &= 2; + bbb = 2; + + false: + a &= 2; + bbb = 2; + + * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations + are aligned. + + .. code-block:: c++ + + true: + unsigned int f1(void); + void f2(void); + size_t f3(void); + + false: + unsigned int f1(void); + void f2(void); + size_t f3(void); + + * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are + aligned. + + .. code-block:: c++ + + true: + unsigned i; + int &r; + int *p; + int (*f)(); + + false: + unsigned i; + int &r; + int *p; + int (*f)(); + + * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment + operators are left-padded to the same length as long ones in order to + put all assignment operators to the right of the left hand side. + + .. code-block:: c++ + + true: + a >>= 2; + bbb = 2; + + a = 2; + bbb >>= 2; + + false: + a >>= 2; + bbb = 2; + + a = 2; + bbb >>= 2; + + +.. _AlignConsecutiveDeclarations: + +**AlignConsecutiveDeclarations** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 3.8` :ref:`¶ <AlignConsecutiveDeclarations>` + Style of aligning consecutive declarations. + + ``Consecutive`` will align the declaration names of consecutive lines. + This will result in formattings like: + + .. code-block:: c++ + + int aaaa = 12; + float b = 23; + std::string ccc; + + Nested configuration flags: + + Alignment options. + + They can also be read as a whole for compatibility. The choices are: + + * ``None`` + * ``Consecutive`` + * ``AcrossEmptyLines`` + * ``AcrossComments`` + * ``AcrossEmptyLinesAndComments`` + + For example, to align across empty lines and not across comments, either + of these work. + + .. code-block:: c++ + + AlignConsecutiveDeclarations: AcrossEmptyLines + + AlignConsecutiveDeclarations: + Enabled: true + AcrossEmptyLines: true + AcrossComments: false + + * ``bool Enabled`` Whether aligning is enabled. + + .. code-block:: c++ + + #define SHORT_NAME 42 + #define LONGER_NAME 0x007f + #define EVEN_LONGER_NAME (2) + #define foo(x) (x * x) + #define bar(y, z) (y + z) + + int a = 1; + int somelongname = 2; + double c = 3; + + int aaaa : 1; + int b : 12; + int ccc : 8; + + int aaaa = 12; + float b = 23; + std::string ccc; + + * ``bool AcrossEmptyLines`` Whether to align across empty lines. + + .. code-block:: c++ + + true: + int a = 1; + int somelongname = 2; + double c = 3; + + int d = 3; + + false: + int a = 1; + int somelongname = 2; + double c = 3; + + int d = 3; + + * ``bool AcrossComments`` Whether to align across comments. + + .. code-block:: c++ + + true: + int d = 3; + /* A comment. */ + double e = 4; + + false: + int d = 3; + /* A comment. */ + double e = 4; + + * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments + like ``+=`` are aligned along with ``=``. + + .. code-block:: c++ + + true: + a ... [truncated] `````````` </details> https://github.com/llvm/llvm-project/pull/166730 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
