blob: 2863a076edf46216efc3bdcd5eef3e883ec70380 [file] [log] [blame]
Daniel Jasper85a77c12013-01-09 21:49:281=========
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
Sylvestre Ledru69f49ce2017-06-26 03:19:0531formatting. A list of options can be found under :ref:`style-options`.
32
33The style options are described in :doc:`ClangFormatStyleOptions`.
Daniel Jasper85a77c12013-01-09 21:49:2834
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
Adrian Prantl9fc8faf2018-05-09 01:00:0147 /// Returns a format style complying with the LLVM coding standards:
Daniel Jasper85a77c12013-01-09 21:49:2848 /// http://llvm.org/docs/CodingStandards.html.
49 FormatStyle getLLVMStyle();
50
Adrian Prantl9fc8faf2018-05-09 01:00:0151 /// Returns a format style complying with Google's C++ style guide:
Daniel Jasper85a77c12013-01-09 21:49:2852 /// 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.