Maiden-Commands

This agent is responsible for catching message-events and turning them into command-events if apropriate. It also gives you the define-command macro to define user-invokable commands with.

How To

In order to define a command, use define-command, which will generate a matching event, function, and handler for you, similar to define-instruction. It will also create the appropriate translation for you through define-command-invoker.

First, let's create a consumer and add a command to it.

(maiden:define-consumer tester () ())

(maiden-commands:define-command (tester greet) (instance event name &optional greeting)
  (maiden:reply event "~a, ~a" (or greeting "Hello") name))

Now we have to create a test environment for us to work with.

(defvar *core* (maiden:make-simple-core 'maiden-commands:commands 'tester))

We can now call the command as a function.

(greet *core* "someone")

Or through a message that is recognised as a command.

(maiden-commands:issue-message *core* "::greet you")

In order for the latter to work, the commands agent must be present on the core.

You can manipulate what is recognised as a command message through the extractors. Calling remove-command-extractor on prefix will stop the double-colons from being recognised as a command prefix. You can add arbitrary functions that do what you want through define-command-extractor. The function should return the substring of the event's message that contains the actual command, or NIL if it is not a command message.

Package Index

MAIDEN-COMMANDS (ORG.SHIRAKUMO.MAIDEN.AGENTS.COMMANDS)

class

`COMMAND-EVENT`

Superclass for all command events.

The dispatch-event defaults to either *DISPATCH-EVENT*, or
if it is not present, an instance of FRAMEWORK-MESSAGE.

Command events are by default advised to be public. If a
command should not be publicly accessible, you need to set
the advice to (not public).

See DISPATCH-EVENT
See MAIDEN:INSTRUCTION-EVENT
See MAIDEN:ACTIVE-EVENT

class

`COMMAND-INVOKER`

Container class to hold a command invoker.

Command invokers are responsible for parsing a command line
and turning it into a command event instance, which is then
issued onto a core to cause the actual command to be executed.

See NAME
See PREFIX
See LAMBDA-LIST
See INVOKER

class

`COMMANDS`

Agent to allow users to issue commands over messages. It is responsible for detecting, parsing, and issuing the commands as events.

class

`FRAMEWORK-MESSAGE`

A message event used to simulate commands or issue them without a specific client for them to come from.

See *FRAMEWORK-CLIENT*
See *FRAMEWORK-USER*
See MAIDEN-CLIENT-ENTITIES:MESSAGE-EVENT
See MAIDEN:PASSIVE-EVENT

condition

`COMMAND-CONDITION`

Superclass for all conditions related to the command system.

See MAIDEN:MAIDEN-CONDITION

condition

`DESTRUCTURING-ERROR`

Superclass for all conditions related to the destructuring of argument lists.

See COMMAND-CONDITION

condition

`EXPECTED-KEY-ERROR`

Error signalled when a key was expected, but could not be found.

See LEXING-ERROR

condition

`LEXING-ERROR`

Superclass for all conditions related to the lexing and parsing of commands.

See COMMAND-CONDITION

condition

`NOT-ENOUGH-ARGUMENTS-ERROR`

Error signalled when the argument list was too short and could not satisfy the lambda-list.

See DESTRUCTURING-ERROR

accessor (

`COMMAND-EXTRACTOR`

NAME)

Accessor to set/get the command-extractor of a given name.

See *EXTRACTORS*

accessor (

`COMMAND-INVOKER`

NAME)

Accessor to the command-invoker of the given name.

See COMMAND-INVOKER
See *INVOKERS*

accessor (

`INVOKER`

OBJECT)

Accessor to the command invoker's invocation function.

The invoker is responsible for parsing the message,
destructuring it into the arguments necessary to produce the
command event, and finally issuing the complete event onto
the same core as the one the event originated from.

The function must take two arguments, the event that caused
the command, and the command string that needs to be parsed.

See COMMAND-INVOKER

accessor (

`LAMBDA-LIST`

OBJECT)

Accessor to the command invoker's lambda-list.

Note that this is not equal to the invoker's lambda-list.

See COMMAND-INVOKER

accessor (

`NAME`

OBJECT)

Aecessor to the name of the entity.

See NAMED-ENTITY

accessor (

`PREFIX`

OBJECT)

Accessor to the prefix that must be present in the command string for the invoker to be considered for it.

See COMMAND-INVOKER

function (

`CONSUMER-COMMANDS`

CONSUMER)

Attempts to collect a list of all command invokers that the consumer defined.

This is a heuristic and may not find everything if the
developer of the commands is being sneaky. It works by
going through all handlers defined on the consumer, looking
at each handler's typespec, and checking whether it contains
a type that is a subclass of COMMAND-EVENT. If so, a command-
invoker by the name of the handler is attempted to be found.

function (

`FIND-COMMAND-INVOKER`

NAME)

Attempt to find a command-invoker of the given name or prefix.

See *INVOKERS*

function (

`FIND-MATCHING-COMMAND`

MESSAGE)

Attempt to find a command that matches the message.

Returns two values-- the matching command-invoker if it
could be found, and a list of alternatives, where each
alternative is a cons cell of its distance to the message
and the command-invoker.

See COMPARE-ALTERNATIVES
See LEVENSHTEIN-DISTANCE
See *ALTERNATIVE-DISTANCE-THRESHOLD*

function (

`ISSUE-MESSAGE`

CORE COMMAND-STRING)

Issue a framework message onto the core.

See FRAMEWORK-MESSAGE

