1/*
2 SPDX-FileCopyrightText: 2019 Dominik Haumann <dhaumann@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KTEXTEDITOR_VARIABLE_H
8#define KTEXTEDITOR_VARIABLE_H
9
10#include <QStringList>
11#include <functional>
12
13namespace KTextEditor
14{
15class View;
16
17/**
18 * @brief Variable for variable expansion.
19 *
20 * @section variable_intro Introduction
21 *
22 * A Variable is used by the KTextEditor::Editor to expand variables, also
23 * know as expanding macros. A Variable itself is defined by the variable
24 * name() as well as a description() and a function that replaces the variable
25 * by its value.
26 *
27 * To register a Variable in the Editor use either Editor::registerVariableMatch()
28 * or Editor::registerPrefixMatch().
29 *
30 * @see KTextEditor::Editor, KTextEditor::Editor::registerVariableMatch(),
31 * KTextEditor::Editor::registerPrefixMatch()
32 * @author Dominik Haumann \<dhaumann@kde.org\>
33 */
34class Variable
35{
36public:
37 /**
38 * Function that is called to expand a variable in @p text.
39 * @param text
40 */
41 using ExpandFunction = std::function<QString(const QStringView &text, KTextEditor::View *view)>;
42
43 /**
44 * Constructs an invalid Variable, see isValid().
45 */
46 Variable() = default;
47
48 /**
49 * Constructor defining a Variable by its @p name, its @p description, and
50 * its function @p expansionFunc to expand a variable to its corresponding
51 * value. The parameter @p isPrefixMatch indicates whether this Variable
52 * represents an exact match (false) or a prefix match (true).
53 *
54 * @note The @p name should @e not be translated.
55 */
56 Variable(const QString &name, const QString &description, ExpandFunction expansionFunc, bool isPrefixMatch);
57
58 /**
59 * Copy constructor.
60 */
61 Variable(const Variable &copy) = default;
62
63 /**
64 * Assignment operator.
65 */
66 Variable &operator=(const Variable &copy) = default;
67
68 /**
69 * Returns true, if the name is non-empty and the function provided in the
70 * constructor is not a nullptr.
71 */
72 bool isValid() const;
73
74 /**
75 * Returns whether this Variable represents an exact match (false) or a
76 * prefix match (true).
77 */
78 bool isPrefixMatch() const;
79
80 /**
81 * Returns the @p name that was provided in the constructor.
82 * Depending on where the Variable is registered, this name is used to
83 * identify an exact match or a prefix match.
84 */
85 QString name() const;
86
87 /**
88 * Returns the description that was provided in the constructor.
89 */
90 QString description() const;
91
92 /**
93 * Expands the Variable to its value.
94 *
95 * As example for an exact match, a variable "CurerntDocument:Cursor:Line"
96 * uses the @p view to return the current line of the text cursor. In this
97 * case @p prefix equals the text of the variable itself, i.e.
98 * "CurerntDocument:Cursor:Line".
99 *
100 * As example of a prefix match, a variable "ENV:value" expands the
101 * environment value @e value, e.g. "ENV:HOME". In this case, the @p prefix
102 * equals the text "ENV:HOME" and @p view would be unused.
103 *
104 * @return the expanded variable.
105 */
106 QString evaluate(const QStringView &prefix, KTextEditor::View *view) const;
107
108private:
109 QString m_name;
110 QString m_description;
111 ExpandFunction m_function;
112 bool m_isPrefixMatch = false;
113};
114
115}
116
117#endif
118

source code of ktexteditor/src/utils/variable.h