Branch data Line data Source code
1 : : /******************************************************************************
2 : : ------------- Copyright (c) 2009-2023 H a r a l d A c h i t z ---------------
3 : : ---------- < h a r a l d dot a c h i t z at g m a i l dot c o m > ------------
4 : : ---- This Source Code Form is subject to the terms of the Mozilla Public -----
5 : : ---- License, v. 2.0. If a copy of the MPL was not distributed with this -----
6 : : ---------- file, You can obtain one at http://mozilla.org/MPL/2.0/. ----------
7 : : ******************************************************************************/
8 : :
9 : : #ifndef SL3_SQLCOMMAND_HPP
10 : : #define SL3_SQLCOMMAND_HPP
11 : :
12 : : #include <memory>
13 : : #include <string>
14 : :
15 : : #include <sl3/config.hpp>
16 : : #include <sl3/dataset.hpp>
17 : : #include <sl3/dbvalue.hpp>
18 : : #include <sl3/rowcallback.hpp>
19 : :
20 : : struct sqlite3;
21 : : struct sqlite3_stmt;
22 : :
23 : : namespace sl3
24 : : {
25 : :
26 : : namespace internal
27 : : {
28 : : class Connection;
29 : : }
30 : :
31 : : /**
32 : : * \brief A compiled SQL command
33 : : *
34 : : * This class holds a compiled SQL statement so that it can be reused.
35 : : *
36 : : * A command can have parameters.
37 : : *
38 : : */
39 : : class LIBSL3_API Command
40 : : {
41 : : friend class Database;
42 : : using Connection = std::shared_ptr<internal::Connection>;
43 : :
44 : : Command (Connection connection, const std::string& sql);
45 : :
46 : : Command (Connection connection,
47 : : const std::string& sql,
48 : : DbValues parameters);
49 : :
50 : : Command () = delete;
51 : : Command (const Command&) = delete;
52 : : Command operator= (const Command&) = delete;
53 : : Command operator= (Command&&) = delete;
54 : :
55 : : public:
56 : : /**
57 : : * \brief Move constructor.
58 : : *
59 : : * A command is movable
60 : : *
61 : : */
62 : : Command (Command&&);
63 : :
64 : : /**
65 : : * \brief Destructor.
66 : : *
67 : : * The destructor calls release.
68 : : */
69 : : ~Command (); // cause of unique pointer, check if protected is possible
70 : :
71 : : /**
72 : : * \brief Run the Command and get the result
73 : : *
74 : : * Runs the command, applying possible already given parameters
75 : : * and returns the result in a Dataset.
76 : : *
77 : : *
78 : : * \return A Dataset containing the query result
79 : : */
80 : : Dataset select ();
81 : :
82 : : /**
83 : : * \brief Run the Command and get the result
84 : : *
85 : : * Runs the command, applying given parameters
86 : : * and returns the result in a Dataset.
87 : : * If types are given, they are used for the returned Dataset.
88 : : * If no
89 : : * types are given all fields in the returned Dataset will be
90 : : * of
91 : : * Type::Variant
92 : : *
93 : : * \throw sl3::ErrTypeMisMatch if types are given which are invalid or
94 : : * given parameters are of the wrong size.
95 : : * \param parameters a list of parameters
96 : : * \param types Types the Dataset shall use
97 : : * \return A Dataset containing the query result
98 : : */
99 : : Dataset select (const DbValues& parameters, const Types& types = {});
100 : :
101 : : /**
102 : : * \brief Run the Command and get the result
103 : : *
104 : : * Runs the command, applying possible given parameters
105 : : * and returns the result in a Dataset in which given types are
106 : : * used for the fields.
107 : : *
108 : : * \throw sl3::ErrTypeMisMatch if types are given which are invalid or
109 : : * given parameters are of the wrong size.
110 : : * \param parameters a list of parameters
111 : : * \param types Types the Dataset shall use
112 : : * \return A Dataset containing the query result
113 : : */
114 : : Dataset select (const Types& types, const DbValues& parameters = {});
115 : :
116 : : /**
117 : : * \brief function object for handling a command result.
118 : : *
119 : : * Functor called for each processed row of Command or a
120 : : * sql statement.
121 : : *
122 : : * \return false if processing the query result shall stop
123 : : * \n true otherwise
124 : : */
125 : : using Callback = std::function<bool (Columns)>;
126 : :
127 : : /**
128 : : * \brief Execute the command
129 : : *
130 : : * Runs the current command.
131 : : * If parameters are set,
132 : : *
133 : : */
134 : : void execute ();
135 : :
136 : : /**
137 : : * \brief Execute the command
138 : : *
139 : : * Applies given parameters and run the current command.
140 : : *
141 : : * \throw sl3::ErrTypeMisMatch given parameters are of the wrong size.
142 : : * \param parameters a list of parameters
143 : : */
144 : : void execute (const DbValues& parameters);
145 : :
146 : : /**
147 : : * \brief Execute the command applying given callback
148 : : *
149 : : * Applies given parameters and run the current command.
150 : : *
151 : : * \throw sl3::ErrTypeMisMatch given parameters are of the wrong size.
152 : : * \param cb a callback
153 : : * \param parameters a list of parameters
154 : : */
155 : : void execute (RowCallback& cb, const DbValues& parameters = {});
156 : :
157 : : /**
158 : : * \brief Execute the command applying given callback
159 : : *
160 : : * Applies given parameters and run the current command.
161 : : *
162 : : * \throw sl3::ErrTypeMisMatch given parameters are of the wrong size.
163 : : * \param cb a callback
164 : : * \param parameters a list of parameters
165 : : */
166 : : void execute (Callback cb, const DbValues& parameters = {});
167 : :
168 : : /**
169 : : * \brief Parameters of command.
170 : : *
171 : : * \return reference to the parameters
172 : : */
173 : : DbValues& getParameters ();
174 : :
175 : : /**
176 : : * \brief Parameters of command.
177 : : *
178 : : * \return const reference to the parameters
179 : : */
180 : : const DbValues& getParameters () const;
181 : :
182 : : /**
183 : : * \brief get Parameter at given index.
184 : : * \param idx index
185 : : * \throw sl3::ErrOutOfRange if index is invalid
186 : : * \return reference to the parameters at given index
187 : : */
188 : : DbValue& getParameter (int idx);
189 : :
190 : : /**
191 : : * \brief get Parameter at given index.
192 : : * \param idx index
193 : : * \throw sl3::ErrOutOfRange if index is invalid
194 : : * \return const reference to the parameters at given index
195 : : */
196 : : const DbValue& getParameter (int idx) const;
197 : :
198 : : /**
199 : : * \brief Set parameter values
200 : : *
201 : : * The types of the given values must be compatible with the
202 : : * current
203 : : * ones.
204 : : *
205 : : * \param values new parameter values
206 : : * \throw sl3::ErrTypeMisMatch if
207 : : * size of values differs from the actual parameter size or DbValue
208 : : * assignment throws.
209 : : * \see DbValue
210 : : *
211 : : */
212 : : void setParameters (const DbValues& values);
213 : :
214 : : /**
215 : : * \brief Set new parameter values
216 : : *
217 : : * In contrast to setParameters, where the DbValue types must match,
218 : : * this can be used to set other Types.
219 : : *
220 : : * \param values new parameter values
221 : : * \throw sl3::ErrTypeMisMatch if size of values differs from the actual
222 : : * one
223 : : */
224 : : void resetParameters (DbValues values);
225 : :
226 : : /**
227 : : * \brief get a list of the parameter names
228 : : *
229 : : * If the command has no parameters, the list will be empty.
230 : : * Parameters with no name will be an empty entry in the list.
231 : : *
232 : : * \return list of names
233 : : */
234 : : std::vector<std::string> getParameterNames () const;
235 : :
236 : : private:
237 : : Connection _connection;
238 : : sqlite3_stmt* _stmt;
239 : : DbValues _parameters;
240 : : };
241 : :
242 : : // Branch coverage for that is a nightmare,
243 : : // cant come over 60% with all the boilerplate in commandsexttest.cpp
244 : : // LCOV_EXCL_BR_START
245 : : /**
246 : : * \brief Syntax sugar to create command parameters
247 : : *
248 : : * Creates DbValues with types based on the given arguments.
249 : : * \code
250 : : * cmd.execute(parameters(1,"foo",3.3))
251 : : * \endcode
252 : : * Will create DbValues of Type::Int, Type::Text and Type::Real
253 : : *
254 : : * \tparam VALS variadic argument types
255 : : * \param vals variadic argument values
256 : : *
257 : : * \return DbValues constructed by given arguments
258 : : */
259 : : template <typename... VALS>
260 : : DbValues
261 : 34 : parameters (VALS&&... vals)
262 : : {
263 : 108 : return {DbValue{vals}...};
264 : 68 : }
265 : : // LCOV_EXCL_BR_STOP
266 : : }
267 : :
268 : : #endif
|
