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,
43two 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
55These options are also exposed in the :doc:`standalone tools <ClangFormat>`
56through the `-style` option.
57
58In the future, we plan on making this configurable.
59