function (

`LIST-COMMAND-INVOKERS`

)

Return a fresh list of all command-invokers.

See COMMAND-INVOKER
See *INVOKERS*

function (
RELAY
EV NEW-COMMAND &REST ARGS)
```
 
```

function (

`REMOVE-COMMAND`

CONSUMER NAME &OPTIONAL (EVENT-TYPE NAME) (COMMAND (STRING NAME)))

Remove a command from the system.

See REMOVE-FUNCTION-HANDLER
See REMOVE-COMMAND-INVOKER

function (

`REMOVE-COMMAND-EXTRACTOR`

NAME)

Remove the command-extractor of the given name.

See *EXTRACTORS*

function (

`REMOVE-COMMAND-INVOKER`

NAME)

Remove the command-invoker of the given name.

See COMMAND-INVOKER
See *INVOKERS*

generic (

`COMMAND-P`

EVENT)

Returns true if the event can be interpreted as a command.

See EXTRACT-COMMAND

generic (

`DISPATCH-EVENT`

OBJECT)

Reader for the original event that lead to the command event being dispatched.

See COMMAND-EVENT

generic (

`EXTRACT-COMMAND`

EVENT)

Attempt to extract a command string from the event.

If this is not possible, NIL is returned.

macro (

`DEFINE-COMMAND`

&REST ARGS)

Define a new command.

This will define a new event for the command, a new handler
for the event that will actually cause the desired code to
be executed, and a command-invoker that is responsible for
parsing the command from a message and issuing the event.

The event will always have COMMAND-EVENT as a superclass,
but you can specify additional superclasses through the
usual body option.

The following additional body options are present and will
not be passed to DEFINE-FUNCTION-HANDLER:
- :COMMAND                
  The prefix string that will cause the command to be parsed
  from a string. This prefix can contain any character
  sequence you want, the system will be able to deal with it.
  Defaults to the command name.
- :COMMAND-EVENT-VARIABLE
  The variable that the command-event is bound to. This is
  not the same as the EVENT argument. The EVENT argument is
  bound to the dispatching event of the command, which is
  usually what you want to inspect and reply to. The command-
  event may be useful in some circumstances, but usually it
  will just be a carrier for the arguments, which will
  already have been bound to distinct variables.

If an error occurs during the execution of the command's
body, a REPLY is done to the dispatching event with the
message set to the error printed as a string.

Within the body, *DISPATCH-EVENT* is bound to the dispatching
event instance.

See REPLY
See *DISPATCH-EVENT*
See MAIDEN:DEFINE-FUNCTION-HANDLER
See DEFINE-SIMPLE-COMMAND-INVOKER
See REMOVE-COMMAND

macro (

`DEFINE-COMMAND-EXTRACTOR`

&REST ARGS)

Define a new command extractor.

See *EXTRACTORS*

macro (

`DEFINE-COMMAND-INVOKER`

&REST ARGS)

Define a new command-invoker.

The body defines the command-invoker's invoker function, with
the lambda-list making up the lambda-list for WITH-COMMAND-
DESTRUCTURING-BIND. The message is thus already properly
parsed into the necessary arguments within the body.

See COMMAND-INVOKER
See INVOKER
See WITH-COMMAND-DESTRUCTURING-BIND

macro (

`DEFINE-SIMPLE-COMMAND-INVOKER`

&REST ARGS)

Define a new, simple command-invoker.

This defines a command-invoker that simple issues a given
event onto the loop, using the arguments to fill in the
initargs of the event. The MESSAGE-EVENT-INITARG option
specifies which initarg, if any, the dispatching event should
be passed to.

See DEFINE-COMMAND-INVOKER

macro (

`WITH-COMMAND-DESTRUCTURING-BIND`

&REST ARGS)

Destructure the INPUT string according to the lambda-list.

Required, optional, key, and rest arguments are supported.

If the arguments cannot be parsed or if they do not match
the lambda-list, an error is signalled.

See GENERATE-LAMBDA-LIST-BINDINGS
See LEX

maiden-commands

Maiden-Commands

How To

Copyright

Package Index

MAIDEN-COMMANDS (ORG.SHIRAKUMO.MAIDEN.AGENTS.COMMANDS)

`COMMAND-EVENT`

`COMMAND-INVOKER`

`COMMANDS`

`FRAMEWORK-MESSAGE`

`COMMAND-CONDITION`

`DESTRUCTURING-ERROR`

`EXPECTED-KEY-ERROR`

`LEXING-ERROR`

`NOT-ENOUGH-ARGUMENTS-ERROR`

`COMMAND-EXTRACTOR`

`COMMAND-INVOKER`

`INVOKER`

`LAMBDA-LIST`

`NAME`

`PREFIX`

`CONSUMER-COMMANDS`

`FIND-COMMAND-INVOKER`

`FIND-MATCHING-COMMAND`

`ISSUE-MESSAGE`

`LIST-COMMAND-INVOKERS`

`RELAY`

`REMOVE-COMMAND`

`REMOVE-COMMAND-EXTRACTOR`

`REMOVE-COMMAND-INVOKER`

`COMMAND-P`

`DISPATCH-EVENT`

`EXTRACT-COMMAND`

`DEFINE-COMMAND`

`DEFINE-COMMAND-EXTRACTOR`

`DEFINE-COMMAND-INVOKER`

`DEFINE-SIMPLE-COMMAND-INVOKER`

`WITH-COMMAND-DESTRUCTURING-BIND`