IrcCommandParser Class Reference

Parses commands from user input. More...

Inherits QObject.

Public Types

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 IrcCommand *	parse (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

enum IrcCommandParser::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 ( 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:

• QStringList channels() const
• void setChannels(const QStringList& channels) [slot]

Notifier signal:

• void channelsChanged(const QStringList& channels)

See also

IrcBufferModel::channels()

QStringList IrcCommandParser::commands

read

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

QString IrcCommandParser::target

readwrite

This property holds the current target.

Access functions:

• QString target() const
• void setTarget(const QString& target) [slot]

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:

• QStringList triggers() const
• void setTriggers(const QStringList& triggers) [slot]

Notifier signal:

• void triggersChanged(const QStringList& triggers)