AbstractCommand Class Reference

The AbstractCommand class provides a consistent base for the classes that implement CLI commands. More...

Inheritance diagram for AbstractCommand:

Collaboration diagram for AbstractCommand:

Public Types
enum class	OutputFormat { Csv , Json , Text }
	Supported output formats. More...

Public Slots
virtual QStringList	processOptions (const QCommandLineParser &parser)
	Processes the relevant options from the command line parser.
virtual bool	start ()=0
	Begins the functionality of this command, and returns true if begun successfully, false otherwise.

Public Member Functions
	AbstractCommand (QObject *const parent=nullptr)
	Constructs a new command with parent.
virtual QStringList	requiredOptions (const QCommandLineParser &parser) const
	Returns a list of CLI option names required by this command.
virtual QStringList	supportedOptions (const QCommandLineParser &parser) const
	Returns a list of CLI option names supported by this command.
Public Member Functions inherited from QObject
virtual const QMetaObject *	metaObject () const const
	QObject (QObject *parent)
virtual bool	event (QEvent *e)
virtual bool	eventFilter (QObject *watched, QEvent *event)
QString	objectName () const const
void	setObjectName (const QString &name)
bool	isWidgetType () const const
bool	isWindowType () const const
bool	signalsBlocked () const const
bool	blockSignals (bool block)
QThread *	thread () const const
void	moveToThread (QThread *targetThread)
int	startTimer (int interval, Qt::TimerType timerType)
int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)
void	killTimer (int id)
T	findChild (const QString &name, Qt::FindChildOptions options) const const
QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const const
QList< T >	findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const
QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
const QObjectList &	children () const const
void	setParent (QObject *parent)
void	installEventFilter (QObject *filterObj)
void	removeEventFilter (QObject *obj)
QMetaObject::Connection	connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
bool	disconnect (const char *signal, const QObject *receiver, const char *method) const const
bool	disconnect (const QObject *receiver, const char *method) const const
void	dumpObjectTree ()
void	dumpObjectInfo ()
void	dumpObjectTree () const const
void	dumpObjectInfo () const const
bool	setProperty (const char *name, const QVariant &value)
QVariant	property (const char *name) const const
QList< QByteArray >	dynamicPropertyNames () const const
void	destroyed (QObject *obj)
void	objectNameChanged (const QString &objectName)
QObject *	parent () const const
bool	inherits (const char *className) const const
void	deleteLater ()
	Q_DISABLE_COPY (Class)
	Q_DISABLE_MOVE (Class)
	Q_DISABLE_COPY_MOVE (Class)
T	qobject_cast (QObject *object)
T	qobject_cast (const QObject *object)
T	qFindChild (const QObject *obj, const QString &name)
QList< T >	qFindChildren (const QObject *obj, const QString &name)
QList< T >	qFindChildren (const QObject *obj, const QRegExp &regExp)
	Q_CLASSINFO (Name, Value)
	Q_INTERFACES (...)
	Q_PROPERTY (...)
	Q_ENUMS (...)
	Q_FLAGS (...)
	Q_ENUM (...)
	Q_FLAG (...)
	Q_ENUM_NS (...)
	Q_FLAG_NS (...)
	Q_OBJECT Q_OBJECT
	Q_GADGET Q_GADGET
	Q_NAMESPACE Q_NAMESPACE
	Q_NAMESPACE_EXPORT (EXPORT_MACRO)
	Q_SIGNALS Q_SIGNALS
	Q_SIGNAL Q_SIGNAL
	Q_SLOTS Q_SLOTS
	Q_SLOT Q_SLOT
	Q_EMIT Q_EMIT
	Q_INVOKABLE Q_INVOKABLE
	Q_REVISION Q_REVISION
	Q_SET_OBJECT_NAME (Object)
	QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT

Static Public Member Functions
static QString	escapeCsvField (const QString &field)
	Returns an RFC 4180 compliant version of field.
