<liclass="toctree-l2"><aclass="reference internal"href="#running-code-at-the-initialization-of-the-bot">Running code at the initialization of the bot</a></li>
<h2>Creating a new Command<aclass="headerlink"href="#creating-a-new-command"title="Permalink to this headline">¶</a></h2>
<p>First, think of a <codeclass="docutils literal notranslate"><spanclass="pre">name</span></code> for your command.
It’s the name your command will be called with: for example, the “spaghetti” command will be called by typing <strong>/spaghetti</strong> in chat.
Try to keep the name as short as possible, while staying specific enough so no other command will have the same name.</p>
<p>Next, create a new Python file with the <codeclass="docutils literal notranslate"><spanclass="pre">name</span></code> you have thought of.
The previously mentioned “spaghetti” command should have a file called <codeclass="docutils literal notranslate"><spanclass="pre">spaghetti.py</span></code>.</p>
<p>Then, in the first row of the file, import the <aclass="reference internal"href="apireference.html#royalnet.commands.Command"title="royalnet.commands.Command"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">Command</span></code></a> class from royalnet, and create a new class inheriting from it:</p>
<p>Inside the class, override the attributes <codeclass="docutils literal notranslate"><spanclass="pre">name</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">description</span></code> with respectively the <strong>name of the command</strong> and a <strong>small description of what the command will do</strong>:</p>
<spanclass="n">description</span><spanclass="o">=</span><spanclass="s2">"Send a spaghetti emoji in the chat."</span>
</pre></div>
</div>
<p>Now override the <aclass="reference internal"href="apireference.html#royalnet.commands.Command.run"title="royalnet.commands.Command.run"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">Command.run()</span></code></a> method, adding the code you want the bot to run when the command is called.</p>
<p>To send a message in the chat the command was called in, you can use the <aclass="reference internal"href="apireference.html#royalnet.commands.CommandData.reply"title="royalnet.commands.CommandData.reply"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">CommandData.reply()</span></code></a> method:</p>
<p>A command can have some arguments passed by the user: for example, on Telegram an user may type <cite>/spaghetti carbonara al-dente</cite>
to pass the <aclass="reference external"href="https://docs.python.org/3.7/library/stdtypes.html#str"title="(in Python v3.7)"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">str</span></code></a><cite>“carbonara al-dente”</cite> to the command code.</p>
<p>These arguments can be accessed in multiple ways through the <codeclass="docutils literal notranslate"><spanclass="pre">args</span></code> parameter passed to the <aclass="reference internal"href="apireference.html#royalnet.commands.Command.run"title="royalnet.commands.Command.run"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">Command.run()</span></code></a>
<p>If you want your command to use arguments, override the <codeclass="docutils literal notranslate"><spanclass="pre">syntax</span></code> class attribute with a brief description of the
syntax of your command, possibly using (round parentheses) for required arguments and [square brackets] for optional
<spanclass="k">await</span><spanclass="n">data</span><spanclass="o">.</span><spanclass="n">reply</span><spanclass="p">(</span><spanclass="n">f</span><spanclass="s2">"🍝 Here's your </span><spanclass="si">{args[0]}</span><spanclass="s2">!"</span><spanclass="p">)</span>
<h3>Direct access<aclass="headerlink"href="#direct-access"title="Permalink to this headline">¶</a></h3>
<p>You can consider arguments as if they were separated by spaces.</p>
<p>You can then access command arguments directly by number as if the args object was a list of <aclass="reference external"href="https://docs.python.org/3.7/library/stdtypes.html#str"title="(in Python v3.7)"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">str</span></code></a>.</p>
<p>If you request an argument with a certain number, but the argument does not exist, an
<aclass="reference internal"href="apireference.html#royalnet.error.InvalidInputError"title="royalnet.error.InvalidInputError"><codeclass="xref py py-exc docutils literal notranslate"><spanclass="pre">royalnet.error.InvalidInputError</span></code></a> is raised, making the arguments accessed in this way <strong>required</strong>.</p>
<spanclass="c1"># InvalidInputError() is raised</span>
</pre></div>
</div>
</div>
<divclass="section"id="optional-access">
<h3>Optional access<aclass="headerlink"href="#optional-access"title="Permalink to this headline">¶</a></h3>
<p>If you don’t want arguments to be required, you can access them through the <aclass="reference internal"href="apireference.html#royalnet.commands.CommandArgs.optional"title="royalnet.commands.CommandArgs.optional"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">CommandArgs.optional()</span></code></a> method: it
will return <codeclass="xref py py-const docutils literal notranslate"><spanclass="pre">None</span></code> if the argument wasn’t passed, making it <strong>optional</strong>.</p>
<p>You can specify a default result too, so that the method will return it instead of returning <codeclass="xref py py-const docutils literal notranslate"><spanclass="pre">None</span></code>:</p>
<h3>Full string<aclass="headerlink"href="#full-string"title="Permalink to this headline">¶</a></h3>
<p>If you want the full argument string, you can use the <aclass="reference internal"href="apireference.html#royalnet.commands.CommandArgs.joined"title="royalnet.commands.CommandArgs.joined"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">CommandArgs.joined()</span></code></a> method.</p>
<p>You can specify a minimum number of arguments too, so that an <aclass="reference internal"href="apireference.html#royalnet.error.InvalidInputError"title="royalnet.error.InvalidInputError"><codeclass="xref py py-exc docutils literal notranslate"><spanclass="pre">royalnet.error.InvalidInputError</span></code></a> will be
<spanclass="c1"># InvalidInputError() is raised</span>
</pre></div>
</div>
</div>
<divclass="section"id="regular-expressions">
<h3>Regular expressions<aclass="headerlink"href="#regular-expressions"title="Permalink to this headline">¶</a></h3>
<p>For more complex commands, you may want to get arguments through <aclass="reference external"href="https://regexr.com/">regular expressions</a>.</p>
<p>You can then use the <aclass="reference internal"href="apireference.html#royalnet.commands.CommandArgs.match"title="royalnet.commands.CommandArgs.match"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">CommandArgs.match()</span></code></a> method, which tries to match a pattern to the command argument string,
which returns a tuple of the matched groups and raises an <aclass="reference internal"href="apireference.html#royalnet.error.InvalidInputError"title="royalnet.error.InvalidInputError"><codeclass="xref py py-exc docutils literal notranslate"><spanclass="pre">royalnet.error.InvalidInputError</span></code></a> if there is no match.</p>
<p>To match a pattern, <aclass="reference external"href="https://docs.python.org/3.7/library/re.html#re.match"title="(in Python v3.7)"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">re.match()</span></code></a> is used, meaning that Python will try to match only at the beginning of the string.</p>
<h2>Running code at the initialization of the bot<aclass="headerlink"href="#running-code-at-the-initialization-of-the-bot"title="Permalink to this headline">¶</a></h2>
<p>You can run code while the bot is starting by overriding the <codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">Command.__init__()</span></code> function.</p>
<p>You should keep the <codeclass="docutils literal notranslate"><spanclass="pre">super().__init__(interface)</span></code> call at the start of it, so that the <aclass="reference internal"href="apireference.html#royalnet.commands.Command"title="royalnet.commands.Command"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">Command</span></code></a> instance is
initialized properly, then add your code after it.</p>
<p>You can add fields to the command to keep <strong>shared data between multiple command calls</strong> (but not bot restarts): it may
be useful for fetching external static data and keeping it until the bot is restarted, or to store references to all the
<aclass="reference external"href="https://docs.python.org/3.7/library/asyncio-task.html#asyncio.Task"title="(in Python v3.7)"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">asyncio.Task</span></code></a> started by the bot.</p>
<spanclass="k">await</span><spanclass="n">data</span><spanclass="o">.</span><spanclass="n">reply</span><spanclass="p">(</span><spanclass="n">f</span><spanclass="s2">"⚠️ This pasta was already requested before."</span><spanclass="p">)</span>
<spanclass="k">await</span><spanclass="n">data</span><spanclass="o">.</span><spanclass="n">reply</span><spanclass="p">(</span><spanclass="n">f</span><spanclass="s2">"🍝 Here's your </span><spanclass="si">{pasta}</span><spanclass="s2">!"</span><spanclass="p">)</span>
<p>You may have noticed that in the previous examples we used <codeclass="docutils literal notranslate"><spanclass="pre">await</span><spanclass="pre">data.reply("🍝")</span></code> instead of just <codeclass="docutils literal notranslate"><spanclass="pre">data.reply("🍝")</span></code>.</p>
<p>This is because <aclass="reference internal"href="apireference.html#royalnet.commands.CommandData.reply"title="royalnet.commands.CommandData.reply"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">CommandData.reply()</span></code></a> isn’t a simple method: it is a coroutine, a special kind of function that
can be executed separately from the rest of the code, allowing the bot to do other things in the meantime.</p>
<p>By adding the <codeclass="docutils literal notranslate"><spanclass="pre">await</span></code> keyword before the <codeclass="docutils literal notranslate"><spanclass="pre">data.reply("🍝")</span></code>, we tell the bot that it can do other things, like
receiving new messages, while the message is being sent.</p>
<p>You should avoid running slow normal functions inside bot commands, as they will stop the bot from working until they
are finished and may cause bugs in other parts of the code!</p>
<p>If the slow function you want does not cause any side effect, you can wrap it with the <aclass="reference internal"href="apireference.html#royalnet.utils.asyncify"title="royalnet.utils.asyncify"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">royalnet.utils.asyncify()</span></code></a>
<p>Avoid using <aclass="reference external"href="https://docs.python.org/3.7/library/time.html#time.sleep"title="(in Python v3.7)"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">time.sleep()</span></code></a> function, as it is considered a slow operation: use instead <aclass="reference external"href="https://docs.python.org/3.7/library/asyncio-task.html#asyncio.sleep"title="(in Python v3.7)"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">asyncio.sleep()</span></code></a>,
a coroutine that does the same exact thing.</p>
</div>
<divclass="section"id="accessing-the-database">
<h2>Accessing the database<aclass="headerlink"href="#accessing-the-database"title="Permalink to this headline">¶</a></h2>
<p><codeclass="docutils literal notranslate"><spanclass="pre">self.interface.alchemy</span></code>, and can access the database session at <codeclass="docutils literal notranslate"><spanclass="pre">self.interface.session</span></code>.</p>
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
