Line data Source code
1 : // SPDX-FileCopyrightText: 2022-2025 Paul Colby <git@colby.id.au>
2 : // SPDX-License-Identifier: LGPL-3.0-or-later
3 :
4 : #include "abstractcommand.h"
5 : #include "../stringliterals_p.h"
6 :
7 : #include <qtpokit/pokitdevice.h>
8 : #include <qtpokit/pokitdiscoveryagent.h>
9 :
10 : #include <QLocale>
11 : #include <QTimer>
12 :
13 : #include <cmath>
14 : #include <ratio>
15 :
16 : DOKIT_USE_STRINGLITERALS
17 :
18 : /*!
19 : * \class AbstractCommand
20 : *
21 : * The AbstractCommand class provides a consistent base for the classes that implement CLI commands.
22 : */
23 :
24 : /*!
25 : * Constructs a new command with \a parent.
26 : */
27 53099 : AbstractCommand::AbstractCommand(QObject * const parent) : QObject(parent),
28 53099 : discoveryAgent(new PokitDiscoveryAgent(this))
29 18813 : {
30 56810 : connect(discoveryAgent, &PokitDiscoveryAgent::pokitDeviceDiscovered,
31 30763 : this, &AbstractCommand::deviceDiscovered);
32 56810 : connect(discoveryAgent, &PokitDiscoveryAgent::finished,
33 30763 : this, &AbstractCommand::deviceDiscoveryFinished);
34 56810 : connect(discoveryAgent,
35 7377 : #if (QT_VERSION < QT_VERSION_CHECK(6, 2, 0))
36 7377 : QOverload<PokitDiscoveryAgent::Error>::of(&PokitDiscoveryAgent::error),
37 : #else
38 11436 : &PokitDiscoveryAgent::errorOccurred,
39 11436 : #endif
40 18992 : this, [](const PokitDiscoveryAgent::Error &error) {
41 724 : qCWarning(lc).noquote() << tr("Bluetooth discovery error:") << error;
42 147 : QTimer::singleShot(0, QCoreApplication::instance(), [](){
43 0 : QCoreApplication::exit(EXIT_FAILURE);
44 0 : });
45 308 : });
46 56810 : }
47 :
48 : /*!
49 : * Returns a list of CLI option names required by this command. The main console appication may
50 : * use this list to output an error (and exit) if any of the returned names are not found in the
51 : * parsed CLI options.
52 : *
53 : * The (already parsed) \a parser may be used adjust the returned required options depending on the
54 : * value of other options. For example, the `logger` command only requires the `--mode` option if
55 : * the `--command` option is `start`.
56 : *
57 : * This base implementation simply returns an empty list. Derived classes should override this
58 : * function to include any required options.
59 : */
60 24960 : QStringList AbstractCommand::requiredOptions(const QCommandLineParser &parser) const
61 15680 : {
62 15680 : Q_UNUSED(parser)
63 40640 : return QStringList();
64 15680 : }
65 :
66 : /*!
67 : * Returns a list of CLI option names supported by this command. The main console appication may
68 : * use this list to output a warning for any parsed CLI options not included in the returned list.
69 : *
70 : * The (already parsed) \a parser may be used adjust the returned supported options depending on the
71 : * value of other options. For example, the `logger` command only supported the `--timestamp` option
72 : * if the `--command` option is `start`.
73 : *
74 : * This base implementation simply returns requiredOptions(). Derived classes should override this
75 : * function to include optional options, such as:
76 : *
77 : * ```
78 : * QStringList Derived::supportedOptions(const QCommandLineParser &parser) const
79 : * {
80 : * const QStringList list = AbstractCommand::supportedOptions(parser) + QStringList{ ... };
81 : * list.sort();
82 : * list.removeDuplicates(); // Optional, recommended.
83 : * return list;
84 : * }
85 : * ```
86 : */
87 12160 : QStringList AbstractCommand::supportedOptions(const QCommandLineParser &parser) const
88 7616 : {
89 96080 : return requiredOptions(parser) + QStringList{
90 7616 : u"debug"_s,
91 7616 : u"device"_s, u"d"_s,
92 7616 : u"output"_s,
93 7616 : u"timeout"_s,
94 88328 : };
95 7616 : }
96 :
97 : /*!
98 : * Returns an RFC 4180 compliant version of \a field. That is, if \a field contains any of the
99 : * the below four characters, than any double quotes are escaped (by addition double-quotes), and
100 : * the string itself surrounded in double-quotes. Otherwise, \a field is returned verbatim.
101 : *
102 : * Some examples:
103 : * ```
104 : * QCOMPARE(escapeCsvField("abc"), "abc"); // Returned unchanged.
105 : * QCOMPARE(escapeCsvField("a,c"), R"("a,c")"); // Wrapped in double-quotes.
106 : * QCOMPARE(escapeCsvField(R"(a"c)"), R("("a""c")"); // Existing double-quotes doubled, then wrapped.
107 : * ```
108 : */
109 9305 : QString AbstractCommand::escapeCsvField(const QString &field)
110 3785 : {
111 36835 : if (field.contains(','_L1) || field.contains('\r'_L1) || field.contains('"'_L1) || field.contains('\n'_L1)) {
112 292 : return uR"("%1")"_s.arg(QString(field).replace('"'_L1, uR"("")"_s));
113 3673 : } else return field;
114 3785 : }
115 :
116 : /*!
117 : * \internal
118 : * A (run-time) class approximately equivalent to the compile-time std::ratio template.
119 : */
120 : struct Ratio {
121 : std::intmax_t num { 0 }; ///< Numerator.
122 : std::intmax_t den { 0 }; ///< Denominator.
123 : //! Returns \a true if both #num and #den are non-zero.
124 12040 : bool isValid() const { return (num != 0) && (den != 0); }
125 : };
126 :
127 : /*!
128 : * \internal
129 : * Returns a (run-time) Ratio representation of (compile-time) ratio \a R.
130 : */
131 11944 : template<typename R> constexpr Ratio makeRatio() { return Ratio{ R::num, R::den }; }
132 :
133 : /*!
134 : * Returns \a value as an integer multiple of the ratio \a R. The string \a value
135 : * may end with the optional \a unit, such as `V` or `s`, which may also be preceded with a SI unit
136 : * prefix such as `m` for `milli`. If \a value contains no SI unit prefix, then the result will be
137 : * multiplied by 1,000 enough times to be greater than \a sensibleMinimum. This allows for
138 : * convenient use like:
139 : *
140 : * ```
141 : * const quint32 timeout = parseNumber<std::milli>(parser.value("window"), 's', 500'000);
142 : * ```
143 : *
144 : * So that an unqualified period like "300" will be assumed to be 300 milliseconds, and not 300
145 : * microseconds, while a period like "1000" will be assume to be 1 second.
146 : *
147 : * If conversion fails for any reason, 0 is returned.
148 : */
149 : template<typename R>
150 10320 : quint32 AbstractCommand::parseNumber(const QString &value, const QString &unit, const quint32 sensibleMinimum)
151 5880 : {
152 16480 : static const QMap<QChar, Ratio> unitPrefixScaleMap {
153 5880 : { 'E'_L1, makeRatio<std::exa>() },
154 5880 : { 'P'_L1, makeRatio<std::peta>() },
155 5880 : { 'T'_L1, makeRatio<std::tera>() },
156 5880 : { 'G'_L1, makeRatio<std::giga>() },
157 5880 : { 'M'_L1, makeRatio<std::mega>() },
158 5880 : { 'K'_L1, makeRatio<std::kilo>() }, // Not official SI unit prefix, but commonly used.
159 5880 : { 'k'_L1, makeRatio<std::kilo>() },
160 5880 : { 'h'_L1, makeRatio<std::hecto>() },
161 5880 : { 'd'_L1, makeRatio<std::deci>() },
162 5880 : { 'c'_L1, makeRatio<std::centi>() },
163 5880 : { 'm'_L1, makeRatio<std::milli>() },
164 5880 : { 'u'_L1, makeRatio<std::micro>() }, // Not official SI unit prefix, but commonly used.
165 5880 : { QChar(0x00B5), makeRatio<std::micro>() }, // Unicode micro symbol (μ).
166 5880 : { 'n'_L1, makeRatio<std::nano>() },
167 5880 : { 'p'_L1, makeRatio<std::pico>() },
168 5880 : { 'f'_L1, makeRatio<std::femto>() },
169 5880 : { 'a'_L1, makeRatio<std::atto>() },
170 5880 : };
171 :
172 : // Remove the optional (whole) unit suffix.
173 5880 : Ratio ratio;
174 5880 : QString number = value.trimmed();
175 16200 : if ((!unit.isEmpty()) && (number.endsWith(unit, Qt::CaseInsensitive))) {
176 7880 : number.chop(unit.length());
177 2680 : ratio = makeRatio<std::ratio<1>>();
178 2680 : }
179 :
180 : // Parse, and remove, the optional SI unit prefix.
181 16200 : if (!number.isEmpty()) {
182 5524 : #if (QT_VERSION >= QT_VERSION_CHECK(5, 10, 0))
183 11028 : const QChar siPrefix = number.back(); // QString::back() introduced in Qt 5.10.
184 : #else
185 684 : const QChar siPrefix = number.at(number.size() - 1);
186 300 : #endif
187 5824 : const auto iter = unitPrefixScaleMap.constFind(siPrefix);
188 16064 : if (iter != unitPrefixScaleMap.constEnd()) {
189 2560 : Q_ASSERT(iter->isValid());
190 7680 : ratio = *iter;
191 7680 : number.chop(1);
192 2560 : }
193 5824 : }
194 :
195 6288 : #define DOKIT_RESULT(var) (var * ratio.num * R::den / ratio.den / R::num)
196 : // Parse the number as an (unsigned) integer.
197 16200 : QLocale locale; bool ok;
198 10653 : qulonglong integer = locale.toULongLong(number, &ok);
199 16200 : if (ok) {
200 10680 : if (integer == 0) {
201 56 : return 0;
202 56 : }
203 3664 : if (!ratio.isValid()) {
204 4336 : for (ratio = makeRatio<R>(); DOKIT_RESULT(integer) < sensibleMinimum; ratio.num *= 1000);
205 1096 : }
206 10544 : return (integer == 0) ? 0u : (quint32)DOKIT_RESULT(integer);
207 3720 : }
208 :
209 : // Parse the number as a (double) floating point number, and check that it is positive.
210 5520 : if (const double dbl = locale.toDouble(number, &ok); (ok) && (dbl > 0.0)) {
211 616 : if (!ratio.isValid()) {
212 952 : for (ratio = makeRatio<R>(); DOKIT_RESULT(dbl) < sensibleMinimum; ratio.num *= 1000);
213 280 : }
214 1496 : return static_cast<quint32>(std::llround(DOKIT_RESULT(dbl)));
215 616 : }
216 1544 : #undef DOKIT_RESULT
217 1544 : return 0; // Failed to parse as either integer, or float.
218 12480 : }
219 :
220 : #define DOKIT_INSTANTIATE_TEMPLATE_FUNCTION(type) template \
221 : quint32 AbstractCommand::parseNumber<type>(const QString &value, const QString &unit, const quint32 sensibleMinimum)
222 : DOKIT_INSTANTIATE_TEMPLATE_FUNCTION(std::exa);
223 : DOKIT_INSTANTIATE_TEMPLATE_FUNCTION(std::peta);
224 : DOKIT_INSTANTIATE_TEMPLATE_FUNCTION(std::tera);
225 : DOKIT_INSTANTIATE_TEMPLATE_FUNCTION(std::giga);
226 : DOKIT_INSTANTIATE_TEMPLATE_FUNCTION(std::mega);
227 : DOKIT_INSTANTIATE_TEMPLATE_FUNCTION(std::kilo);
228 : DOKIT_INSTANTIATE_TEMPLATE_FUNCTION(std::hecto);
229 : DOKIT_INSTANTIATE_TEMPLATE_FUNCTION(std::deca);
230 : DOKIT_INSTANTIATE_TEMPLATE_FUNCTION(std::ratio<1>);
231 : DOKIT_INSTANTIATE_TEMPLATE_FUNCTION(std::deci);
232 : DOKIT_INSTANTIATE_TEMPLATE_FUNCTION(std::centi);
233 : DOKIT_INSTANTIATE_TEMPLATE_FUNCTION(std::milli);
234 : DOKIT_INSTANTIATE_TEMPLATE_FUNCTION(std::micro);
235 : DOKIT_INSTANTIATE_TEMPLATE_FUNCTION(std::nano);
236 : DOKIT_INSTANTIATE_TEMPLATE_FUNCTION(std::pico);
237 : DOKIT_INSTANTIATE_TEMPLATE_FUNCTION(std::femto);
238 : DOKIT_INSTANTIATE_TEMPLATE_FUNCTION(std::atto);
239 : #undef DOKIT_INSTANTIATE_TEMPLATE_FUNCTION
240 :
241 : /*!
242 : * Processes the relevant options from the command line \a parser.
243 : *
244 : * On success, returns an empty QStringList, otherwise returns a list of CLI errors that the caller
245 : * should report appropriately before exiting.
246 : *
247 : * This base implementations performs some common checks, such as ensuring that required options are
248 : * present. Derived classes should override this function to perform further processing, typically
249 : * invoking this base implementation as a first step, such as:
250 : *
251 : * ```
252 : * QStringList CustomCommand::processOptions(const QCommandLineParser &parser)
253 : * {
254 : * QStringList errors = AbstractCommand::processOptions(parser);
255 : * if (!errors.isEmpty()) {
256 : * return errors;
257 : * }
258 : *
259 : * // Do further procession of options.
260 : *
261 : * return errors;
262 : * }
263 : * ```
264 : */
265 10480 : QStringList AbstractCommand::processOptions(const QCommandLineParser &parser)
266 6440 : {
267 : // Report any supplied options that are not supported by this command.
268 16920 : const QStringList suppliedOptionNames = parser.optionNames();
269 16920 : const QStringList supportedOptionNames = supportedOptions(parser);
270 41712 : for (const QString &option: suppliedOptionNames) {
271 31232 : if (!supportedOptionNames.contains(option)) {
272 288 : qCInfo(lc).noquote() << tr("Ignoring option: %1").arg(option);
273 56 : }
274 11392 : }
275 12073 : QStringList errors;
276 :
277 : // Parse the device (name/addr/uuid) option.
278 22553 : if (parser.isSet(u"device"_s)) {
279 358 : deviceToScanFor = parser.value(u"device"_s);
280 112 : }
281 :
282 : // Parse the output format options (if supported, and supplied).
283 30151 : if ((supportedOptionNames.contains(u"output"_s)) && // Derived classes may have removed.
284 25148 : (parser.isSet(u"output"_s)))
285 728 : {
286 2808 : const QString output = parser.value(u"output"_s).toLower();
287 1768 : if (output == u"csv"_s) {
288 408 : format = OutputFormat::Csv;
289 1360 : } else if (output == u"json"_s) {
290 408 : format = OutputFormat::Json;
291 952 : } else if (output == u"text"_s) {
292 408 : format = OutputFormat::Text;
293 224 : } else {
294 716 : errors.append(tr("Unknown output format: %1").arg(output));
295 224 : }
296 1209 : }
297 :
298 : // Parse the device scan timeout option.
299 22553 : if (parser.isSet(u"timeout"_s)) {
300 2444 : const quint32 timeout = parseNumber<std::milli>(parser.value(u"timeout"_s), u"s"_s, 500);
301 1768 : if (timeout == 0) {
302 1374 : errors.append(tr("Invalid timeout: %1").arg(parser.value(u"timeout"_s)));
303 952 : } else if (discoveryAgent->lowEnergyDiscoveryTimeout() == -1) {
304 945 : qCWarning(lc).noquote() << tr("Platform does not support Bluetooth scan timeout");
305 392 : } else {
306 546 : discoveryAgent->setLowEnergyDiscoveryTimeout(timeout);
307 665 : qCDebug(lc).noquote() << tr("Set scan timeout to %1").arg(
308 0 : discoveryAgent->lowEnergyDiscoveryTimeout());
309 329 : }
310 728 : }
311 :
312 : // Return errors for any required options that are absent.
313 16920 : const QStringList requiredOptionNames = this->requiredOptions(parser);
314 29896 : for (const QString &option: requiredOptionNames) {
315 19288 : if (!parser.isSet(option)) {
316 1841 : errors.append(tr("Missing required option: %1").arg(option));
317 488 : }
318 6888 : }
319 16920 : return errors;
320 6440 : }
321 :
322 : /*!
323 : * \fn virtual bool AbstractCommand::start()
324 : *
325 : * Begins the functionality of this command, and returns `true` if begun successfully, `false`
326 : * otherwise.
327 : */
328 :
329 : /*!
330 : * \fn virtual void AbstractCommand::deviceDiscovered(const QBluetoothDeviceInfo &info) = 0
331 : *
332 : * Handles PokitDiscoveryAgent::pokitDeviceDiscovered signal. Derived classes must
333 : * implement this slot to begin whatever actions are relevant when a Pokit device has been
334 : * discovered. For example, the 'scan' command would simply output the \a info details, whereas
335 : * most other commands would begin connecting if \a info is the device they're after.
336 : */
337 :
338 : /*!
339 : * \fn virtual void AbstractCommand::deviceDiscoveryFinished() = 0
340 : *
341 : * Handles PokitDiscoveryAgent::deviceDiscoveryFinished signal. Derived classes must
342 : * implement this slot to perform whatever actions are appropriate when discovery is finished.
343 : * For example, the 'scan' command would simply exit, whereas most other commands would verify that
344 : * an appropriate device was found.
345 : */
|
