diff --git a/docs/bot_tutorial/building_block_commands.md b/docs/bot_tutorial/building_block_commands.md index e69de29..36861b7 100644 --- a/docs/bot_tutorial/building_block_commands.md +++ b/docs/bot_tutorial/building_block_commands.md @@ -0,0 +1,73 @@ +# Commands + +Commands are a big part of the Discord bot ussage. You've probably used commands multiple times yourself, maybe without even realizing. +Basic examples of commands are: +`/nick`, `/tableflip` +A command can be defined as an order you give to a bot or some other sort of program that will reply in a certain way. So, looking back at the examples above, if you'd use `/tableflip` in Discord, Discord will append `(╯°□°)╯︵ ┻━┻` to your message. + +## Commands in disco + +Creating commands in Disco is really easy because of the [Plugins](https://b1naryth1ef.github.io/disco/bot_tutorial/building_block_plugins.html) that are a core fundamential of Disco. Creating a basic command is done as follows: +First, create a Plugin class: +```py +class myPlugin(Plugin): +``` +Now, we can add a command to it. The command will be named ping, and it will simply reply with `pong!` +```py +@Plugin.command('ping') +def on_ping_command(self, event): + event.msg.reply('Pong!') +``` +And there we go! Our very first command! + +Now, lets go on to some more advanced commands. Now, we'll create an echo command that will respond with whatever we put in to it. +```py +@Plugin.command('echo', '') +def on_echo_command(self, event, content): + event.msg.reply(content) +``` +What we did here, was add an argument to our command. The argument we created here, content, is required. This means the command wont work if you don't give it a content. +You can also add optional arguments to a command. Instead of surrounding the name and type in angel brackets, you'd surround them in square brackets like this: `[content:str...]` +Keep in mind that arguments that are optional, might not be there. You'll have to create some checks so that your program doesn't crash on unexpected null values. + +Now that we have 2 basic commands and we know to create basic commands and add some arguments to it. Let's create a more advanced command utilizing what we just learned. +The command will take 2 numbers (integers) and simply adds them together. It will work like this: `!math add 1 4` and it would return 5. We could of course specify the name of the command to be `math add` but Disco commands also have a nice feature called command groups. +Using command groups, you can easaly group commands together and create sub commands. Now, here comes our math command: +```py +@Plugin.command('add', ' ', group='math') +def on_add_command(self, event, a, b): + event.msg.reply('{}'.format(a+b)) +``` +Here, we added multiple arguments to our commands, namely, number a and number b, that we add together and return back. Of course, you can do loads more fun things with the Disco command handler. +For example, lets create a tag system, that can either store a tag if you'd use it like this: `!tag name value` or retrieve a tag if you'd use it like this: `!tag name` + +For this, we'll need 2 arguments. A name argument that's required, and an optional value argument. Inside the command, we'll check if there is a value, if there is, we'll store the tag in Discos builtin storage, if there's no value, we'll try to retrieve the value from the storage and return it. +```py +@Plugin.command('tag', ' [value:str...]') +def on_tag_command(self, event, name, value=None): + tags = self.storage.guild.ensure('tags') + + if value: + tags[name] = value + event.msg.reply(':ok_hand: created tag `{}`'.format(name)) + else: + if name in tags: + return event.msg.reply(tags[name]) + else: + return event.msg.reply('Unknown tag: `{}`'.format(name)) +``` + +A different way of adding arguments to a command is by using argparse.ArgumentParser. With agparser it's easier to create more complicated commands with many options or flags. +Right here, we'll recreate our math add command, but using agparser. +```py +@Plugin.command('add', parser=True, group='math') +@Plugin.parser.add_argument('a', type=int) +@Plugin.parser.add_argument('b', type=int) +def on_add_command(self, event, args): + event.msg.reply('{}'.format(args.a + args.b) +``` + +All combined commands in 1 large codeblock: +```py +class myPlugin(Plugin): +