Changeset View
Changeset View
Standalone View
Standalone View
src/utils/variable.h
- This file was added.
1 | /* This file is part of the KDE project | ||||
---|---|---|---|---|---|
2 | Copyright (C) 2019 Dominik Haumann <dhaumann@kde.org> | ||||
3 | | ||||
4 | This library is free software; you can redistribute it and/or | ||||
5 | modify it under the terms of the GNU Library General Public | ||||
6 | License as published by the Free Software Foundation; either | ||||
7 | version 2 of the License, or (at your option) any later version. | ||||
8 | | ||||
9 | This library is distributed in the hope that it will be useful, | ||||
10 | but WITHOUT ANY WARRANTY; without even the implied warranty of | ||||
11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||||
12 | Library General Public License for more details. | ||||
13 | | ||||
14 | You should have received a copy of the GNU Library General Public License | ||||
15 | along with this library; see the file COPYING.LIB. If not, write to | ||||
16 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, | ||||
17 | Boston, MA 02110-1301, USA. | ||||
18 | */ | ||||
19 | | ||||
20 | #ifndef KTEXTEDITOR_VARIABLE_H | ||||
21 | #define KTEXTEDITOR_VARIABLE_H | ||||
22 | | ||||
23 | #include <QStringList> | ||||
24 | #include <QVariant> | ||||
25 | | ||||
26 | namespace KTextEditor | ||||
27 | { | ||||
28 | class View; | ||||
29 | | ||||
30 | /** | ||||
31 | * @brief Variable for variable expansion. | ||||
32 | * | ||||
33 | * @section variable_intro Introduction | ||||
34 | * | ||||
35 | * A Variable is used by the KTextEditor::Editor to expand variables, also | ||||
36 | * know as expanding macros. A Variable itself is defined by the variable | ||||
37 | * name() as well as a description() and a function that replaces the variable | ||||
38 | * by its value. | ||||
39 | * | ||||
40 | * To register a Variable in the Editor use either Editor::registerVariableMatch() | ||||
41 | * or Editor::registerPrefixMatch(). | ||||
42 | * | ||||
43 | * @see KTextEditor::Editor, KTextEditor::Editor::registerVariableMatch(), | ||||
44 | * KTextEditor::Editor::registerPrefixMatch() | ||||
45 | * @author Dominik Haumann \<dhaumann@kde.org\> | ||||
46 | */ | ||||
47 | class Variable | ||||
48 | { | ||||
49 | public: | ||||
50 | /** | ||||
51 | * Function that is called to expand a variable in @p text. | ||||
52 | * @param text | ||||
53 | */ | ||||
54 | using ExpandFunction = QString (*)(const QStringView& text, KTextEditor::View* view); | ||||
55 | | ||||
56 | /** | ||||
57 | * Constructor defining a Variable by its @p name, its @p description, and | ||||
58 | * its function @p expansionFunc to expand a variable to its corresponding | ||||
59 | * value. | ||||
60 | * | ||||
61 | * @note The @p name should @e not be translated. | ||||
62 | */ | ||||
63 | Variable(const QString& name, const QString& description, ExpandFunction expansionFunc); | ||||
64 | | ||||
65 | /** | ||||
66 | * Returns true, if the name is non-empty and the function provided in the | ||||
67 | * constructor is not a nullptr. | ||||
68 | */ | ||||
69 | bool isValid() const; | ||||
70 | | ||||
71 | /** | ||||
72 | * Returns the @p name that was provided in the constructor. | ||||
73 | * Depending on where the Variable is registered, this name is used to | ||||
74 | * identify an exact match or a prefix match. | ||||
75 | */ | ||||
76 | QString name() const; | ||||
77 | | ||||
78 | /** | ||||
79 | * Returns the description that was provided in the constructor. | ||||
80 | */ | ||||
81 | QString description() const; | ||||
82 | | ||||
83 | /** | ||||
84 | * Expands the Variable to its value. | ||||
85 | * | ||||
86 | * As example for an exact match, a variable "CurerntDocument:Cursor:Line" | ||||
87 | * uses the @p view to return the current line of the text cursor. In this | ||||
88 | * case @p prefix equals the text of the variable itself, i.e. | ||||
89 | * "CurerntDocument:Cursor:Line". | ||||
90 | * | ||||
91 | * As example of a prefix match, a variable "ENV:value" expands the | ||||
92 | * environment value @e value, e.g. "ENV:HOME". In this case, the @p prefix | ||||
93 | * equals the text "ENV:HOME" and @p view would be unused. | ||||
94 | * | ||||
95 | * @return the expanded variable. | ||||
96 | */ | ||||
97 | QString evaluate(const QStringView& prefix, KTextEditor::View * view) const; | ||||
98 | | ||||
99 | private: | ||||
100 | QString m_name; | ||||
101 | QString m_description; | ||||
102 | ExpandFunction m_function; | ||||
103 | }; | ||||
104 | | ||||
105 | } | ||||
106 | | ||||
107 | #endif |