Communi  3.0.0
A cross-platform IRC framework written with Qt
 All Classes Namespaces Files Functions Variables Enumerations Enumerator Properties Macros Groups Pages
Public Types | Public Slots | Public Member Functions | Properties | List of all members
IrcCommandParser Class Reference

Parses commands from user input. More...

Inherits QObject.

Public Types

enum  Detail {
  Full = 0x0, NoTarget = 0x1, NoPrefix = 0x2, NoEllipsis = 0x4,
  NoParentheses = 0x8, NoBrackets = 0x10, NoAngles = 0x20, Visual = NoTarget | NoPrefix | NoEllipsis

Public Slots

void clear ()
void reset ()

Public Member Functions

 IrcCommandParser (QObject *parent=0)
virtual ~IrcCommandParser ()
Q_INVOKABLE void addCommand (IrcCommand::Type type, const QString &syntax)
Q_INVOKABLE IrcCommandparse (const QString &input) const
Q_INVOKABLE void removeCommand (IrcCommand::Type type, const QString &syntax=QString())
Q_INVOKABLE QString syntax (const QString &command, Details details=Visual) const


QStringList channels
QStringList commands
QString target
bool tolerant
QStringList triggers

Detailed Description


Since the list of supported commands and the exact syntax for each command is application specific, IrcCommandParser does not provide any built-in command syntaxes. It is left up to the applications to introduce the supported commands and syntaxes. IrcCommandParser supports the following command syntax markup:

Syntax Example Description
<param> <target> A required parameter.
(<param>) (<key>) An optional parameter.
<param...> <message...> A required parameter, multiple words accepted. (1)
(<param...>) (<message...>) An optional parameter, multiple words accepted. (1)
(<#param>) (<#channel>) An optional channel parameter. (2)
[param] [target] Inject the current target.
  1. Multi-word parameters are only supported in the last parameter position.
  2. An optional channel parameter is filled up with the current channel when absent.

The following example presents introducing some typical commands.

IrcCommandParser* parser = new IrcCommandParser(this);
parser->addCommand(IrcCommand::Join, "JOIN <#channel> (<key>)");
parser->addCommand(IrcCommand::Part, "PART (<#channel>) (<message...>)");
parser->addCommand(IrcCommand::Kick, "KICK (<#channel>) <nick> (<reason...>)");
parser->addCommand(IrcCommand::CtcpAction, "ME [target] <message...>");
parser->addCommand(IrcCommand::CtcpAction, "ACTION <target> <message...>");
The parameter names are insignificant, but descriptive parameter names are recommended for the sake of readability.


Notice that commands are often context sensitive. While some command may accept an optional parameter that is filled up with the current target (channel/query) name when absent, another command may always inject the current target name as a certain parameter. Therefore IrcCommandParser must be kept up-to-date with the current target and the list of channels.

// currently in a query, and also present on some channels
parser->setChannels(QStringList() << "#communi" << "#freenode");

Command triggers

IrcCommandParser serves as a generic parser for typical IRC commands. It can be utilized for parsing commands from user input in GUI clients, and from messages from other clients when implementing IRC bots.

The command parsing behavior is controlled by setting up command Command triggers. Whilst a typical GUI client might use "/" as a command trigger, an IRC bot might use "!" and the nick name of the bot. The following snippet illustrates a typical GUI client usage.

parser->setTriggers(QStringList() << "/");

Input Result Description
"hello" IrcCommand::Message No matching command trigger => a message "hello" to #communi
"/join #channel" IrcCommand::Join Matching command trigger => a command to join "#channel"

See the bot example to see how the parser can be effectively utilized for IRC bots.

Custom commands

The parser also supports such custom client specific commands that are not sent to the server. Since IrcCommand does not know how to handle custom commands, the parser treats them as a special case injecting the command as a first parameter.

IrcParser parser;
parser.addCommand(IrcCommand::Custom, "QUERY <user>");
IrcCommand* command = parser.parse("/query jpnurmi");
Q_ASSERT(command->type() == IrcCommand::Custom);
qDebug() << command->parameters(); // ("QUERY", "jpnurmi")

Member Enumeration Documentation

This enum describes the available syntax details.


The syntax in full details.


The syntax has injected [target] removed.


The syntax has #channel prefixes removed.


The syntax has ellipsis... removed.


The syntax has parentheses () removed.


The syntax has brackets [] removed.


The syntax has angle brackets <> removed.


The syntax suitable for visual representation.

Constructor & Destructor Documentation

IrcCommandParser::IrcCommandParser ( QObject parent = 0)

Constructs a command parser with parent.

IrcCommandParser::~IrcCommandParser ( )

Destructs the command parser.

Member Function Documentation

void IrcCommandParser::addCommand ( IrcCommand::Type  type,
const QString syntax 

Adds a command with type and syntax.

void IrcCommandParser::clear ( )

Clears the list of commands.

See Also
IrcCommand * IrcCommandParser::parse ( const QString input) const

Parses and returns the command for input, or 0 if the input is not valid.

void IrcCommandParser::removeCommand ( IrcCommand::Type  type,
const QString syntax = QString() 

Removes the command with type and syntax.

void IrcCommandParser::reset ( )

Resets the channels and the current target.

See Also
QString IrcCommandParser::syntax ( const QString command,
Details  details = Visual 
) const

Returns syntax for the given command in given details level.

Property Documentation

QStringList IrcCommandParser::channels

This property holds the available channels.

Access functions:
Notifier signal:
See Also
QStringList IrcCommandParser::commands

This property holds the known commands.

The commands are uppercased and in alphabetical order.

Access function:
Notifier signal:
See Also
addCommand(), removeCommand()
QString IrcCommandParser::target

This property holds the current target.

Access functions:
Notifier signal:
  • void targetChanged(const QString& target)
bool IrcCommandParser::tolerant

This property holds whether the parser is tolerant.

A tolerant parser creates message commands out of input that does not start with a command trigger, and raw server commands when the input starts with a command trigger but the command is unrecognized. Known commands with invalid arguments are still considered invalid.

The default value is false.

Access functions:
  • bool isTolerant() const
  • void setTolerant(bool tolerant)
Notifier signal:
  • void tolerancyChanged(bool tolerant)
See Also
QStringList IrcCommandParser::triggers

This property holds the command triggers.

Access functions:
Notifier signal: