Line data Source code
1 : // SPDX-FileCopyrightText: 2022-2023 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 :
11 : #include <ratio>
12 :
13 : /*!
14 : * \class AbstractCommand
15 : *
16 : * The AbstractCommand class provides a consistent base for the classes that implement CLI commands.
17 : */
18 :
19 : /// \enum AbstractCommand::OutputFormat
20 : /// \brief Supported output formats.
21 :
22 : /*!
23 : * Constructs a new command with \a parent.
24 : */
25 8115 : AbstractCommand::AbstractCommand(QObject * const parent) : QObject(parent),
26 8115 : discoveryAgent(new PokitDiscoveryAgent(this))
27 : {
28 8115 : connect(discoveryAgent, &PokitDiscoveryAgent::pokitDeviceDiscovered,
29 : this, &AbstractCommand::deviceDiscovered);
30 8115 : connect(discoveryAgent, &PokitDiscoveryAgent::finished,
31 : this, &AbstractCommand::deviceDiscoveryFinished);
32 8115 : connect(discoveryAgent,
33 : #if (QT_VERSION < QT_VERSION_CHECK(6, 2, 0))
34 : QOverload<PokitDiscoveryAgent::Error>::of(&PokitDiscoveryAgent::error),
35 : #else
36 : &PokitDiscoveryAgent::errorOccurred,
37 : #endif
38 48 : [](const PokitDiscoveryAgent::Error &error) {
39 96 : qCWarning(lc).noquote() << tr("Bluetooth controller error:") << error;
40 48 : QCoreApplication::exit(EXIT_FAILURE);
41 48 : });
42 8115 : }
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 5138 : QStringList AbstractCommand::requiredOptions(const QCommandLineParser &parser) const
57 : {
58 : Q_UNUSED(parser)
59 5138 : 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 2506 : QStringList AbstractCommand::supportedOptions(const QCommandLineParser &parser) const
84 : {
85 18412 : return requiredOptions(parser) + QStringList{
86 : QLatin1String("debug"),
87 : QLatin1String("device"), QLatin1String("d"),
88 : QLatin1String("output"),
89 : QLatin1String("timeout"),
90 17397 : };
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 1665 : QString AbstractCommand::escapeCsvField(const QString &field)
106 : {
107 1647 : if (field.contains(QLatin1Char(','))||field.contains(QLatin1Char('\r'))||
108 4941 : field.contains(QLatin1Char('"'))||field.contains(QLatin1Char('\n')))
109 : {
110 44 : return QString::fromLatin1(R"("%1")").arg(
111 36 : 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 1690 : 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*1000);
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 2218 : quint32 AbstractCommand::parseNumber(const QString &value, const QString &unit, const quint32 sensibleMinimum)
150 : {
151 2278 : 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 2218 : if ((!unit.isEmpty()) && (number.endsWith(unit, Qt::CaseInsensitive))) {
175 1138 : number.chop(unit.length());
176 : ratio = makeRatio<std::ratio<1>>();
177 : }
178 :
179 : // Parse, and remove, the optional SI unit prefix.
180 2218 : if (!number.isEmpty()) {
181 : #if (QT_VERSION >= QT_VERSION_CHECK(5, 10, 0))
182 512 : 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 2208 : if (iter != unitPrefixScaleMap.constEnd()) {
188 : Q_ASSERT(iter->isValid());
189 1128 : ratio = *iter;
190 1128 : 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 2218 : QLocale locale; bool ok;
197 1702 : qulonglong integer = locale.toULongLong(number, &ok);
198 2218 : if (ok) {
199 1502 : if (integer == 0) {
200 : return 0;
201 : }
202 : if (!ratio.isValid()) {
203 572 : for (ratio = makeRatio<R>(); DOKIT_RESULT(integer) < sensibleMinimum; ratio.num *= 1000);
204 : }
205 1492 : 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 716 : if ((ok) && (dbl > 0.0)) {
211 : if (!ratio.isValid()) {
212 126 : for (ratio = makeRatio<R>(); DOKIT_RESULT(dbl) < sensibleMinimum; ratio.num *= 1000);
213 : }
214 198 : return (quint32)DOKIT_RESULT(dbl);
215 : }
216 : #undef DOKIT_RESULT
217 : return 0; // Failed to parse as either integer, or float.
218 2218 : }
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 2164 : QStringList AbstractCommand::processOptions(const QCommandLineParser &parser)
266 : {
267 : // Report any supplied options that are not supported by this command.
268 2164 : const QStringList suppliedOptionNames = parser.optionNames();
269 2164 : const QStringList supportedOptionNames = supportedOptions(parser);
270 6348 : for (const QString &option: suppliedOptionNames) {
271 4184 : if (!supportedOptionNames.contains(option)) {
272 40 : qCInfo(lc).noquote() << tr("Ignoring option: %1").arg(option);
273 : }
274 : }
275 504 : QStringList errors;
276 :
277 : // Parse the device (name/addr/uuid) option.
278 2668 : if (parser.isSet(QLatin1String("device"))) {
279 44 : deviceToScanFor = parser.value(QLatin1String("device"));
280 : }
281 :
282 : // Parse the output format options (if supported, and supplied).
283 3811 : if ((supportedOptionNames.contains(QLatin1String("output"))) && // Derived classes may have removed.
284 4024 : (parser.isSet(QLatin1String("output"))))
285 : {
286 468 : const QString output = parser.value(QLatin1String("output")).toLower();
287 234 : if (output == QLatin1String("csv")) {
288 54 : format = OutputFormat::Csv;
289 180 : } else if (output == QLatin1String("json")) {
290 54 : format = OutputFormat::Json;
291 126 : } else if (output == QLatin1String("text")) {
292 54 : format = OutputFormat::Text;
293 : } else {
294 88 : errors.append(tr("Unknown output format: %1").arg(output));
295 : }
296 182 : }
297 :
298 : // Parse the device scan timeout option.
299 2668 : if (parser.isSet(QLatin1String("timeout"))) {
300 182 : const quint32 timeout = parseNumber<std::milli>(parser.value(QLatin1String("timeout")), QLatin1String("s"), 500);
301 130 : if (timeout == 0) {
302 120 : errors.append(tr("Invalid timeout: %1").arg(parser.value(QLatin1String("timeout"))));
303 : } else {
304 70 : discoveryAgent->setLowEnergyDiscoveryTimeout(timeout);
305 70 : qCDebug(lc).noquote() << tr("Set scan timeout to %1").arg(
306 0 : discoveryAgent->lowEnergyDiscoveryTimeout());
307 : }
308 : }
309 :
310 : // Return errors for any required options that are absent.
311 2164 : const QStringList requiredOptionNames = this->requiredOptions(parser);
312 4760 : for (const QString &option: requiredOptionNames) {
313 2596 : if (!parser.isSet(option)) {
314 220 : errors.append(tr("Missing required option: %1").arg(option));
315 : }
316 : }
317 2164 : return errors;
318 : }
319 :
320 : /*!
321 : * \fn virtual bool AbstractCommand::start()
322 : *
323 : * Begins the functionality of this command, and returns `true` if begun successfully, `false`
324 : * otherwise.
325 : */
326 :
327 : /*!
328 : * \fn virtual void AbstractCommand::deviceDiscovered(const QBluetoothDeviceInfo &info) = 0
329 : *
330 : * Handles PokitDiscoveryAgent::pokitDeviceDiscovered signal. Derived classes must
331 : * implement this slot to begin whatever actions are relevant when a Pokit device has been
332 : * discovered. For example, the 'scan' command would simply output the \a info details, whereas
333 : * most other commands would begin connecting if \a info is the device they're after.
334 : */
335 :
336 : /*!
337 : * \fn virtual void AbstractCommand::deviceDiscoveryFinished() = 0
338 : *
339 : * Handles PokitDiscoveryAgent::deviceDiscoveryFinished signal. Derived classes must
340 : * implement this slot to perform whatever actions are appropraite when discovery is finished.
341 : * For example, the 'scan' command would simply exit, whereas most other commands would verify that
342 : * an appropriate device was found.
343 : */
|
