KTextEditor

variable.h
1 /*
2  SPDX-FileCopyrightText: 2019 Dominik Haumann <[email protected]>
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 
13 namespace KTextEditor
14 {
15 class 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 <[email protected]>
33  */
34 class Variable
35 {
36 public:
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 
108 private:
109  QString m_name;
110  QString m_description;
111  ExpandFunction m_function;
112  bool m_isPrefixMatch = false;
113 };
114 
115 }
116 
117 #endif
Variable()=default
Constructs an invalid Variable, see isValid().
QString description() const
Returns the description that was provided in the constructor.
Definition: variable.cpp:34
bool isValid() const
Returns true, if the name is non-empty and the function provided in the constructor is not a nullptr.
Definition: variable.cpp:19
A text widget with KXMLGUIClient that represents a Document.
Definition: view.h:146
Variable for variable expansion.
Definition: variable.h:34
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
Definition: katetextblock.h:22
QString name() const
Returns the name that was provided in the constructor.
Definition: variable.cpp:29
bool isPrefixMatch() const
Returns whether this Variable represents an exact match (false) or a prefix match (true).
Definition: variable.cpp:24
QString evaluate(const QStringView &prefix, KTextEditor::View *view) const
Expands the Variable to its value.
Definition: variable.cpp:39
std::function< QString(const QStringView &text, KTextEditor::View *view)> ExpandFunction
Function that is called to expand a variable in text.
Definition: variable.h:41
Variable & operator=(const Variable &copy)=default
Assignment operator.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon May 8 2023 03:50:23 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.