template<typename R >
static quint32	parseNumber (const QString &value, const QString &unit, const quint32 sensibleMinimum=0)
	Returns value as an integer multiple of the ratio R.
Static Public Member Functions inherited from QObject
QString	tr (const char *sourceText, const char *disambiguation, int n)
QString	trUtf8 (const char *sourceText, const char *disambiguation, int n)
QMetaObject::Connection	connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
QMetaObject::Connection	connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
bool	disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
bool	disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
bool	disconnect (const QMetaObject::Connection &connection)
bool	disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)

Protected Slots
virtual void	deviceDiscovered (const QBluetoothDeviceInfo &info)=0
	Handles PokitDiscoveryAgent::pokitDeviceDiscovered signal.
virtual void	deviceDiscoveryFinished ()=0
	Handles PokitDiscoveryAgent::deviceDiscoveryFinished signal.

Static Protected Member Functions
static	Q_LOGGING_CATEGORY (lc, "dokit.cli.command", QtInfoMsg)
	Logging category for UI commands.

Protected Attributes
QString	deviceToScanFor
	Device (if any) that were passed to processOptions().
PokitDiscoveryAgent *	discoveryAgent
	Agent for Pokit device descovery.
OutputFormat	format { OutputFormat::Text }
	Selected output format.

Friends
class	TestAbstractCommand

Additional Inherited Members
Public Attributes inherited from QObject
typedef	QObjectList
Protected Member Functions inherited from QObject
QObject *	sender () const const
int	senderSignalIndex () const const
int	receivers (const char *signal) const const
bool	isSignalConnected (const QMetaMethod &signal) const const
virtual void	timerEvent (QTimerEvent *event)
virtual void	childEvent (QChildEvent *event)
virtual void	customEvent (QEvent *event)
virtual void	connectNotify (const QMetaMethod &signal)
virtual void	disconnectNotify (const QMetaMethod &signal)
Properties inherited from QObject
	objectName

Detailed Description

The AbstractCommand class provides a consistent base for the classes that implement CLI commands.

Definition at line 14 of file abstractcommand.h.

Member Enumeration Documentation

OutputFormat

enum class AbstractCommand::OutputFormat

strong

Supported output formats.

Enumerator
Csv	RFC 4180 compliant CSV text.
Json	RFC 8259 compliant JSON text.
Text	Plain unstructured text.

Definition at line 20 of file abstractcommand.h.

                            {
        Csv,  ///< RFC 4180 compliant CSV text.
        Json, ///< RFC 8259 compliant JSON text.
        Text, ///< Plain unstructured text.
    };

Constructor & Destructor Documentation

AbstractCommand()

AbstractCommand::AbstractCommand ( QObject *const parent = nullptr )

explicit

Constructs a new command with parent.

Definition at line 23 of file abstractcommand.cpp.

                                                       : QObject(parent),
    discoveryAgent(new PokitDiscoveryAgent(this))
{
    connect(discoveryAgent, &PokitDiscoveryAgent::pokitDeviceDiscovered,
            this, &AbstractCommand::deviceDiscovered);
    connect(discoveryAgent, &PokitDiscoveryAgent::finished,
            this, &AbstractCommand::deviceDiscoveryFinished);
    connect(discoveryAgent,
        #if (QT_VERSION < QT_VERSION_CHECK(6, 2, 0))
        QOverload<PokitDiscoveryAgent::Error>::of(&PokitDiscoveryAgent::error),
        #else
        &PokitDiscoveryAgent::errorOccurred,
        #endif
    [](const PokitDiscoveryAgent::Error &error) {
        qCWarning(lc).noquote() << tr("Bluetooth discovery error:") << error;
        QTimer::singleShot(0, QCoreApplication::instance(), [](){
            QCoreApplication::exit(EXIT_FAILURE);
        });
    });
}

References QObject::connect(), deviceDiscovered(), deviceDiscoveryFinished(), discoveryAgent, QBluetoothDeviceDiscoveryAgent::error(), QCoreApplication::exit(), QBluetoothDeviceDiscoveryAgent::finished(), QCoreApplication::instance(), PokitDiscoveryAgent::pokitDeviceDiscovered(), QTimer::singleShot, and QObject::tr().

