Merge pull request #1 from MrLotU/Commands-Docs

Update building_block_commands.md

docs/bot_tutorial/building_block_commands.md

@@ -0,0 +1,103 @@
+# 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', '<content:str...>')
+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', '<a:int> <b:int>', 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', '<name:str> [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)
+```
+
+These are all the commands we created in this tutorial:
+```py
+class myPlugin(Plugin):
+  @Plugin.command('ping')
+  def on_ping_command(self, event):
+    event.msg.reply('Pong!')
+    
+  @Plugin.command('echo', '<content:str...>')
+  def on_echo_command(self, event, content):
+    event.msg.reply(content)
+    
+  @Plugin.command('add', '<a:int> <b:int>', group='math')
+  def on_add_command(self, event, a, b):
+    event.msg.reply('{}'.format(a+b))
+    
+  @Plugin.command('tag', '<name:str> [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))
+        
+  @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)
+```