granicus.if.org Git - clang/blob - docs/LibFormat.rst

   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
  31 formatting. A list of options can be found under :ref:`style-options`.
  32
  33
  34 .. _style-options:
  35
  36 Style Options
  37 -------------
  38
  39 The style options describe specific formatting options that can be used in
  40 order to make `ClangFormat` comply with different style guides. Currently,
  41 two 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
  53 These options are also exposed in the :doc:`standalone tools <ClangFormat>`
  54 through the `-style` option.
  55
  56 In the future, we plan on making this configurable.