Provides functionality for defining and managing macros. Macros defined by this
plugin are available to all users in all channels on the current network, and
persist across bot restarts.
=cut
has'+name'=> (
default=> 'Core::Macro',
);
has'+description'=> (
default=> 'Provides functionality for defining and managing macros. Macros defined by this plugin are available to all users in all channels on the current network, and persist across bot restarts.',
);
=head2 defmacro
=head3 Description
Macros are user-defined functions, and any channel members with permission to
call ``(defmacro)`` may define their own macros. Name collisions between macros
and builtin functions are always resolved in favor of the functions.
Macro names may contain any valid identifier characters, including many forms
of punctuation and Unicode glyphs (as long as your chat network supports their
transmission). The primary restrictions on macro names are:
* They cannot begin with a colon ``:`` character (that is reserved for Symbols).
* They cannot contain whitespace.
* They cannot be a valid Numeric (have an optional leading dash, include a decimal separator, and otherwise consist only of numbers).
* They cannot contain a slash ``/`` as that is the function namespace separator.
The macro argument list is a vector of names to which arguments will be bound
whenever the macro is invoked. The may be used repeatedly within the macro
body, but bear in mind they are replaced during macro expansion with the value
of the argument. They are not mutable variables.
Unless otherwise indicated, all macro arguments are considered mandatory, and
calling the macro without them will result in an error. To mark arguments as
optional, they must follow a ``&optional`` symbol in the argument vector. In
addition to optional arguments, you may mark a single argument as the target
for all remaining arguments that may have been passed to the macro, after all
of the explicit arguments are bound. This is done by placing the name to which
they will be bound as a list after the ``&rest`` symbol in the argument vector.
Finally, the macro body expression may be any valid quoted expression and as
such may invoke other macros. The names from your argument vector will be
available for use within the entire macro body.
=head3 Usage
<macro name> <vector of arguments> <macro body expression>
Undefines the named macro. This is a permanent action and if the named macro is
desired again, it must be recreated from scratch.
If the macro has been locked by its author, only they may undefine it. Anyone
else attempting to remove the macro will receive an error explaining that it is
currently locked.
=head3 Usage
<macro name>
=head2 show-macro
=head3 Description
Displays a macro's definition and who authored it.
=head3 Usage
<macro name>
=head2 list-macros
=head3 Description
Displays a list of all registered macros. Optional pattern will limit list to
only those macros whose names match.
=head3 Usage
[<pattern>]
=head2 lock-macro
=head3 Description
Locks a macro from further modification or deletion. This function is only
available to the author of the macro.
=head3 Usage
<macro name>
=head2 unlock-macro
=head3 Description
Unlocks a previously locked macro, allowing it to once again be modified or
deleted. This function is only available to the author of the macro.
=head3 Usage
<macro name>
=cut
has'+commands'=> (
default=> sub{{
'defmacro'=> { method=> 'define_macro',
preprocess_args=> 0,
description=> 'Defines a new macro, or replaces an existing macro of the same name. Macros may call, or even create/modify/delete other macros.',
usage=> '<name> (<... argument list ...>) \'(<definition body list>)',
example=> "plus-one (a) '(+ a 1)"},
'undefmacro'=> { method=> 'undefine_macro',
description=> 'Undefines an existing macro.',
usage=> '<name>'},
'show-macro'=> { method=> 'show_macro',
description=> 'Displays the definition of a macro.',
usage=> '<name>'},
'list-macros'=> { method=> 'list_macros',
description=> 'Displays a list of all registered macros. Optional pattern will limit list to only those macros whose names match.',
usage=> '[<pattern>]', },
'lock-macro'=> { method=> 'lock_macro',
description=> 'Locks a macro from further modification or deletion. This function is only available to the author of the macro.',
usage=> '<macro name>'},
'unlock-macro'=> { method=> 'unlock_macro',
description=> 'Unlocks a previously locked macro, allowing it to once again be modified or deleted. This function is only available to the author of the macro.',