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
33
34.. _style-options:
35
36Style Options
37-------------
38
39The style options describe specific formatting options that can be used in
40order to make `ClangFormat` comply with different style guides. Currently,
41two style guides are hard-coded:
42
43.. code-block:: c++
44
45  /// \brief Returns a format style complying with the LLVM coding standards:
46  /// http://llvm.org/docs/CodingStandards.html.
47  FormatStyle getLLVMStyle();
48
49  /// \brief Returns a format style complying with Google's C++ style guide:
50  /// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml.
51  FormatStyle getGoogleStyle();
52
53These options are also exposed in the :doc:`standalone tools <ClangFormat>`
54through the `-style` option.
55
56In the future, we plan on making this configurable.
57