clang/lib/Format/FormatInternal.h

   1 //===--- FormatInternal.h - Format C++ code ---------------------*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8 ///
   9 /// \file
  10 /// This file declares Format APIs to be used internally by the
  11 /// formatting library implementation.
  12 ///
  13 //===----------------------------------------------------------------------===//
  14
  15 #ifndef LLVM_CLANG_LIB_FORMAT_FORMATINTERNAL_H
  16 #define LLVM_CLANG_LIB_FORMAT_FORMATINTERNAL_H
  17
  18 #include "clang/Basic/LLVM.h"
  19 #include "clang/Format/Format.h"
  20 #include "clang/Tooling/Core/Replacement.h"
  21 #include <utility>
  22
  23 namespace clang {
  24 namespace format {
  25 namespace internal {
  26
  27 /// Reformats the given \p Ranges in the code fragment \p Code.
  28 ///
  29 /// A fragment of code could conceptually be surrounded by other code that might
  30 /// constrain how that fragment is laid out.
  31 /// For example, consider the fragment of code between 'R"(' and ')"',
  32 /// exclusive, in the following code:
  33 ///
  34 /// void outer(int x) {
  35 ///   string inner = R"(name: data
  36 ///                     ^ FirstStartColumn
  37 ///     value: {
  38 ///       x: 1
  39 ///     ^ NextStartColumn
  40 ///     }
  41 ///   )";
  42 ///   ^ LastStartColumn
  43 /// }
  44 ///
  45 /// The outer code can influence the inner fragment as follows:
  46 ///   * \p FirstStartColumn specifies the column at which \p Code starts.
  47 ///   * \p NextStartColumn specifies the additional indent dictated by the
  48 ///     surrounding code. It is applied to the rest of the lines of \p Code.
  49 ///   * \p LastStartColumn specifies the column at which the last line of
  50 ///     \p Code should end, in case the last line is an empty line.
  51 ///
  52 ///     In the case where the last line of the fragment contains content,
  53 ///     the fragment ends at the end of that content and \p LastStartColumn is
  54 ///     not taken into account, for example in:
  55 ///
  56 ///     void block() {
  57 ///       string inner = R"(name: value)";
  58 ///     }
  59 ///
  60 /// Each range is extended on either end to its next bigger logic unit, i.e.
  61 /// everything that might influence its formatting or might be influenced by its
  62 /// formatting.
  63 ///
  64 /// Returns a pair P, where:
  65 ///   * P.first are the ``Replacements`` necessary to make all \p Ranges comply
  66 ///     with \p Style.
  67 ///   * P.second is the penalty induced by formatting the fragment \p Code.
  68 ///     If the formatting of the fragment doesn't have a notion of penalty,
  69 ///     returns 0.
  70 ///
  71 /// If ``Status`` is non-null, its value will be populated with the status of
  72 /// this formatting attempt. See \c FormattingAttemptStatus.
  73 std::pair<tooling::Replacements, unsigned>
  74 reformat(const FormatStyle &Style, StringRef Code,
  75          ArrayRef<tooling::Range> Ranges, unsigned FirstStartColumn,
  76          unsigned NextStartColumn, unsigned LastStartColumn, StringRef FileName,
  77          FormattingAttemptStatus *Status);
  78
  79 } // namespace internal
  80 } // namespace format
  81 } // namespace clang
  82
  83 #endif