79 lines
2.5 KiB
ReStructuredText
79 lines
2.5 KiB
ReStructuredText
|
=========
|
||
|
|
LibFormat
|
||
|
|
=========
|
||
|
|
|
||
|
|
LibFormat is a library that implements automatic source code formatting based
|
||
|
|
on Clang. This documents describes the LibFormat interface and design as well
|
||
|
|
as some basic style discussions.
|
||
|
|
|
||
|
|
If you just want to use `clang-format` as a tool or integrated into an editor,
|
||
|
|
checkout :doc:`ClangFormat`.
|
||
|
|
|
||
|
|
Design
|
||
|
|
------
|
||
|
|
|
||
|
|
FIXME: Write up design.
|
||
|
|
|
||
|
|
|
||
|
|
Interface
|
||
|
|
---------
|
||
|
|
|
||
|
|
The core routine of LibFormat is ``reformat()``:
|
||
|
|
|
||
|
|
.. code-block:: c++
|
||
|
|
|
||
|
|
tooling::Replacements reformat(const FormatStyle &Style, Lexer &Lex,
|
||
|
|
SourceManager &SourceMgr,
|
||
|
|
std::vector<CharSourceRange> Ranges);
|
||
|
|
|
||
|
|
This reads a token stream out of the lexer ``Lex`` and reformats all the code
|
||
|
|
ranges in ``Ranges``. The ``FormatStyle`` controls basic decisions made during
|
||
|
|
formatting. A list of options can be found under :ref:`style-options`.
|
||
|
|
|
||
|
|
The style options are described in :doc:`ClangFormatStyleOptions`.
|
||
|
|
|
||
|
|
|
||
|
|
.. _style-options:
|
||
|
|
|
||
|
|
Style Options
|
||
|
|
-------------
|
||
|
|
|
||
|
|
The style options describe specific formatting options that can be used in
|
||
|
|
order to make `ClangFormat` comply with different style guides. Currently,
|
||
|
|
several style guides are hard-coded:
|
||
|
|
|
||
|
|
.. code-block:: c++
|
||
|
|
|
||
|
|
/// Returns a format style complying with the LLVM coding standards:
|
||
|
|
/// https://llvm.org/docs/CodingStandards.html.
|
||
|
|
FormatStyle getLLVMStyle();
|
||
|
|
|
||
|
|
/// Returns a format style complying with Google's C++ style guide:
|
||
|
|
/// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml.
|
||
|
|
FormatStyle getGoogleStyle();
|
||
|
|
|
||
|
|
/// Returns a format style complying with Chromium's style guide:
|
||
|
|
/// https://chromium.googlesource.com/chromium/src/+/master/styleguide/styleguide.md
|
||
|
|
FormatStyle getChromiumStyle();
|
||
|
|
|
||
|
|
/// Returns a format style complying with the GNU coding standards:
|
||
|
|
/// https://www.gnu.org/prep/standards/standards.html
|
||
|
|
FormatStyle getGNUStyle();
|
||
|
|
|
||
|
|
/// Returns a format style complying with Mozilla's style guide
|
||
|
|
/// https://firefox-source-docs.mozilla.org/code-quality/coding-style/index.html
|
||
|
|
FormatStyle getMozillaStyle();
|
||
|
|
|
||
|
|
/// Returns a format style complying with Webkit's style guide:
|
||
|
|
/// https://webkit.org/code-style-guidelines/
|
||
|
|
FormatStyle getWebkitStyle();
|
||
|
|
|
||
|
|
/// Returns a format style complying with Microsoft's style guide:
|
||
|
|
/// https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference
|
||
|
|
FormatStyle getMicrosoftStyle();
|
||
|
|
|
||
|
|
These options are also exposed in the :doc:`standalone tools <ClangFormat>`
|
||
|
|
through the `-style` option.
|
||
|
|
|
||
|
|
In the future, we plan on making this configurable.
|