Visindigo::General::CommandHost Class

class Visindigo::General::CommandHost

此类提供了一个命令主机，用于注册和管理命令处理程序. 详情...

头文件：	`#include <General/CommandHost.h>`
自以下版本：	Visindigo 0.13.0

所有成员列表（包含继承成员）

公开成员函数

`(自 Visindigo 0.13.0 引入)`	~CommandHost()
`(自 Visindigo 0.13.0 引入)` QStringList	completeCommand(const QString &commandLine)
`(自 Visindigo 0.13.0 引入)` Visindigo::General::CommandHandler *	getCommandHandler(const QString &commandName)
`(自 Visindigo 0.13.0 引入)` QStringList	getCommandHistory(const QString &startWith = "") const
`(自 Visindigo 0.13.0 引入)` QString	getLastCommand() const
`(自 Visindigo 0.13.0 引入)` qsizetype	getMaxCommandHistorySize() const
`(自 Visindigo 0.13.0 引入)` QStringList	getRegisteredCommandNames() const
`(自 Visindigo 0.13.0 引入)` bool	isCommandRegistered(Visindigo::General::CommandHandler *handler)
`(自 Visindigo 0.13.0 引入)` void	registerCommand(Visindigo::General::CommandHandler *handler)
`(自 Visindigo 0.13.0 引入)` void	setMaxCommandHistorySize(qsizetype size)
`(自 Visindigo 0.13.0 引入)` void	setStdInListeningEnabled(bool enabled)
`(自 Visindigo 0.13.0 引入)` void	unregisterCommand(Visindigo::General::CommandHandler *handler)

公开槽函数

(自 Visindigo 0.13.0 引入) void executeCommand(const QString &commandLine)

静态公开成员

(自 Visindigo 0.13.0 引入) Visindigo::General::CommandHost * getInstance()

详细说明

Note: 这是一个从旧版Visindigo继承下来的功能（VICore/VICommand），但已经重新实现，因此行为和接口与旧版有所不同。建议用户参考本类的文档和示例代码，以了解如何使用新版本。

命令主机是一个单例类，负责维护所有注册的命令处理程序，并提供执行命令的接口。

命令格式

Visindigo将命令格式分为两类：匿名参数命令和具名参数命令。匿名参数命令的格式为：

commandName arg1 arg2 ...

具名参数命令的格式为：

commandName -key value -key value

在具名参数命令中，参数以键值对的形式出现，键以短横线（-）开头，后跟对应的值。 Visindigo不支持某些命令格式中的纯标志设置语法（如–flag），所有具名参数都必须有对应的值。

Visindigo允许混用具名参数和匿名参数，也不要求参数的前后顺序，因为Visindigo这样解析命令：如果一个参数以短横线开头，则将其视为具名参数的键，后续的参数直到下一个空格之前都视为该键的值。而在任何值之后的参数都视为匿名参数，直到再次遇到可以视为键名（即以短横线开头）的参数为止。例如，在以下命令中：

commandName -key1 value1 arg1 -key2 value2 arg2 arg3

Visindigo会将-key1和value1解析为具名参数，将arg1解析为匿名参数，然后将-key2和value2解析为另一个具名参数，最后将arg2和arg3解析为匿名参数。

不过，这样的写法可能会降低命令的可读性，我们仍然建议用户将具名参数和匿名参数分开书写，以提高命令的清晰度和可维护性。

对于开发者而言，具名参数和匿名参数在CommandHandler的onCommand 和 onComplete 方法中分别通过namedArgs 和unnamedArgs 参数传递。它们分别对应于QMap<QString, QString> 类型的具名参数和QStringList 类型的匿名参数。因此匿名参数是有序的，而具名参数则是无序的。

如果参数中要出现空格，则整个参数都必须用引号括起来。（这与Windows Batch不同，在bat中你可以只在空格处用引号，比如arg" "withspace，但在Visindigo中你必须使用"arg withspace"这种形式。），同样的，如果参数头部要出现短横线，也必须使用引号括起来以避免被误解析为具名参数的键名。要使用引号本身，请在引号前加反斜杠进行转义，例如："。

命令名和别名

Visindigo中的每个命令处理程序都有一个唯一的命令名（command name），用于标识该命令。此外，命令处理程序还可以有一个或多个别名（alias），这些别名也是用于标识该命令的有效名称。但是，所有命令名和别名在整个命令主机中必须是唯一的，不能重复注册。如果注册命令时发现命令名已被占用，则注册将失败，命令处理程序仍然保持未注册状态。

但重复的别名不影响注册本身，只是后来者的别名将无法使用，因为命令主机会优先匹配最先注册的命令处理程序。

命名建议

Visindigo命令处理框架的灵感来源于Minecraft的命令系统，因此在命令命名方面，我们推荐遵循 Minecraft插件社区大部分作品所采用的一种不成文的规则：

1. 命令名应和插件名（或功能模块名）相关联并尽量采取全名。如果插件名为TianyuAreaManager，则命令名应为tianyareamanager，而不是tam或tamgr
2. 命令名（包括别名和命令解析）应全部采用小写字母，也不需要任何连字符或下划线。
3. 命令名尽量避免使用缩写，除非该缩写已经被广泛接受和使用（例如，cfg代表config）。
4. 命令名缩写的形式，例如，假设AdvancedCfg插件的作者是Visindigo团队，则可以使用viac作为advancedcfg命令的别名。

监听stdin和多线程

Visindigo的命令主机默认并不监听标准输入（stdin），因此用户无法直接在控制台中输入命令。如果需要启用stdin监听功能，请参考setStdInListeningEnabled 方法的说明。

除了stdin之外，在很多情况下命令执行可能需要在其他线程中进行或调用，而 CommandHost只在主线程中执行命令处理程序的onCommand 和onComplete 方法，也只在主线程实现命令解析。不过为了方便起见，executeCommand方法被置为了槽函数，使得用户可以通过Qt的信号槽机制在其他线程中调用它来执行命令。但它本身仍然只在主线程中执行。

命令提示和自动补全

Visindigo的命令主机支持命令提示和自动补全功能，这些功能通过CommandHandler的onComplete 方法实现。 onComplete 方法接受与onCommand 方法相同的参数，但返回一个QStringList，表示可能的补全选项。

而调用者可以通过CommandHost的completeCommand 方法来获取补全选项。这对于实现命令行界面（CLI）或集成开发环境（IDE）中的命令补全功能非常有用。

错误处理

Visindigo的命令主机提供了基本的错误处理机制，通过CommandHost的getLastError 方法获取最后一次命令执行的错误信息。如果executeCommand 方法返回false，则可以调用getLastError 方法获取详细的错误信息，有关Visindigo::General::CommandErrorData 类的说明，请参考相应的文档。