Home | History | Annotate | Line # | Download | only in docs 
      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/+/master/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.
     79