mirror of
https://github.com/Limnoria/Limnoria-doc.git
synced 2025-04-04 14:29:46 +00:00
First draft of Command parsing primer and Custom commands (Aka) guide
See GH-114
This commit is contained in:
James Lu
Val Lorentz
96
use/command_parsing.rst
Normal file
96
use/command_parsing.rst
Normal file
@ -0,0 +1,96 @@
|
||||
.. _command-parsing-primer:
|
||||
======================
|
||||
Command parsing primer
|
||||
======================
|
||||
|
||||
This page discusses some of the details and features in Limnoria's command
|
||||
parser, such as the ability to nest commands. This is mainly useful
|
||||
when building :ref:`custom commands <custom-commands>` or
|
||||
message triggers using the :ref:`Aka <plugin-aka>` and
|
||||
:ref:`MessageParser <plugin-messageparser>` plugins.
|
||||
|
||||
.. _quoting-commands:
|
||||
Quoting command arguments
|
||||
-------------------------
|
||||
|
||||
In most cases, commands are simple enough that their arguments don't need to be
|
||||
quoted::
|
||||
|
||||
<jlu5> @echo hello world
|
||||
<Limnoria> hello world
|
||||
|
||||
However, when a command takes in multiple strings, you will have to quote
|
||||
multi-word inputs to prevent them from being split::
|
||||
|
||||
# wrong
|
||||
<jlu5> @sample 1 hello hi what's up
|
||||
<Limnoria> what's
|
||||
|
||||
# right
|
||||
<jlu5> @sample 1 "hello" "hi" "what's up"
|
||||
<Limnoria> hello
|
||||
|
||||
Similarly, if a text argument includes ``"``, ``[``, or ``]``, you'll have to
|
||||
quote it and escape any double quotes::
|
||||
|
||||
<jlu5> @len "waiter, there's a \" in my soup!"
|
||||
<Limnoria> 31
|
||||
|
||||
<jlu5> @echo "test" "test"
|
||||
<Limnoria> test test
|
||||
<jlu5> @echo "\"test\" \"test\""
|
||||
<Limnoria> "test" "test"
|
||||
|
||||
You can use quotes to express an empty argument::
|
||||
|
||||
<jlu5> @format replace a "" abacadabra
|
||||
<Limnoria> bcdbr
|
||||
|
||||
And also to expand non-printable characters::
|
||||
|
||||
<jlu5> @echo \x0308hello world
|
||||
<Limnoria> \x0308hello world
|
||||
|
||||
<jlu5> @echo "\x0308hello world"
|
||||
# this text would be yellow on IRC
|
||||
<Limnoria> hello world
|
||||
|
||||
.. _nested-commands:
|
||||
Nested commands
|
||||
---------------
|
||||
|
||||
Commands can be nested in Limnoria by surrounding them in square brackets.
|
||||
This example runs some text through two commands from the
|
||||
:ref:`Filter <plugin-filter>` plugin::
|
||||
|
||||
<jlu5> @caps [filter reverse hello world]
|
||||
<Limnoria> DLROW OLLEH
|
||||
|
||||
Similarly, the output of multiple commands can be combined using
|
||||
:ref:`echo <command-utilities-echo>` or :ref:`reply <command-reply-reply>`.
|
||||
The below command flips two coins using the :ref:`plugin-games` plugin::
|
||||
|
||||
<jlu5> @echo [coin] [coin]
|
||||
<Limnoria> heads tails
|
||||
|
||||
<jlu5> @reply [coin] [coin]
|
||||
<Limnoria> jlu5: heads heads
|
||||
|
||||
There are a few differences between ``echo`` and ``reply``:
|
||||
|
||||
- ``reply`` always prefixes the output with the caller's nick, while ``echo`` does not.
|
||||
- ``echo`` supports standard substitutions, such as ``$nick``, ``$version``, etc., while ``reply`` does not
|
||||
|
||||
Note that the bot will always add spaces around the output of a nested
|
||||
command. To work around this, you may want to use the
|
||||
:ref:`Filter squish <command-filter-squish>` command to remove stray spaces::
|
||||
|
||||
<jlu5> @echo Random percent value: [dice 1d100]%
|
||||
<Limnoria> Random percent value: 56 %
|
||||
|
||||
<jlu5> @echo Random percent value: [squish [dice 1d100]%]
|
||||
<Limnoria> Random percent value: 78%
|
||||
|
||||
The above example shows how commands can be nested more than once as well; this
|
||||
limit is controlled by the :ref:`config option <configuration-guide>`
|
||||
``commands.nested.maximum``.
|
||||
163
use/custom_commands.rst
Normal file
163
use/custom_commands.rst
Normal file
@ -0,0 +1,163 @@
|
||||
.. _custom-commands:
|
||||
|
||||
===============================
|
||||
Creating custom commands (Akas)
|
||||
===============================
|
||||
|
||||
Limnoria allows you create custom bot commands, also known as aliases, without
|
||||
writing a full Python plugin. This feature is provided by the
|
||||
:ref:`Aka <plugin-aka>` plugin, and can be combined with
|
||||
:ref:`nested commands <nested-commands>` to create expressive commands.
|
||||
|
||||
Before proceeding through this page, we recommend reading the
|
||||
:ref:`command-parsing-primer`, which discusses many of the details that apply
|
||||
to building custom commands.
|
||||
|
||||
.. contents::
|
||||
|
||||
Creating & managing aliases
|
||||
---------------------------
|
||||
|
||||
Add an alias, ``trout``, which expects one argument (``$1``). This alias requires
|
||||
the :ref:`plugin-reply` plugin to be loaded since it
|
||||
provides the :ref:`action <command-reply-action>` command::
|
||||
|
||||
<jamessan> @aka add trout "reply action slaps $1 with a large trout"
|
||||
<Limnoria> The operation succeeded.
|
||||
# $1 will be replaced with the input to @trout
|
||||
<jamessan> @trout me
|
||||
* Limnoria slaps me with a large trout
|
||||
|
||||
You can also replace an existing alias with ``aka set``::
|
||||
|
||||
<jlu5> @aka set trout "reply Sorry, we're all out of fish!"
|
||||
<Limnoria> The operation succeeded.
|
||||
|
||||
To remove an alias, use ``aka remove``::
|
||||
|
||||
<jlu5> @aka remove trout
|
||||
<Limnoria> The operation succeeded.
|
||||
|
||||
Alias with nested commands
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Add an alias, ``randpercent``, which returns a random percentage value.
|
||||
This requires the :ref:`plugin-filter` and :ref:`plugin-games` plugins for
|
||||
:ref:`squish <command-filter-squish>` and :ref:`dice <command-games-dice>`
|
||||
respetively::
|
||||
|
||||
<jlu5> @aka add randpercent "squish [dice 1d100]%"
|
||||
<Limnoria> The operation succeeded.
|
||||
<jlu5> @randpercent
|
||||
<Limnoria> 66%
|
||||
|
||||
.. note::
|
||||
|
||||
When defining aliases, you almost always want to **quote the contents** of
|
||||
the alias, so that any nested commands are expanded when the actual alias is
|
||||
ran, instead of when the ``aka add`` call happens.
|
||||
|
||||
In this above example, not quoting the ``dice`` command would mean that the
|
||||
``randpercent`` always returns the same value!
|
||||
|
||||
This, in conjunction with Limnoria's :ref:`command quoting rules <quoting-commands>`
|
||||
means that aliases towards nested commands may require **two levels of quoting**,
|
||||
with the inner quotes additionally escaped. This example uses the
|
||||
:ref:`sample <command-utilities-sample>` command from the :ref:`plugin-utilities` plugin::
|
||||
|
||||
<jlu5> @aka add greetme "reply [sample 1 \"hi there!\" \"what's up?\" \"how are you?\"]"
|
||||
<Limnoria> The operation succeeded.
|
||||
<jlu5> @greetme
|
||||
<Limnoria> jlu5: what's up?
|
||||
<jlu5> @greetme
|
||||
<Limnoria> jlu5: hi there!
|
||||
|
||||
Passing multiple arguments
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Aliases can pass multiple arguments (``$1``, ``$2``, etc.), as well as all
|
||||
remaining arguments (``$*``) to another command. A common use case of this
|
||||
is to define short-forms to other commands, such as ``config``::
|
||||
|
||||
<jlu5> @aka add cf "config $*"
|
||||
<Limnoria> The operation succeeded.
|
||||
|
||||
# using this alias
|
||||
<jlu5> @cf reply.whenaddressedby.chars
|
||||
<Limnoria> @
|
||||
|
||||
Note that the following also works, because ``config`` is technically ambiguous
|
||||
(it can refer to either the :ref:`plugin-config` plugin or the
|
||||
:ref:`config <command-config-config>` command)::
|
||||
|
||||
# "@cf help" expands to "@config help"
|
||||
<jlu5> @cf help reply.whenaddressedby.chars
|
||||
<Limnoria> Determines what prefix characters the bot will reply to. -snip-
|
||||
|
||||
Conditionals and optional arguments
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Aliases also support optional arguments, using ``@1``, ``@2``, etc. instead of
|
||||
``$1`` and ``$2``. This can be combined with the :ref:`plugin-conditional`
|
||||
plugin to make a custom command behave differently depending on how many
|
||||
arguments were passed in.
|
||||
|
||||
Here's a variant of the ``trout`` example from earlier, which will now slap the
|
||||
caller if no argument was passed in. It uses:
|
||||
|
||||
* The :ref:`command-conditional-cif` and :ref:`command-conditional-ceq` commands
|
||||
to define an if expression and check whether ``@1`` is an empty string.
|
||||
* The :ref:`echo <command-utilities-echo>` command from the :ref:`plugin-utilities` plugin.
|
||||
|
||||
::
|
||||
|
||||
<jlu5> @aka add trout "reply action slaps [cif [ceq \"@1\" \"\"] \"echo $nick\" \"echo @1\"] with a large trout"
|
||||
<Limnoria> The operation succeeded.
|
||||
<jlu5> @trout Limnoria
|
||||
* Limnoria slaps Limnoria with a large trout
|
||||
<jlu5> @trout
|
||||
* Limnoria slaps jlu5 with a large trout
|
||||
|
||||
Referring to other Akas
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Because command aliases are expanded at runtime, they can refer to one another,
|
||||
and even themselves.
|
||||
|
||||
Suppose I define an alias for the :ref:`sample <command-utilities-sample>` command::
|
||||
|
||||
<jlu5> @aka add choose "sample 1 $*"
|
||||
<Limnoria> The operation succeeded.
|
||||
|
||||
Then I can define more aliases using the ``choose`` command::
|
||||
|
||||
<jlu5> @aka add bloom "choose 🌼 💐 🌹 🌻 🌺 🌸"
|
||||
<Limnoria> The operation succeeded.
|
||||
<jlu5> @bloom
|
||||
<Limnoria> 💐
|
||||
|
||||
For completeness, here's an example of a (not particularly efficient) factorial
|
||||
command. It additionally uses the :ref:`plugin-Math` plugin's
|
||||
:ref:`calc <command-math-calc>` command::
|
||||
|
||||
<jlu5> @aka add factorial "cif [nle $1 1] \"echo 1\" \"calc [factorial [calc $1 - 1]] * $1\""
|
||||
<Limnoria> The operation succeeded.
|
||||
<jlu5> @factorial 8
|
||||
<Limnoria> 40320
|
||||
<jlu5> @factorial 10
|
||||
<Limnoria> Error: You've attempted more nesting than is currently allowed on this bot.
|
||||
|
||||
Replacing an existing command with your own
|
||||
-------------------------------------------
|
||||
|
||||
TODO
|
||||
|
||||
Limitations, and when to write a plugin instead
|
||||
-----------------------------------------------
|
||||
|
||||
TODO
|
||||
|
||||
Final notes
|
||||
-----------
|
||||
|
||||
TODO: interaction with capabilities
|
||||
@ -12,6 +12,8 @@ User Guide
|
||||
getting_started.rst
|
||||
configuration.rst
|
||||
identifying_to_services.rst
|
||||
command_parsing.rst
|
||||
custom_commands.rst
|
||||
capabilities.rst
|
||||
security.rst
|
||||
httpserver.rst
|
||||
|
||||
Reference in New Issue
Block a user