clang/docs/LibFormat.rst

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