Here is the call graph for this function:

Member Function Documentation

deviceDiscovered

void AbstractCommand::deviceDiscovered ( const QBluetoothDeviceInfo & info )

protectedpure virtualslot

Handles PokitDiscoveryAgent::pokitDeviceDiscovered signal.

Derived classes must implement this slot to begin whatever actions are relevant when a Pokit device has been discovered. For example, the 'scan' command would simply output the info details, whereas most other commands would begin connecting if info is the device they're after.

Referenced by AbstractCommand().

Here is the caller graph for this function:

deviceDiscoveryFinished

void AbstractCommand::deviceDiscoveryFinished ( )

protectedpure virtualslot

Handles PokitDiscoveryAgent::deviceDiscoveryFinished signal.

Derived classes must implement this slot to perform whatever actions are appropraite when discovery is finished. For example, the 'scan' command would simply exit, whereas most other commands would verify that an appropriate device was found.

Referenced by AbstractCommand().

Here is the caller graph for this function:

escapeCsvField()

QString AbstractCommand::escapeCsvField ( const QString & field )

static

Returns an RFC 4180 compliant version of field.

That is, if field contains any of the the below four characters, than any double quotes are escaped (by addition double-quotes), and the string itself surrounded in double-quotes. Otherwise, field is returned verbatim.

Some examples:

