4. Advanced bot commands

4.1. Automatic argument splitting

With the split_args_with argument to botcmd(), you can specify a delimiter of the arguments and it will give you an array of strings instead of a string:

@botcmd(split_args_with=None)
def action(self, mess, args):
 # if you send it !action one two three
 # args will be ['one', 'two', 'three']

Note

split_args_with behaves exactly like str.split(), therefore the value None can be used to split on any type of whitespace, such as multiple spaces, tabs, etc. This is recommended over ‘ ‘ for general use cases but you’re free to use whatever argument you see fit.

4.2. Subcommands

If you put an _ in the name of the function, Errbot will create what looks like a subcommand for you. This is useful to group commands that belong to each other together.

@botcmd
def basket_add(self, mess, args):
 # Will respond to !basket add
 pass
@botcmd
def basket_remove(self, mess, args):
 # Will respond to !basket remove
 pass

Note

It will still respond to !basket_add and !basket_remove as well.

4.3. Argparse argument splitting

With the arg_botcmd() decorator you can specify a command’s arguments in argparse format. The decorator can be used multiple times, and each use adds a new argument to the command. The decorator can be passed any valid add_arguments() parameters.

@arg_botcmd('first_name', type=str)
@arg_botcmd('--last-name', dest='last_name', type=str)
@arg_botcmd('--favorite', dest='favorite_number', type=int, default=42)
def hello(self, mess, first_name=None, last_name=None, favorite_number=None):
 # if you send it !hello Err --last-name Bot
 # first_name will be 'Err'
 # last_name will be 'Bot'
 # favorite_number will be 42

Note

  • An argument’s dest parameter is used as its kwargs key when your command is called.

  • favorite_number would be None if we removed default=42 from the arg_botcmd() call.

4.4. Commands using regular expressions

In addition to the fixed commands created with the botcmd() decorator, Errbot supports an alternative type of bot function which can be triggered based on a regular expression. These are created using the re_botcmd() decorator. There are two forms these can be used, with and without the usual bot prefix.

In both cases, your method will receive the message object same as with a regular botcmd(), but instead of an args parameter, it takes a match parameter which will receive an re.MatchObject.

Note

By default, only the first occurrence of a match is returned, even if it can match multiple parts of the message. If you specify matchall=True, you will instead get a list of re.MatchObject items, containing all the non-overlapping matches that were found in the message.

4.4.1. With a bot prefix

You can define commands that trigger based on a regular expression, but still require a bot prefix at the beginning of the line, in order to create more flexible bot commands. Here’s an example of a bot command that lets people ask for cookies:

from errbot import BotPlugin, re_botcmd
class CookieBot(BotPlugin):
"""A cookiemonster bot"""
 @re_botcmd(pattern=r"^(([Cc]an|[Mm]ay) I have a )?cookie please\?$")
 def hand_out_cookies(self, msg, match):
"""
 Gives cookies to people who ask me nicely.
 This command works especially nice if you have the following in
 your `config.py`:
 BOT_ALT_PREFIXES = ('Err',)
 BOT_ALT_PREFIX_SEPARATORS = (':', ',', ';')
 People are then able to say one of the following:
 Err, can I have a cookie please?
 Err: May I have a cookie please?
 Err; cookie please?
 """
 yield "Here's a cookie for you, {}".format(msg.frm)
 yield "/me hands out a cookie."

4.4.2. Without a bot prefix

It’s also possible to trigger commands even when no bot prefix is specified, by passing prefixed=False to the re_botcmd() decorator. This is especially useful if you want to trigger on specific keywords that could show up anywhere in a conversation:

import re
from errbot import BotPlugin, re_botcmd
class CookieBot(BotPlugin):
"""A cookiemonster bot"""
 @re_botcmd(pattern=r"(^| )cookies?( |$)", prefixed=False, flags=re.IGNORECASE)
 def listen_for_talk_of_cookies(self, msg, match):
"""Talk of cookies gives Errbot a craving..."""
 return "Somebody mentioned cookies? Om nom nom!"