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
23namespace clang {
24namespace format {
25namespace 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.
73std::pair<tooling::Replacements, unsigned>
74reformat(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