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