Daniel Jasper | 85a77c1 | 2013-01-09 21:49:28 | [diff] [blame] | 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 |
Sylvestre Ledru | 69f49ce | 2017-06-26 03:19:05 | [diff] [blame] | 31 | formatting. A list of options can be found under :ref:`style-options`. |
| 32 | |
| 33 | The style options are described in :doc:`ClangFormatStyleOptions`. |
Daniel Jasper | 85a77c1 | 2013-01-09 21:49:28 | [diff] [blame] | 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 | two style guides are hard-coded: |
| 44 | |
| 45 | .. code-block:: c++ |
| 46 | |
Adrian Prantl | 9fc8faf | 2018-05-09 01:00:01 | [diff] [blame^] | 47 | /// Returns a format style complying with the LLVM coding standards: |
Daniel Jasper | 85a77c1 | 2013-01-09 21:49:28 | [diff] [blame] | 48 | /// http://llvm.org/docs/CodingStandards.html. |
| 49 | FormatStyle getLLVMStyle(); |
| 50 | |
Adrian Prantl | 9fc8faf | 2018-05-09 01:00:01 | [diff] [blame^] | 51 | /// Returns a format style complying with Google's C++ style guide: |
Daniel Jasper | 85a77c1 | 2013-01-09 21:49:28 | [diff] [blame] | 52 | /// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml. |
| 53 | FormatStyle getGoogleStyle(); |
| 54 | |
| 55 | These options are also exposed in the :doc:`standalone tools <ClangFormat>` |
| 56 | through the `-style` option. |
| 57 | |
| 58 | In the future, we plan on making this configurable. |