Communi  3.4.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...

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
 

Properties

QStringList channels
 
QStringList commands
 
QString target
 
bool tolerant
 
QStringList triggers
 

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...>");
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" << "#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 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);

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.

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 ( QObject parent = 0)
explicit

Constructs a command parser with parent.

IrcCommandParser::~IrcCommandParser ( )
virtual

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 ( )
slot

Clears the list of commands.

See also
reset()
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 ( )
slot

Resets the channels and the current target.

See also
clear()
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
readwrite

This property holds the available channels.

Access functions:
Notifier signal:
See also
IrcBufferModel::channels()
QStringList IrcCommandParser::commands
read

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
readwrite

This property holds the current target.

Access functions:
Notifier signal:
  • void targetChanged(const QString& target)
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
QStringList IrcCommandParser::triggers
readwrite

This property holds the command triggers.

Access functions:
Notifier signal: