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 84