Line data Source code
1 : // SPDX-FileCopyrightText: 2022-2024 Paul Colby <git@colby.id.au>
2 : // SPDX-License-Identifier: LGPL-3.0-or-later
3 :
4 : #include "abstractcommand.h"
5 :
6 : #include <qtpokit/pokitdevice.h>
7 : #include <qtpokit/pokitdiscoveryagent.h>
8 :
9 : #include <QLocale>
10 : #include <QTimer>
11 :
12 : #include <ratio>
13 :
14 : /*!
15 : * \class AbstractCommand
16 : *
17 : * The AbstractCommand class provides a consistent base for the classes that implement CLI commands.
18 : */
19 :
20 : /*!
21 : * Constructs a new command with \a parent.
22 : */
23 9305 : AbstractCommand::AbstractCommand(QObject * const parent) : QObject(parent),
24 9305 : discoveryAgent(new PokitDiscoveryAgent(this))
25 : {
26 9305 : connect(discoveryAgent, &PokitDiscoveryAgent::pokitDeviceDiscovered,
27 478 : this, &AbstractCommand::deviceDiscovered);
28 9305 : connect(discoveryAgent, &PokitDiscoveryAgent::finished,
29 478 : this, &AbstractCommand::deviceDiscoveryFinished);
30 9305 : connect(discoveryAgent,
31 : #if (QT_VERSION < QT_VERSION_CHECK(6, 2, 0))
32 : QOverload<PokitDiscoveryAgent::Error>::of(&PokitDiscoveryAgent::error),
33 : #else
34 : &PokitDiscoveryAgent::errorOccurred,
35 : #endif
36 54 : this, [](const PokitDiscoveryAgent::Error &error) {
37 114 : qCWarning(lc).noquote() << tr("Bluetooth discovery error:") << error;
38 3 : QTimer::singleShot(0, QCoreApplication::instance(), [](){
39 0 : QCoreApplication::exit(EXIT_FAILURE);
40 : });
41 54 : });
42 9305 : }
43 :
44 : /*!
45 : * Returns a list of CLI option names required by this command. The main console appication may
46 : * use this list to output an eror (and exit) if any of the returned names are not found in the
47 : * parsed CLI options.
48 : *
49 : * The (already parsed) \a parser may be used adjust the returned required options depending on the
50 : * value of other options. For example, the `logger` command only requires the `--mode` option if
51 : * the `--command` option is `start`.
52 : *
53 : * This base implementation simply returns an empty list. Derived classes should override this
54 : * function to include any required options.
55 : */
56 6032 : QStringList AbstractCommand::requiredOptions(const QCommandLineParser &parser) const
57 : {
58 : Q_UNUSED(parser)
59 6032 : return QStringList();
60 : }
61 :
62 : /*!
63 : * Returns a list of CLI option names supported by this command. The main console appication may
64 : * use this list to output a warning for any parsed CLI options not included in the returned list.
65 : *
66 : * The (already parsed) \a parser may be used adjust the returned supported options depending on the
67 : * value of other options. For example, the `logger` command only supported the `--timestamp` option
68 : * if the `--command` option is `start`.
69 : *
70 : * This base implementation simply returns requiredOptions(). Derived classes should override this
71 : * function to include optional options, such as:
72 : *
73 : * ```
74 : * QStringList Derived::supportedOptions(const QCommandLineParser &parser) const
75 : * {
76 : * const QStringList list = AbstractCommand::supportedOptions(parser) + QStringList{ ... };
77 : * list.sort();
78 : * list.removeDuplicates(); // Optional, recommended.
79 : * return list;
80 : * }
81 : * ```
82 : */
83 2936 : QStringList AbstractCommand::supportedOptions(const QCommandLineParser &parser) const
84 : {
85 21464 : return requiredOptions(parser) + QStringList{
86 : QLatin1String("debug"),
87 : QLatin1String("device"), QLatin1String("d"),
88 : QLatin1String("output"),
89 : QLatin1String("timeout"),
90 20248 : };
91 0 : }
92 :
93 : /*!
94 : * Returns an RFC 4180 compliant version of \a field. That is, if \a field contains any of the
95 : * the below four characters, than any double quotes are escaped (by addition double-quotes), and
96 : * the string itself surrounded in double-quotes. Otherwise, \a field is returned verbatim.
97 : *
98 : * Some examples:
99 : * ```
100 : * QCOMPARE(escapeCsvField("abc"), "abc"); // Returned unchanged.
101 : * QCOMPARE(escapeCsvField("a,c"), R"("a,c")"); // Wrapped in double-quotes.
102 : * QCOMPARE(escapeCsvField(R"(a"c)"), R("("a""c")"); // Existing double-quotes doubled, then wrapped.
103 : * ```
104 : */
105 2005 : QString AbstractCommand::escapeCsvField(const QString &field)
106 : {
107 1985 : if (field.contains(QLatin1Char(','))||field.contains(QLatin1Char('\r'))||
108 5955 : field.contains(QLatin1Char('"'))||field.contains(QLatin1Char('\n')))
109 : {
110 52 : return QString::fromLatin1(R"("%1")").arg(
111 40 : QString(field).replace(QLatin1Char('"'), QLatin1String(R"("")")));
112 : } else return field;
113 : }
114 :
115 : /*!
116 : * \internal
117 : * A (run-time) class approximately equivalent to the compile-time std::ratio template.
118 : */
119 : struct Ratio {
120 : std::intmax_t num { 0 }; ///< Numerator.
121 : std::intmax_t den { 0 }; ///< Denominator.
122 : //! Returns \a true if both #num and #den are non-zero.
123 1884 : bool isValid() const { return (num != 0) && (den != 0); }
124 : };
125 :
126 : /*!
127 : * \internal
128 : * Returns a (run-time) Ratio representation of (compile-time) ratio \a R.
129 : */
130 : template<typename R> constexpr Ratio makeRatio() { return Ratio{ R::num, R::den }; }
131 :
132 : /*!
133 : * Returns \a value as an integer multiple of the ratio \a R. The string \a value
134 : * may end with the optional \a unit, such as `V` or `s`, which may also be preceded with a SI unit
135 : * prefix such as `m` for `milli`. If \a value contains no SI unit prefix, then the result will be
136 : * multiplied by 1,000 enough times to be greater than \a sensibleMinimum. This allows for
137 : * convenient use like:
138 : *
139 : * ```
140 : * const quint32 timeout = parseNumber<std::milli>(parser.value("window"), 's', 500'000);
141 : * ```
142 : *
143 : * So that an unqalified period like "300" will be assumed to be 300 milliseconds, and not 300
144 : * microseconds, while a period like "1000" will be assume to be 1 second.
145 : *
146 : * If conversion fails for any reason, 0 is returned.
147 : */
148 : template<typename R>
149 2476 : quint32 AbstractCommand::parseNumber(const QString &value, const QString &unit, const quint32 sensibleMinimum)
150 : {
151 2536 : static const QMap<QChar, Ratio> unitPrefixScaleMap {
152 : { QLatin1Char('E'), makeRatio<std::exa>() },
153 : { QLatin1Char('P'), makeRatio<std::peta>() },
154 : { QLatin1Char('T'), makeRatio<std::tera>() },
155 : { QLatin1Char('G'), makeRatio<std::giga>() },
156 : { QLatin1Char('M'), makeRatio<std::mega>() },
157 : { QLatin1Char('K'), makeRatio<std::kilo>() }, // Not official SI unit prefix, but commonly used.
158 : { QLatin1Char('k'), makeRatio<std::kilo>() },
159 : { QLatin1Char('h'), makeRatio<std::hecto>() },
160 : { QLatin1Char('d'), makeRatio<std::deci>() },
161 : { QLatin1Char('c'), makeRatio<std::centi>() },
162 : { QLatin1Char('m'), makeRatio<std::milli>() },
163 : { QLatin1Char('u'), makeRatio<std::micro>() }, // Not official SI unit prefix, but commonly used.
164 : { QChar (0x00B5), makeRatio<std::micro>() }, // Unicode micro symbol (μ).
165 : { QLatin1Char('n'), makeRatio<std::nano>() },
166 : { QLatin1Char('p'), makeRatio<std::pico>() },
167 : { QLatin1Char('f'), makeRatio<std::femto>() },
168 : { QLatin1Char('a'), makeRatio<std::atto>() },
169 : };
170 :
171 : // Remove the optional (whole) unit suffix.
172 : Ratio ratio;
173 : QString number = value.trimmed();
174 2476 : if ((!unit.isEmpty()) && (number.endsWith(unit, Qt::CaseInsensitive))) {
175 1268 : number.chop(unit.length());
176 : ratio = makeRatio<std::ratio<1>>();
177 : }
178 :
179 : // Parse, and remove, the optional SI unit prefix.
180 2476 : if (!number.isEmpty()) {
181 : #if (QT_VERSION >= QT_VERSION_CHECK(5, 10, 0))
182 768 : const QChar siPrefix = number.back(); // QString::back() introduced in Qt 5.10.
183 : #else
184 244 : const QChar siPrefix = number.at(number.size() - 1);
185 : #endif
186 : const auto iter = unitPrefixScaleMap.constFind(siPrefix);
187 2464 : if (iter != unitPrefixScaleMap.constEnd()) {
188 : Q_ASSERT(iter->isValid());
189 1256 : ratio = *iter;
190 1256 : number.chop(1);
191 : }
192 : }
193 :
194 : #define DOKIT_RESULT(var) (var * ratio.num * R::den / ratio.den / R::num)
195 : // Parse the number as an (unsigned) integer.
196 2476 : QLocale locale; bool ok;
197 1702 : qulonglong integer = locale.toULongLong(number, &ok);
198 2476 : if (ok) {
199 1676 : if (integer == 0) {
200 : return 0;
201 : }
202 : if (!ratio.isValid()) {
203 640 : for (ratio = makeRatio<R>(); DOKIT_RESULT(integer) < sensibleMinimum; ratio.num *= 1000);
204 : }
205 1664 : return (integer == 0) ? 0u : (quint32)DOKIT_RESULT(integer);
206 : }
207 :
208 : // Parse the number as a (double) floating point number, and check that it is positive.
209 548 : const double dbl = locale.toDouble(number, &ok);
210 800 : if ((ok) && (dbl > 0.0)) {
211 : if (!ratio.isValid()) {
212 140 : for (ratio = makeRatio<R>(); DOKIT_RESULT(dbl) < sensibleMinimum; ratio.num *= 1000);
213 : }
214 220 : return (quint32)DOKIT_RESULT(dbl);
215 : }
216 : #undef DOKIT_RESULT
217 : return 0; // Failed to parse as either integer, or float.
218 2476 : }
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 : * inovking 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 2516 : QStringList AbstractCommand::processOptions(const QCommandLineParser &parser)
266 : {
267 : // Report any supplied options that are not supported by this command.
268 2516 : const QStringList suppliedOptionNames = parser.optionNames();
269 2516 : const QStringList supportedOptionNames = supportedOptions(parser);
270 7268 : for (const QString &option: suppliedOptionNames) {
271 4752 : if (!supportedOptionNames.contains(option)) {
272 48 : qCInfo(lc).noquote() << tr("Ignoring option: %1").arg(option);
273 : }
274 : }
275 786 : QStringList errors;
276 :
277 : // Parse the device (name/addr/uuid) option.
278 3302 : if (parser.isSet(QLatin1String("device"))) {
279 52 : deviceToScanFor = parser.value(QLatin1String("device"));
280 : }
281 :
282 : // Parse the output format options (if supported, and supplied).
283 4495 : if ((supportedOptionNames.contains(QLatin1String("output"))) && // Derived classes may have removed.
284 4954 : (parser.isSet(QLatin1String("output"))))
285 : {
286 520 : const QString output = parser.value(QLatin1String("output")).toLower();
287 260 : if (output == QLatin1String("csv")) {
288 60 : format = OutputFormat::Csv;
289 200 : } else if (output == QLatin1String("json")) {
290 60 : format = OutputFormat::Json;
291 140 : } else if (output == QLatin1String("text")) {
292 60 : format = OutputFormat::Text;
293 : } else {
294 104 : errors.append(tr("Unknown output format: %1").arg(output));
295 : }
296 182 : }
297 :
298 : // Parse the device scan timeout option.
299 3302 : if (parser.isSet(QLatin1String("timeout"))) {
300 234 : const quint32 timeout = parseNumber<std::milli>(parser.value(QLatin1String("timeout")), QLatin1String("s"), 500);
301 156 : if (timeout == 0) {
302 144 : errors.append(tr("Invalid timeout: %1").arg(parser.value(QLatin1String("timeout"))));
303 84 : } else if (discoveryAgent->lowEnergyDiscoveryTimeout() == -1) {
304 0 : qCWarning(lc).noquote() << tr("Platform does not support Bluetooth scan timeout");
305 : } else {
306 84 : discoveryAgent->setLowEnergyDiscoveryTimeout(timeout);
307 98 : qCDebug(lc).noquote() << tr("Set scan timeout to %1").arg(
308 0 : discoveryAgent->lowEnergyDiscoveryTimeout());
309 : }
310 : }
311 :
312 : // Return errors for any required options that are absent.
313 2516 : const QStringList requiredOptionNames = this->requiredOptions(parser);
314 5512 : for (const QString &option: requiredOptionNames) {
315 2996 : if (!parser.isSet(option)) {
316 286 : errors.append(tr("Missing required option: %1").arg(option));
317 : }
318 : }
319 2516 : return errors;
320 : }
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 appropraite 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 : */
|
