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