alchemy v0.2.0 Alchemy.Cogs
This module provides quite a bit of sugar for registering commands.
To use the macros in this module, it must be used
. This also defines a
__using__
macro for that module, which will then allow these commands
to be loaded in the main application via use
Note
Be careful not to define multiple commands with the same name. The last module loaded will have their version active.
Example Usage
defmodule Example do
use Alchemy.Cogs
Cogs.def ping, do: Cogs.say "pong!"
Cogs.def echo do
Cogs.say "please give me a word to echo"
end
Cogs.def echo("foo") do
Cogs.say "foo are you?"
end
Cogs.def echo(word) do
Cogs.say word
end
end
Then you can load this cog in at runtime, or anytime after starting the client
use Example
If you need to remove this cog from the handler:
Cogs.unload(Example)
Or you just want to disable a single function:
Cogs.disable(:ping)
Summary
Functions
Disables a command
Sets the client’s command prefix to a specific string
Unloads a module from the handler
Macros
Registers a new command, under the name of the function
Gets the guild struct from which a command was triggered
Gets the id of the guild from which a command was triggered
Gets the member that triggered a command
Sends a message to the same channel as the message triggering a command
Allows you to register a custom message parser for a command
Types
Functions
Specs
disable(atom) :: :ok
Disables a command.
If you want to remove a whole module from the cogs, use Cogs.unload/1
.
This will stop a command from being triggered. The only way to reenable the
command is to reload the module with use
.
Examples
defmodule Example do
use Alchemy.Cogs
Cogs.def ping, do: Cogs.say "pong"
Cogs.def foo, do: Cogs.say "bar"
end
Client.start(@token)
use Example
Cogs.disable(:foo)
Only ping
will be triggerable now.
use Example
At runtime this will add foo
back in, given it’s still in the module.
Specs
set_prefix(String.t) :: :ok
Sets the client’s command prefix to a specific string.
This will only work after the client has been started
Example
Client.start(@token)
Cogs.set_prefix("!!")
Specs
unload(atom) :: :ok
Unloads a module from the handler.
If you just want to disable a single command, use Cogs.disable/1
Examples
Client.start(@token)
use Commands2
Turns out we want to stop using Commands2
commands in our bot, so we
can simply unload the module:
Cogs.unload(Commands2)
Now none of the commands defined in that module will be accessible. If we want to reverse that, we can merely do:
use Commands2
and reload them back in.
Macros
Registers a new command, under the name of the function.
This macro modifies the function definition, to accept an extra
message
parameter, allowing the message that triggered the command to be passed,
as a t:Alchemy.Message/0
Examples
Cogs.def ping do
Cogs.say "pong"
end
In this case, “!ping” will trigger the command, unless another prefix has been set
with set_prefix/1
Cogs.def mimic, do: Cogs.say "Please send a word for me to echo"
Cogs.def mimic(word), do: Cogs.say word
Messages will be parsed, and arguments will be extracted, however, to deal with potentially missing arguments, pattern matching should be used. So, in this case, when a 2nd argument isn’t given, an error message is sent back.
Gets the guild struct from which a command was triggered.
If only the id is needed, see :guild_id/0
Examples
Cogs.def guild do
{:ok, %Alchemy.Guild{name: name}} = Cogs.guild()
Cogs.say(name)
end
Gets the id of the guild from which a command was triggered.
This is to be used when the guild_id is necessary for an operation, but the full guild struct isn’t needed.
Gets the member that triggered a command.
As opposed to message.author
, this comes with a bit more info about who
triggered the command. This is useful for when you want to use certain information
in a command, such as permissions, for example.
Sends a message to the same channel as the message triggering a command.
This can only be used in a command defined with Cogs.def
This is just a thin macro around Alchemy.Client.send_message/2
Examples
Cogs.def ping, do: Cogs.say("pong!")