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