1=========
2LibFormat
3=========
4
5LibFormat is a library that implements automatic source code formatting based
6on Clang. This documents describes the LibFormat interface and design as well
7as some basic style discussions.
8
9If you just want to use `clang-format` as a tool or integrated into an editor,
10checkout :doc:`ClangFormat`.
11
12Design
13------
14
15FIXME: Write up design.
16
17
18Interface
19---------
20
21The 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
29This reads a token stream out of the lexer ``Lex`` and reformats all the code
30ranges in ``Ranges``. The ``FormatStyle`` controls basic decisions made during
31formatting. A list of options can be found under :ref:`style-options`.
32
33The style options are described in :doc:`ClangFormatStyleOptions`.
34
35
36.. _style-options:
37
38Style Options
39-------------
40
41The style options describe specific formatting options that can be used in
42order to make `ClangFormat` comply with different style guides. Currently,
43several 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
75These options are also exposed in the :doc:`standalone tools <ClangFormat>`
76through the `-style` option.
77
78In the future, we plan on making this configurable.
79