QCOMPARE(escapeCsvField("abc"), "abc");           // Returned unchanged.
QCOMPARE(escapeCsvField("a,c"), R"("a,c")");      // Wrapped in double-quotes.
QCOMPARE(escapeCsvField(R"(a"c)"), R("("a""c")"); // Existing double-quotes doubled, then wrapped.

Definition at line 105 of file abstractcommand.cpp.

{
    if (field.contains(QLatin1Char(','))||field.contains(QLatin1Char('\r'))||
        field.contains(QLatin1Char('"'))||field.contains(QLatin1Char('\n')))
    {
        return QString::fromLatin1(R"("%1")").arg(
            QString(field).replace(QLatin1Char('"'), QLatin1String(R"("")")));
    } else return field;
}

References QString::arg(), QString::contains(), and QString::fromLatin1().

Referenced by ScanCommand::deviceDiscovered(), StatusCommand::outputDeviceStatus(), MeterCommand::outputReading(), and InfoCommand::serviceDetailsDiscovered().

Here is the call graph for this function:

Here is the caller graph for this function:

parseNumber()

template<typename R >

quint32 AbstractCommand::parseNumber ( const QString & value, const QString & unit, const quint32 sensibleMinimum = 0 )

static

Returns value as an integer multiple of the ratio R.

The string value may end with the optional unit, such as V or s, which may also be preceded with a SI unit prefix such as m for milli. If value contains no SI unit prefix, then the result will be multiplied by 1,000 enough times to be greater than sensibleMinimum. This allows for convenient use like:

const quint32 timeout = parseNumber<std::milli>(parser.value("window"), 's', 500'000);

So that an unqalified period like "300" will be assumed to be 300 milliseconds, and not 300 microseconds, while a period like "1000" will be assume to be 1 second.

If conversion fails for any reason, 0 is returned.

Definition at line 149 of file abstractcommand.cpp.

{
    static const QMap<QChar, Ratio> unitPrefixScaleMap {
        { QLatin1Char('E'), makeRatio<std::exa>()   },
        { QLatin1Char('P'), makeRatio<std::peta>()  },
        { QLatin1Char('T'), makeRatio<std::tera>()  },
        { QLatin1Char('G'), makeRatio<std::giga>()  },
        { QLatin1Char('M'), makeRatio<std::mega>()  },
        { QLatin1Char('K'), makeRatio<std::kilo>()  }, // Not official SI unit prefix, but commonly used.
        { QLatin1Char('k'), makeRatio<std::kilo>()  },
        { QLatin1Char('h'), makeRatio<std::hecto>() },
        { QLatin1Char('d'), makeRatio<std::deci>()  },
        { QLatin1Char('c'), makeRatio<std::centi>() },
        { QLatin1Char('m'), makeRatio<std::milli>() },
        { QLatin1Char('u'), makeRatio<std::micro>() }, // Not official SI unit prefix, but commonly used.
        { QChar   (0x00B5), makeRatio<std::micro>() }, // Unicode micro symbol (μ).
        { QLatin1Char('n'), makeRatio<std::nano>()  },
        { QLatin1Char('p'), makeRatio<std::pico>()  },
        { QLatin1Char('f'), makeRatio<std::femto>() },
        { QLatin1Char('a'), makeRatio<std::atto>()  },
    };
 
    // Remove the optional (whole) unit suffix.
    Ratio ratio;
    QString number = value.trimmed();
    if ((!unit.isEmpty()) && (number.endsWith(unit, Qt::CaseInsensitive))) {
        number.chop(unit.length());
        ratio = makeRatio<std::ratio<1>>();
    }
 
    // Parse, and remove, the optional SI unit prefix.
    if (!number.isEmpty()) {
        #if (QT_VERSION >= QT_VERSION_CHECK(5, 10, 0))
        const QChar siPrefix = number.back(); // QString::back() introduced in Qt 5.10.
        #else
        const QChar siPrefix = number.at(number.size() - 1);
        #endif
        const auto iter = unitPrefixScaleMap.constFind(siPrefix);
        if (iter != unitPrefixScaleMap.constEnd()) {
            Q_ASSERT(iter->isValid());
            ratio = *iter;
            number.chop(1);
        }
    }
 
    #define DOKIT_RESULT(var) (var * ratio.num * R::den / ratio.den / R::num)
    // Parse the number as an (unsigned) integer.
    QLocale locale; bool ok;
    qulonglong integer = locale.toULongLong(number, &ok);
    if (ok) {
        if (integer == 0) {
            return 0;
        }
        if (!ratio.isValid()) {
            for (ratio = makeRatio<R>(); DOKIT_RESULT(integer) < sensibleMinimum; ratio.num *= 1000);
        }
        return (integer == 0) ? 0u : (quint32)DOKIT_RESULT(integer);
    }
 
    // Parse the number as a (double) floating point number, and check that it is positive.
    const double dbl = locale.toDouble(number, &ok);
    if ((ok) && (dbl > 0.0)) {
        if (!ratio.isValid()) {
            for (ratio = makeRatio<R>(); DOKIT_RESULT(dbl) < sensibleMinimum; ratio.num *= 1000);
        }
        return (quint32)DOKIT_RESULT(dbl);
    }
    #undef DOKIT_RESULT
    return 0; // Failed to parse as either integer, or float.
}

References QString::at(), QString::back(), Qt::CaseInsensitive, QString::chop(), QString::endsWith(), QString::isEmpty(), Ratio::isValid(), QString::length(), Ratio::num, QString::size(), QLocale::toDouble(), QLocale::toULongLong(), and QString::trimmed().

Here is the call graph for this function:

processOptions

QStringList AbstractCommand::processOptions ( const QCommandLineParser & parser )

virtualslot

Processes the relevant options from the command line parser.

On success, returns an empty QStringList, otherwise returns a list of CLI errors that the caller should report appropriately before exiting.

This base implementations performs some common checks, such as ensuring that required options are present. Derived classes should override this function to perform further processing, typically inovking this base implementation as a first step, such as:

QStringList CustomCommand::processOptions(const QCommandLineParser &parser)
{
    QStringList errors = AbstractCommand::processOptions(parser);
    if (!errors.isEmpty()) {
        return errors;
    }
 
    // Do further procession of options.
 
    return errors;
}

Definition at line 265 of file abstractcommand.cpp.

{
    // Report any supplied options that are not supported by this command.
    const QStringList suppliedOptionNames = parser.optionNames();
    const QStringList supportedOptionNames = supportedOptions(parser);
    for (const QString &option: suppliedOptionNames) {
        if (!supportedOptionNames.contains(option)) {
            qCInfo(lc).noquote() << tr("Ignoring option: %1").arg(option);
        }
    }
    QStringList errors;
 
    // Parse the device (name/addr/uuid) option.
    if (parser.isSet(QLatin1String("device"))) {
        deviceToScanFor = parser.value(QLatin1String("device"));
    }
 
    // Parse the output format options (if supported, and supplied).
    if ((supportedOptionNames.contains(QLatin1String("output"))) && // Derived classes may have removed.
        (parser.isSet(QLatin1String("output"))))
    {
        const QString output = parser.value(QLatin1String("output")).toLower();
        if (output == QLatin1String("csv")) {
            format = OutputFormat::Csv;
        } else if (output == QLatin1String("json")) {
            format = OutputFormat::Json;
        } else if (output == QLatin1String("text")) {
            format = OutputFormat::Text;
        } else {
            errors.append(tr("Unknown output format: %1").arg(output));
        }
    }
 
    // Parse the device scan timeout option.
    if (parser.isSet(QLatin1String("timeout"))) {
        const quint32 timeout = parseNumber<std::milli>(parser.value(QLatin1String("timeout")), QLatin1String("s"), 500);
        if (timeout == 0) {
            errors.append(tr("Invalid timeout: %1").arg(parser.value(QLatin1String("timeout"))));
        } else if (discoveryAgent->lowEnergyDiscoveryTimeout() == -1) {
            qCWarning(lc).noquote() << tr("Platform does not support Bluetooth scan timeout");
        } else {
            discoveryAgent->setLowEnergyDiscoveryTimeout(timeout);
            qCDebug(lc).noquote() << tr("Set scan timeout to %1").arg(
                discoveryAgent->lowEnergyDiscoveryTimeout());
        }
    }
 
    // Return errors for any required options that are absent.
    const QStringList requiredOptionNames = this->requiredOptions(parser);
    for (const QString &option: requiredOptionNames) {
        if (!parser.isSet(option)) {
            errors.append(tr("Missing required option: %1").arg(option));
        }
    }
    return errors;
}

References QList::append(), QString::arg(), QStringList::contains(), Csv, deviceToScanFor, discoveryAgent, format, QCommandLineParser::isSet(), Json, QBluetoothDeviceDiscoveryAgent::lowEnergyDiscoveryTimeout(), QCommandLineParser::optionNames(), requiredOptions(), QBluetoothDeviceDiscoveryAgent::setLowEnergyDiscoveryTimeout(), supportedOptions(), Text, QString::toLower(), QObject::tr(), and QCommandLineParser::value().

Referenced by CalibrateCommand::processOptions(), DsoCommand::processOptions(), FlashLedCommand::processOptions(), InfoCommand::processOptions(), LoggerStartCommand::processOptions(), MeterCommand::processOptions(), ScanCommand::processOptions(), SetNameCommand::processOptions(), SetTorchCommand::processOptions(), and StatusCommand::processOptions().

Here is the call graph for this function:

Here is the caller graph for this function:

requiredOptions()

QStringList AbstractCommand::requiredOptions ( const QCommandLineParser & parser ) const

virtual

Returns a list of CLI option names required by this command.

The main console appication may use this list to output an eror (and exit) if any of the returned names are not found in the parsed CLI options.

The (already parsed) parser may be used adjust the returned required options depending on the value of other options. For example, the logger command only requires the --mode option if the --command option is start.

This base implementation simply returns an empty list. Derived classes should override this function to include any required options.

Reimplemented in CalibrateCommand, DsoCommand, FlashLedCommand, InfoCommand, LoggerStartCommand, MeterCommand, ScanCommand, SetNameCommand, SetTorchCommand, and StatusCommand.

Definition at line 56 of file abstractcommand.cpp.

{
    Q_UNUSED(parser)
    return QStringList();
}

Referenced by processOptions(), CalibrateCommand::requiredOptions(), DsoCommand::requiredOptions(), FlashLedCommand::requiredOptions(), InfoCommand::requiredOptions(), LoggerStartCommand::requiredOptions(), MeterCommand::requiredOptions(), ScanCommand::requiredOptions(), SetNameCommand::requiredOptions(), SetTorchCommand::requiredOptions(), StatusCommand::requiredOptions(), and supportedOptions().

Here is the caller graph for this function:

supportedOptions()

QStringList AbstractCommand::supportedOptions ( const QCommandLineParser & parser ) const

virtual

Returns a list of CLI option names supported by this command.

The main console appication may use this list to output a warning for any parsed CLI options not included in the returned list.

The (already parsed) parser may be used adjust the returned supported options depending on the value of other options. For example, the logger command only supported the --timestamp option if the --command option is start.

This base implementation simply returns requiredOptions(). Derived classes should override this function to include optional options, such as:

QStringList Derived::supportedOptions(const QCommandLineParser &parser) const
{
    const QStringList list = AbstractCommand::supportedOptions(parser) + QStringList{ ... };
    list.sort();
    list.removeDuplicates(); // Optional, recommended.
    return list;
}

Reimplemented in CalibrateCommand, DsoCommand, FlashLedCommand, InfoCommand, LoggerStartCommand, MeterCommand, ScanCommand, SetNameCommand, SetTorchCommand, and StatusCommand.

Definition at line 83 of file abstractcommand.cpp.

{
    return requiredOptions(parser) + QStringList{
        QLatin1String("debug"),
        QLatin1String("device"), QLatin1String("d"),
        QLatin1String("output"),
        QLatin1String("timeout"),
    };
}

References requiredOptions().

Referenced by processOptions(), CalibrateCommand::supportedOptions(), DsoCommand::supportedOptions(), FlashLedCommand::supportedOptions(), InfoCommand::supportedOptions(), LoggerStartCommand::supportedOptions(), MeterCommand::supportedOptions(), ScanCommand::supportedOptions(), SetNameCommand::supportedOptions(), SetTorchCommand::supportedOptions(), and StatusCommand::supportedOptions().

Here is the call graph for this function:

Here is the caller graph for this function:

Friends And Related Symbol Documentation

TestAbstractCommand

friend class TestAbstractCommand

friend

Definition at line 50 of file abstractcommand.h.

Member Data Documentation

deviceToScanFor

QString AbstractCommand::deviceToScanFor

protected

Device (if any) that were passed to processOptions().

Definition at line 41 of file abstractcommand.h.

Referenced by DeviceCommand::deviceDiscovered(), DeviceCommand::deviceDiscoveryFinished(), processOptions(), and DeviceCommand::start().

discoveryAgent

PokitDiscoveryAgent* AbstractCommand::discoveryAgent

protected

Agent for Pokit device descovery.

Definition at line 42 of file abstractcommand.h.

Referenced by AbstractCommand(), DeviceCommand::deviceDiscovered(), processOptions(), ScanCommand::ScanCommand(), DeviceCommand::start(), and ScanCommand::start().

format

OutputFormat AbstractCommand::format { OutputFormat::Text }

protected

Selected output format.

Definition at line 43 of file abstractcommand.h.

{ OutputFormat::Text }; ///< Selected output format.

Referenced by ScanCommand::deviceDiscovered(), FlashLedCommand::deviceLedFlashed(), SetNameCommand::deviceNameWritten(), StatusCommand::outputDeviceStatus(), MeterCommand::outputReading(), LoggerFetchCommand::outputSamples(), DsoCommand::outputSamples(), processOptions(), InfoCommand::serviceDetailsDiscovered(), LoggerStartCommand::settingsWritten(), LoggerStopCommand::settingsWritten(), CalibrateCommand::temperatureCalibrated(), and SetTorchCommand::torchStatusWritten().

---

The documentation for this class was generated from the following files:

• abstractcommand.h
• abstractcommand.cpp