1e5dd7070Spatrick========= 2e5dd7070SpatrickLibFormat 3e5dd7070Spatrick========= 4e5dd7070Spatrick 5e5dd7070SpatrickLibFormat is a library that implements automatic source code formatting based 6e5dd7070Spatrickon Clang. This documents describes the LibFormat interface and design as well 7e5dd7070Spatrickas some basic style discussions. 8e5dd7070Spatrick 9e5dd7070SpatrickIf you just want to use `clang-format` as a tool or integrated into an editor, 10e5dd7070Spatrickcheckout :doc:`ClangFormat`. 11e5dd7070Spatrick 12e5dd7070SpatrickDesign 13e5dd7070Spatrick------ 14e5dd7070Spatrick 15e5dd7070SpatrickFIXME: Write up design. 16e5dd7070Spatrick 17e5dd7070Spatrick 18e5dd7070SpatrickInterface 19e5dd7070Spatrick--------- 20e5dd7070Spatrick 21e5dd7070SpatrickThe core routine of LibFormat is ``reformat()``: 22e5dd7070Spatrick 23e5dd7070Spatrick.. code-block:: c++ 24e5dd7070Spatrick 25e5dd7070Spatrick tooling::Replacements reformat(const FormatStyle &Style, Lexer &Lex, 26e5dd7070Spatrick SourceManager &SourceMgr, 27e5dd7070Spatrick std::vector<CharSourceRange> Ranges); 28e5dd7070Spatrick 29e5dd7070SpatrickThis reads a token stream out of the lexer ``Lex`` and reformats all the code 30e5dd7070Spatrickranges in ``Ranges``. The ``FormatStyle`` controls basic decisions made during 31e5dd7070Spatrickformatting. A list of options can be found under :ref:`style-options`. 32e5dd7070Spatrick 33e5dd7070SpatrickThe style options are described in :doc:`ClangFormatStyleOptions`. 34e5dd7070Spatrick 35e5dd7070Spatrick 36e5dd7070Spatrick.. _style-options: 37e5dd7070Spatrick 38e5dd7070SpatrickStyle Options 39e5dd7070Spatrick------------- 40e5dd7070Spatrick 41e5dd7070SpatrickThe style options describe specific formatting options that can be used in 42e5dd7070Spatrickorder to make `ClangFormat` comply with different style guides. Currently, 43ec727ea7Spatrickseveral style guides are hard-coded: 44e5dd7070Spatrick 45e5dd7070Spatrick.. code-block:: c++ 46e5dd7070Spatrick 47e5dd7070Spatrick /// Returns a format style complying with the LLVM coding standards: 48e5dd7070Spatrick /// https://llvm.org/docs/CodingStandards.html. 49e5dd7070Spatrick FormatStyle getLLVMStyle(); 50e5dd7070Spatrick 51e5dd7070Spatrick /// Returns a format style complying with Google's C++ style guide: 52e5dd7070Spatrick /// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml. 53e5dd7070Spatrick FormatStyle getGoogleStyle(); 54e5dd7070Spatrick 55ec727ea7Spatrick /// Returns a format style complying with Chromium's style guide: 56*12c85518Srobert /// https://chromium.googlesource.com/chromium/src/+/refs/heads/main/styleguide/styleguide.md 57ec727ea7Spatrick FormatStyle getChromiumStyle(); 58ec727ea7Spatrick 59ec727ea7Spatrick /// Returns a format style complying with the GNU coding standards: 60ec727ea7Spatrick /// https://www.gnu.org/prep/standards/standards.html 61ec727ea7Spatrick FormatStyle getGNUStyle(); 62ec727ea7Spatrick 63ec727ea7Spatrick /// Returns a format style complying with Mozilla's style guide 64ec727ea7Spatrick /// https://firefox-source-docs.mozilla.org/code-quality/coding-style/index.html 65ec727ea7Spatrick FormatStyle getMozillaStyle(); 66ec727ea7Spatrick 67ec727ea7Spatrick /// Returns a format style complying with Webkit's style guide: 68ec727ea7Spatrick /// https://webkit.org/code-style-guidelines/ 69ec727ea7Spatrick FormatStyle getWebkitStyle(); 70ec727ea7Spatrick 71ec727ea7Spatrick /// Returns a format style complying with Microsoft's style guide: 72ec727ea7Spatrick /// https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference 73ec727ea7Spatrick FormatStyle getMicrosoftStyle(); 74ec727ea7Spatrick 75e5dd7070SpatrickThese options are also exposed in the :doc:`standalone tools <ClangFormat>` 76e5dd7070Spatrickthrough the `-style` option. 77e5dd7070Spatrick 78e5dd7070SpatrickIn the future, we plan on making this configurable. 79