Commands

Commands

Ludolph commands are just plugin methods decorated with the @command decorator.

from ludolph.command import command

@command

Use to register a Ludolph command.

Usage

@command(stream_output=False, reply_output=True,
         user_required=True, admin_required=False,
         room_user_required=False, room_admin_required=False)

Example

@command                             # The decorator (required)
def my_command(self, msg):           # Every method receives the incoming message object as the 2nd positional argument
    """My command documentation."""  # The docstring is used as command documentation
    return 'This is my command'      # The command should return a string which will be send as a reply to the original message sender

Note: The command should not start with an underscore and underscores in method names are transformed to hyphens to generate the command name.

Parameters

Each command method must be a bound method, hence the first parameter is the plugin instance. The second parameter is always a message object. Additional positional, keyword, or "star" (*) arguments may be specified.

@command               
def my_command(self, msg, arg1, arg2, kwarg1=None):   # The command must be run with positional 2 parameters,
    ...                                               # otherwise an error message is sent to the user

Permissions

By default the @command decorator checks if the user has a user permission, i.e. the caller's JID is set in users configuration variable. To enable other permission checks use a combination of following @command parameters:

• user_required
• admin_required
• room_user_required
• room_admin_required

@command(admin_required=True)       # Check if user has admin permission
def my_admin_command(self, msg):
    pass

Exceptions

from ludolph.command import CommandError, PermissionDenied, MissingParameter, command

CommandError

You can raise the CommandError exception to send a standard error message to the user. In fact, this is the preferred way to inform the user about an error.

@command(stream_output=True)
def echo(self, msg, *args):
    if not args:
        raise CommandError('You gave me nothing to echo :(')

    for arg in args:
        yield 'I have received parameter: "%s"' % arg
        time.sleep(0.3)

PermissionDenied

CommandError exception with predefined error message: Permission denied.

@command
def my_command(self, msg):
    user = self.xmpp.get_jid(msg)   # Get the request user

    if user != 'user@example.com':
        raise PermissionDenied
    ...

MissingParameter

CommandError exception with predefined error message: Missing parameter.