Communi  3.7.0
A cross-platform IRC framework written with Qt
Public Types | Public Slots | Public Member Functions | Properties | List of all members
IrcCommandParser Class Reference

Parses commands from user input. More...

#include <IrcCommandParser>

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=nullptr)
 
 ~IrcCommandParser () override
 
Q_INVOKABLE void addCommand (IrcCommand::Type type, const QString &syntax)
 
QStringList channels () const
 
QStringList commands () const
 
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
 
QString target () const
 
QStringList triggers () const
 

Properties

bool tolerant
 

Detailed Description

Syntax

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...>");
Parses commands from user input.
Definition: irccommandparser.h:43
Q_INVOKABLE void addCommand(IrcCommand::Type type, const QString &syntax)
Definition: irccommandparser.cpp:398
IrcCommandParser(QObject *parent=nullptr)
Definition: irccommandparser.cpp:337
@ Kick
A kick command (KICK) is used to forcibly remove a user from a channel.
Definition: irccommand.h:66
@ Part
A part command (PART) causes the client to be removed from the channel.
Definition: irccommand.h:75
@ Join
A join command (JOIN) is used to start listening a specific channel.
Definition: irccommand.h:65
@ CtcpAction
A CTCP action command is used to send an action message to channels and users.
Definition: irccommand.h:59
Note
The parameter names are insignificant, but descriptive parameter names are recommended for the sake of readability.

Context

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->setTarget("jpnurmi");
parser->setChannels(QStringList() << "#communi" << "#libera");

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 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->setTarget("#communi");
parser->setTriggers(QStringList() << "/");
parser->parse(input);
Q_INVOKABLE IrcCommand * parse(const QString &input) const
Definition: irccommandparser.cpp:550

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")
Provides the most common commands.
Definition: irccommand.h:45
@ Custom
A custom command.
Definition: irccommand.h:62

Member Enumeration Documentation

◆ Detail

This enum describes the available syntax details.

Enumerator
Full 

The syntax in full details.

NoTarget 

The syntax has injected [target] removed.

NoPrefix 

The syntax has #channel prefixes removed.

NoEllipsis 

The syntax has ellipsis... removed.

NoParentheses 

The syntax has parentheses () removed.

NoBrackets 

The syntax has brackets [] removed.

NoAngles 

The syntax has angle brackets <> removed.

Visual 

The syntax suitable for visual representation.

Constructor & Destructor Documentation

◆ IrcCommandParser()

IrcCommandParser::IrcCommandParser ( QObject *  parent = nullptr)
explicit

Constructs a command parser with parent.

◆ ~IrcCommandParser()

IrcCommandParser::~IrcCommandParser ( )
override

Destructs the command parser.

Member Function Documentation

◆ addCommand()

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

Adds a command with type and syntax.

◆ channels()

QStringList IrcCommandParser::channels ( ) const

This property holds the available channels.

Access functions:
  • QStringList channels() const
  • void setChannels(const QStringList& channels) [slot]
Notifier signal:
  • void channelsChanged(const QStringList& channels)
See also
IrcBufferModel::channels()

◆ clear

void IrcCommandParser::clear ( )
slot

Clears the list of commands.

See also
reset()

◆ commands()

QStringList IrcCommandParser::commands ( ) const

This property holds the known commands.

The commands are uppercased and in alphabetical order.

Access function:
  • QStringList commands() const
Notifier signal:
  • void commandsChanged(const QStringList& commands)
See also
addCommand(), removeCommand()

◆ parse()

IrcCommand * IrcCommandParser::parse ( const QString &  input) const

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

◆ removeCommand()

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

Removes the command with type and syntax.

◆ reset

void IrcCommandParser::reset ( )
slot

Resets the channels and the current target.

See also
clear()

◆ syntax()

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

Returns syntax for the given command in given details level.

◆ target()

QString IrcCommandParser::target ( ) const

This property holds the current target.

Access functions:
  • QString target() const
  • void setTarget(const QString& target) [slot]
Notifier signal:
  • void targetChanged(const QString& target)

◆ triggers()

QStringList IrcCommandParser::triggers ( ) const

This property holds the command triggers.

Access functions:
  • QStringList triggers() const
  • void setTriggers(const QStringList& triggers) [slot]
Notifier signal:
  • void triggersChanged(const QStringList& triggers)

Property Documentation

◆ tolerant

bool IrcCommandParser::tolerant
readwrite

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
IrcCommand::Quote