3.1.0 A modern and extensible chat bot framework.
Table of Contents
About Maiden
Maiden is a collection of systems to help you build applications and libraries that interact with chat servers. It can help you build a chat bot, or a general chat client. It also offers a variety of parts that should make it much easier to write a client for a new chat protocol.
How To Use Maiden as a Bot
If you only care about using Maiden to set up a bot of some kind, the steps to do so are rather straightforward. First we'll want to load in Maiden and all of the modules and components that you'd like to use in your bot.
(ql:quickload '(maiden maiden-irc maiden-commands maiden-silly))And then we'll create a core with instances of the consumers added to it as we'd like them to be.
(defvar *core* (maiden:make-core
'(:maiden-irc :nickname "MaidenTest" :host "irc.freenode.net" :channels ("##testing"))
:maiden-commands
:maiden-silly))The make-core command takes either package names (as strings or symbols) of consumers to add, or the direct class name of a consumer. In the former case it'll try to find the appropriate consumer class name on its own.
And that's it. make-core will create a core, instantiate all the consumers, add them to it, and start everything up. A loot of the modules provided for Maiden will make use of some kind of configuration or persistent storage. For the management thereof, see the storage subsystem.
How To Use Maiden as a Framework to Develop With
In order to use Maiden as a framework, you'll first want to define your own system and package as usual for a project. For now we'll just use the maiden-user package to play around in. Next we'll want to define a consumer. This can be done with define-consumer.
(in-package #:maiden-user)
(define-consumer ping-notifier (agent)
())Usually you'll want to define an agent. Agents can only exist once on a core. We'll go through an example for a client later. Now, from here on out we can define our own methods and functions that specialise or act on the consumer class as you'd be used to from general CLOS programming. Next, we'll define our own event that we'll use to send "ping requests" to the system.
(define-event ping (passive-event)
())The event is defined as a passive-event as it is not directly requesting an action to be taken, but rather informs the system of a ping that's happening. Now, in order to actually make the consumer interact with the event system however, we'll also want to define handlers. This can be done with define-handler.
(define-handler (ping-notifier ping-receiver ping) (c ev)
(v:info :ping "Received a ping: ~a" ev))This defines a handler called ping-receiver on our ping-notifier consumer. It also specifies that it will listen for events of type ping. The arglist afterwards says that the consumer instance is bound to c and the event instance to ev. The body then simply logs an informational message using Verbose.
Let's test this out real quick.
(defvar *core* (make-core 'ping-notifier))
(do-issue *core* ping)That should print the status message to the REPL as expected. And that's most of everything there is to using this system. Note that in order to do actually useful things, you'll probably want to make use of some of the preexisting subsystems that the Maiden project delivers aside from the core. Those will help you with users, channels, accounts, commands, networking, storage, and so forth. Also keep in mind that you can make use of the features that Deeds offers on its own as well, such as filtering expressions for handlers.
Now let's take a look at a primitive kind of client. The client will simply be able to write to a file through events.
(define-consumer file-client (client)
((file :initarg :file :accessor file))
(:default-initargs :file (error "FILE required.")))
(define-event write-event (client-event active-event)
((sequence :initarg :sequence))
(:default-initargs :sequence (error "SEQUENCE required.")))We've made the write-event a client-event since it needs to be specific to a client we want to write to, and we've made it an active-event since it requests something to happen. Now let's define our handler that will take care of actually writing the sequence to file.
(define-handler (file-client writer write-event) (c ev sequence)
:match-consumer 'client
(with-open-file (stream (file c) :direction :output :if-exists :append :if-does-not-exist :create)
(write-sequence sequence stream)))The :match-consumer option modifies the handler's filter in such a way that the filter will only pass events whose client slot contains the same file-client instance as the current handler instance belongs to. This is important, as each instance of file-client will receive its own instances of its handlers on a core. Without this option, the write-event would be handled by every instance of the file-client regardless of which instance the event was intended for. Also note that we added a sequence argument to the handler's arglist. This argument will be filled with the appropriate slot from the event. If no such slot could be found, an error is signalled.
Time to test it out. We'll just reuse the core from above.
(add-to-core *core* '(file-client :file "~/foo" :name :foo)
'(file-client :file "~/bar" :name :bar))
(do-issue *core* write-event :sequence "foo" :client (consumer :foo *core*))
(do-issue *core* write-event :sequence "bar" :client (consumer :bar *core*))
(alexandria:read-file-into-string "~/foo") ; => "foo"
(alexandria:read-file-into-string "~/bar") ; => "bar"As you can see, the events were directed to the appropriate handler instances according to the client we wanted, and the files thus contain what we expect them to.
Finally, it is worth mentioning that it is also possible to dynamically add and remove handlers at runtime, and even do so for handlers that are not associated with a particular consumer. This is often useful when you need to wait for a response event from somewhere. To handle the logic of doing this asynchronously and retain the impression of an imperative flow, Maiden offers --just as Deeds does-- a with-awaiting macro. It can be used as follows:
(with-awaiting (core event-type) (ev some-field)
(do-issue core initiating-event)
:timeout 20
some-field)with-awaiting is very similar to define-handler, with the exception that it doesn't take a name, and instead of a consumer name at the beginning it needs a core or consumer instance. It also takes one extra option that is otherwise unused, the :timeout. Another required extra is the "setup form" after the arglist. In order to properly manage everything and ensure no race conditions may occur in the system, you must initiate the process that will prompt the eventual response event in this setup form. If you initiate it before then, the response event might be sent out before the temporary handler is set up in the system and it'll appear as if it never arrived at all.
And that's pretty much all of the basics. As mentioned above, take a look at the subsystems this project includes, as they will help you with all sorts of common tasks and problems revolving around chat systems and so on.
Core Documentation
Before understanding Maiden, it is worth it to understand Deeds, if only at a surface level. Maiden builds on it rather heavily.
Core
A core is the central part of a Maiden configuration. It is responsible for managing and orchestrating the other components of the system. You can have multiple cores running simultaneously within the same lisp image, and can even share components between them.
More specifically, a Core is made up of an event-loop and a set of consumers. The event-loop is responsible for delivering events to handlers. Consumers are responsible for attaching handlers to the event-loop. The operations you will most likely want to perform on a core are thus: issuing events to it by issue, adding consumers to it by add-consumer, or removing a consumer from it by remove-consumer.
In order to make it easier on your to create a useful core with consumers added to it, you can make use of the make-core and add-to-core functions.
Event
An event is an object that represents a change in the system. Events can be used to either represent a change that has occurred, or to represents a request for a change to happen. These are called passive-events and active-events respectively.
Generally you will use events in the following ways:
- Consuming them by writing a handler that takes events of a particular type and does something in response to them.
- Define new event classes that describe certain behaviour.
- Emitting them by writing components that inform the system about changes.
Consumer
A consumer is a class that represents a component in the system. Each consumer can have a multitude of handlers tied to it, which will react to events in the system. Consumers come in two basic supertypes, agents and clients. Agents are consumers that should only exist on a core once, as they implement functionality that would not make sense to be multiplexed in some way. Clients on the other hand represent some kind of bridge to an outside system, and naturally should be allowed to have multiple instances on the same core.
Thus developing a set of commands or an interface of some kind would probably lead to an agent, whereas interfacing with a service like XMPP would lead to a client.
Defining a consumer should happen with define-consumer, which is similar to the standard defclass, but ensures that the superclasses and metaclasses are properly set up.
Handler
handlers are objects that hold a function that performs certain actions when a particular event is issued onto the core. Each handler is tied to a particular consumer and is removed or added to the core's event-loop when the consumer is removed or added to the core.
Handler definition happens through one of define-handler, define-function-handler, define-instruction, or define-query. Which each successively build on the last to provide a broader shorthand for common requirements. Note that the way in which a handler actually receives its events can differ. Have a look at the Deeds' documentation to see what handler classes are available.
Subsystems
Included in the Maiden project are a couple of subsystems that extend the core functionality.
- API Access -- Helper functions to access remote APIs over HTTP.
- Client Entities -- Common entities for clients and remote systems.
- Networking -- Client mixins to handle network connections.
- Serialize -- Data to wire serialization.
- Storage -- Configuration and data storage.
Existing Clients
The Maiden project also includes a few standard clients that can be used right away.
- IRC -- Internet Relay Chat client.
- Lichat -- Lichat client.
- Relay -- Maiden relay. Allows connecting remote Maiden cores.
Existing Agents
Finally, the project has a bunch of agent modules that provide functionality that is useful for creating chat bots and such. They, too, can be used straight away.
- accounts -- User accounts.
- activatable -- Allow activating or deactivating consumer's handlers.
- blocker -- Block commands by rules.
- chatlog -- Log channels to a database.
- commands -- Provide a common command infrastructure.
- core-manager -- Manage the core's consumers and parts.
- counter -- Count occurrences in message events.
- crimes -- Lets the user play "Crimes", a Cards Against Humanity clone.
- emoticon -- Provides :emote:s in messages.
- help -- A generic command help system.
- location -- Allows retrieving location information.
- markov -- Provides efficient markov chains.
- medals -- Gives commands to hand out "medals" to users.
- notify -- Allow sending users notification messages.
- permissions -- Manage command permissions.
- quicklisp -- Operate Quicklisp and system updates through commands.
- silly -- Adds some silly commands and automatic message responses.
- talk -- Allows playing Text To Speech messages on the machine Maiden runs on.
- throttle -- Throttle users to prevent them from issuing too many commands.
- time -- Provides time information.
- trivia -- Implements a simple trivia game.
- urlinfo -- Retrieves information about URLs.
- weather -- Provides weather and forecast information for a location.
System Information
Definition Index
-
MAIDEN
- ORG.SHIRAKUMO.MAIDEN
No documentation provided.-
EXTERNAL SPECIAL-VARIABLE *DEBUGGER*
This variable sets whether an internal error should call out to the debugger or not. On deployed systems, this should probably be NIL. The default value is whether the SWANK package is present or not.
-
EXTERNAL SPECIAL-VARIABLE *ROOT*
This variable holds a directory pathname that points to the "root" of the Maiden installation. The root should mainly be used for storage of runtime fragments such as configuration, cache, and so forth.
-
EXTERNAL CLASS ABSTRACT-HANDLER
This is an object to represent a handler definition. It contains all data necessary to construct an appropriate handler instance for a consumer. See ADD-TO-CONSUMER See TARGET-CLASS See OPTIONS See INSTANTIATE-HANDLER See DEFINE-HANDLER
-
EXTERNAL CLASS ACTIVE-EVENT
Superclass for all active events in the system. An active event notifies of a request for an action to be taken somewhere in the system. It is active in the sense that it should cause some part of the system to perform an action, rather than merely notifying of a change happening. See EVENT See PASSIVE-EVENT
-
EXTERNAL CLASS AGENT
A type of consumer of which only one instance should exist on a core. An agent's name defaults to the agent's class name. An agent MATCHES if the class or the class name matches. If an agent is attempted to be added to a core when an agent that matches it by name already exists on the core, a warning of type AGENT-ALREADY-EXISTS-ERROR is signalled. See CONSUMER
-
EXTERNAL CLASS BLOCK-LOOP
Base class for the block loop on a Maiden core. See CORE See DEEDS:EVENT-LOOP
-
EXTERNAL CLASS CLIENT
A type of consumer of which multiple instances can exist on a core. See CONSUMER
-
EXTERNAL CLASS CLIENT-EVENT
-
EXTERNAL CLASS CONSUMER
Superclass for all consumers on a core. Consumers are responsible for issuing and responding to events that happen on a core. They do this by having a number of handler definitions tied to them, which are instantiated into proper handlers for each consumer instance. Consumers can have handlers that are registered directly on the consumer or are instead added to the core the consumer is being added to. The former allows the grouping of handlers and a more granular management of resources, whereas the latter allows you to circumvent potential bottleneck or ordering issues. See the Deeds library for information on how the event-loop and handlers work in detail. Consumers are divided into two classes, ones of which only a single instance should exist on the core, and ones of which many may exist on the core. The former are called AGENTS, and the latter are called CLIENTS. The former usually provide functionality that is reactionary in some sense. The latter usually provide some form of connection to another entity and primarily provide events rather than consuming them. You should not inherit directly from CONSUMER therefore, and rather pick either CLIENT or AGENT, depending on which of the two is more suitable for the kind of consumer you want to write for the system. Consumer classes must inherit from the CONSUMER-CLASS class, which is responsible for ensuring that handler definitions get properly instantiated and managed over consumer instances. In order to easily define consumer classes with the appropriate superclass and metaclass, you can use DEFINE-CONSUMER. In order to add handlers to the consumer, use DEFINE-HANDLER. Each consumer has a LOCK that can be used to synchronise access to the consumer from different parts in the system. Since Deeds, and Maiden by extension, is highly parallel most of the time, locking of resources and access to the consumer from different handlers is vital. The list of handler instances is held in the HANDLERS slot. The list of handlers that are tied directly to cores is held in the CORE-HANDLERS slot. The list of cores the consumer is on is held in the CORES slot. You can start and stop all the handlers on a consumer by the usual Deeds START and STOP functions. After the initialisation of a consumer, the consumer instance is pushed onto the INSTANCES list of its class by way of a weak-pointer. It will also turn all of its effective-handlers into actual handler instances by way of INSTANTIATE-HANDLER and push them onto its HANDLERS list. See NAMED-ENTITY See COMPILED-EVENT-LOOP See HANDLER See CONSUMER-CLASS See AGENT See CLIENT See DEFINE-CONSUMER See DEFINE-HANDLER See HANDLERS See CORE-HANDLERS See CORES See LOCK See START See STOP See INSTANCES See INSTANTIATE-HANDLER
-
EXTERNAL CLASS CONSUMER-ADDED
Event that is issued after a consumer has been added to the core. See CORE-EVENT See CONSUMER
-
EXTERNAL CLASS CONSUMER-CLASS
Metaclass for all consumer objects. It handles the proper instantiation of handler objects when the consumer is added to a core or the handler definitions are updated. See DIRECT-HANDLERS See EFFECTIVE-HANDLERS See INSTANCES See CONSUMER
-
EXTERNAL CLASS CONSUMER-REMOVED
Event that is issued after a consumer has been removed from the core. See CORE-EVENT See CONSUMER
-
EXTERNAL CLASS CORE
The core of an event system in Maiden. The core is responsible for managing events, consumers, and their handlers. It uses two (!) event-loops in the back to handle event delivery. The first loop, called the primary loop is where most handlers live. It is (by default) of type PRIMARY-LOOP and should be fairly speed in delivery, at the cost that adding and removing handlers will be slow. The second loop, called the blocking loop is where temporary handlers that only exist for hopefully a short time live. It is (by default) of type BLOCK-LOOP and is not optimised for fast delivery, but much faster at removing and adding handlers. Thus, whenever you wait for an event for a one-time request, the handler should be added to the block loop. Calling DE/REGISTER-HANDLER on a core will automatically add it to the primary loop. If you want to change the blocking loop you will have to access it directly. When an event is ISSUEd onto the core, it is ISSUEd onto the primary loop and then ISSUEd onto the block loop. The behaviour for when an event is directly HANDLEd by the core is analogous. See PRIMARY-LOOP See BLOCK-LOOP See CONSUMERS See CONSUMER See ADD-CONSUMER See REMOVE-CONSUMER See START See STOP See ISSUE See HANDLE See WITH-AWAITING See WITH-RESPONSE See MAKE-CORE See ADD-TO-CORE
-
EXTERNAL CLASS CORE-EVENT
Superclass for all events relating to a Maiden core. See EVENT
-
EXTERNAL CLASS DATA-ENTITY
Superclass for entities that have a data storage table. See ENTITY See DATA See DATA-VALUE
-
EXTERNAL CLASS ENTITY
Superclass for things that are comparable according to some kind of identity. See ID
-
EXTERNAL CLASS EVENT
The superclass for all events in Maiden. An event is an object that represents a change that occurs in the system. It may also carry relevant information about the change. Events can also be used to signify requests for things to happen in the system. Events need to be ISSUEd onto a core, where they will then be dispatched to HANDLERs that can process it. See EVENT-CLASS See CORE See DEEDS:EVENT See DEFINE-EVENT
-
EXTERNAL CLASS INSTRUCTION-EVENT
Superclass for all instruction events in the system. Instructions are event representations of a change request in the system. They often represent a "virtual" function call. See DEFINE-INSTRUCTION See ACTIVE-EVENT
-
EXTERNAL CLASS NAMED-ENTITY
-
EXTERNAL CLASS PASSIVE-EVENT
Superclass for all passive events in the system. A passive event notifies of a change that happened somewhere in the system. It is passive in the sense that it provides information, rather than explicitly requesting information or explicitly requesting an action. See EVENT See ACTIVE-EVENT
-
EXTERNAL CLASS PRIMARY-LOOP
Base class for the primary loop on a Maiden core. See CORE See DEEDS:COMPILED-EVENT-LOOP
-
EXTERNAL CLASS QUERY-EVENT
Superclass for all query events in the system. Queries are events that represent both a change request and a request for a result to be obtained about the change. They often represent a "full" function call. It is identified so that it and its response event counter- piece can be found. See DEFINE-QUERY See DEEDS:IDENTIFIED-EVENT See INSTRUCTION-EVENT
-
EXTERNAL CLASS RESPONSE-EVENT
Generic response event class. This event is used to deliver the response payload of a query-event. Its IDentity must be the same as that of the query-event that prompted it. See DEEDS:IDENTIFIED-EVENT See DEEDS:PAYLOAD-EVENT See PASSIVE-EVENT
-
EXTERNAL CONDITION AGENT-ALREADY-EXISTS-ERROR
A condition signalled when an agent of the same name already exists on the core. See EXISTING-AGENT See AGENT-CONDITION See CORE-CONDITION
-
EXTERNAL CONDITION AGENT-CONDITION
Superclass for all conditions related to agents. See AGENT See MAIDEN-CONDITION
-
EXTERNAL CONDITION CLIENT-CONDITION
Superclass for all conditions related to clients. See CLIENT See MAIDEN-CONDITION
-
EXTERNAL CONDITION CONSUMER-NAME-DUPLICATED-WARNING
A condition signalled when a consumer is added to a core and has the same name as an already existing consumer. See EXISTING-CONSUMER See NEW-CONSUMER See CORE-CONDITION
-
EXTERNAL CONDITION CORE-CONDITION
Superclass for all conditions related to operations on a core. See CORE See MAIDEN-CONDITION
-
EXTERNAL CONDITION MAIDEN-CONDITION
Superclass for all condition types in the Maiden system.
-
EXTERNAL FUNCTION ADD-TO-CORE
- CORE
- &REST
- CONSUMERS
Easily add consumers to a core. The consumers will be started after having been added to the core. Each consumer in the list of consumers can be: - A symbol denoting the class of consumer to construct - A string or keyword denoting a package that homes a symbol denoting a consumer class. - A list starting with one of the above followed by the initargs for the class instantiation. The instances are all constructed before any of them are added to the core or started, so as to catch errors early.
-
EXTERNAL FUNCTION BROADCAST
- CORES
- EVENT-TYPE
- &REST
- INITARGS
Shorthand function to construct and issue an event onto a set of cores. Unlike DO-ISSUE, this is a function, so the event-type has to be quoted.
-
EXTERNAL FUNCTION ENLIST
- THING
- &REST
- EXTRA-ELEMENTS
If THING is a list, it is returned. Otherwise a new list out of the given elements is constructed.
-
EXTERNAL FUNCTION FIND-CONSUMER-IN-PACKAGE
- PACKAGE
Scans through the symbols in the given package and attempts to find one that denotes a class that is a subclass of CONSUMER. The first such symbol found is returned.
-
EXTERNAL FUNCTION FORMAT-ABSOLUTE-TIME
- TIME
Formats the universal-time as a timestring in the format of YYYY.MM.DD hh:mm:ss
-
EXTERNAL FUNCTION FORMAT-RELATIVE-TIME
- SECONDS
Formats the time in seconds as a human-readable string. Time is split up into seconds, minutes, hours, days, weeks, months, years, decades, centuries, and æons.
-
EXTERNAL FUNCTION FORMAT-TIME
- TIME
- &OPTIONAL
- RELATIVE-TIME-THRESHOLD
Formats the universal-time in a (hopefully) appropriate manner. If the time differs from now by more than the RELATIVE-TIME-THRESHOLD then the time is printed absolutely, otherwise relatively. See FORMAT-RELATIVE-TIME See FORMAT-ABSOLUTE-TIME
-
EXTERNAL FUNCTION GET-UNIX-TIME
Returns the time in seconds since the unix epoch of 1970.
-
EXTERNAL FUNCTION KW
- NAME
Return the keyword corresponding to the given symbol designator.
-
EXTERNAL FUNCTION MAKE-CORE
- &REST
- CONSUMERS
Construct a new core instance and add consumers to it. The resulting core will be started. See CORE See ADD-TO-CORE
-
EXTERNAL FUNCTION MAYBE-INVOKE-DEBUGGER
- CONDITION
- &OPTIONAL
- RESTART
- &REST
- VALUES
Might invoke the debugger with the condition. If *DEBUGGER* is non-NIL, the debugger is invoked with a CONTINUE restart surrounding it to allow giving up on handling the condition. Otherwise, if the RESTART argument is passed, that restart is invoked with the rest of the arguments as values for the restart. See *DEBUGGER*
-
EXTERNAL FUNCTION REMOVE-FUNCTION-HANDLER
- CONSUMER
- NAME
- &OPTIONAL
- EVENT-TYPE
Shorthand function to remove a function-handler definition. This removes both the event class and the handler it defined. See CL:FIND-CLASS See REMOVE-HANDLER
-
EXTERNAL FUNCTION REMOVE-HANDLER
- ABSTRACT-HANDLER
- CLASS-ISH
Removes the handler from the consumer-class. This function simply updates the list of direct-handlers on the class by removing the corresponding abstract-handler. The class-ish can be a CONSUMER-CLASS, a CONSUMER, or a SYMBOL naming a consumer-class. The abstract-handler can be an ABSTRACT-HANDLER, or a SYMBOL denoting the NAME of an abstract-handler. See DIRECT-HANDLERS See ABSTRACT-HANDLER See CONSUMER-CLASS
-
EXTERNAL FUNCTION REMOVE-INSTRUCTION
- CONSUMER
- INSTRUCTION
- &OPTIONAL
- EVENT-TYPE
Shorthand function to remove an instruction definition. This removes both the event class, the handler, and the issue- function it defined. See CL:FMAKUNBOUND See REMOVE-FUNCTION-HANDLER
-
EXTERNAL FUNCTION REMOVE-QUERY
- CONSUMER
- INSTRUCTION
- &OPTIONAL
- EVENT-TYPE
- EVENT-RESPONSE-TYPE
Shorthand function to remove a query definition. This removes both the event classes, the handler, and the issue- function it defined. See REMOVE-FUNCTION-HANDLER See CL:FIND-CLASS See CL:FMAKUNBOUND
-
EXTERNAL FUNCTION STARTS-WITH
- START
- SEQUENCE
- &KEY
- TEST
Returns true if SEQUENCE begins with START.
-
EXTERNAL FUNCTION UNIVERSAL-TO-UNIX
- UNIVERSAL
Convert universal-time to unix-time.
-
EXTERNAL FUNCTION UNIX-TO-UNIVERSAL
- UNIX
Convert unix-time to universal-time.
-
EXTERNAL FUNCTION UNLIST
- THING
- &KEY
- KEY
If THING is not a list, it is returned. Otherwise the element by KEY from the list is returned.
-
EXTERNAL FUNCTION XNOR
- A
- B
If both A and B are either true or false at the same time.
-
EXTERNAL FUNCTION XOR
- A
- B
If either A or B are true, but not both.
-
EXTERNAL GENERIC-FUNCTION ADD-CONSUMER
- CONSUMER
- TARGET
Add the consumer to the core. If the consumer already exists on the core, nothing is done. If a consumer of the same name already exists on the core, a warning of type CONSUMER-NAME-DUPLICATED-WARNING is signalled. If a consumer has been added, an event of type CONSUMER-ADDED is issued onto the core. See CONSUMER-NAME-DUPLICATED-WARNING See CONSUMER-ADDED
-
EXTERNAL GENERIC-FUNCTION ADD-TO-CONSUMER
- OBJECT
Whether the generated handler of this abstract handler should be added to the consumer or the cores of the consumer. See ABSTRACT-HANDLER
-
EXTERNAL GENERIC-FUNCTION (SETF ADD-TO-CONSUMER)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION ADVICE
- OBJECT
Accessor to the advice information on the event or event-class. See EVENT-CLASS See EVENT
-
EXTERNAL GENERIC-FUNCTION (SETF ADVICE)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION AGENT
- CONDITION
Accessor to the agent that this object holds. See AGENT-CONDITION
-
EXTERNAL GENERIC-FUNCTION BLOCK-LOOP
- OBJECT
Accessor to the blocking back loop of the Maiden core. This should govern one-time handlers and response events. See CORE
-
EXTERNAL GENERIC-FUNCTION (SETF BLOCK-LOOP)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION CANCEL
- EVENT
Cancels the event. An event can be cancelled multiple times though the effect does not change. Once an event has been cancelled it can only be handled by handlers that have HANDLE-CANCELLED set to a non-NIL value. See CANCELLED See HANDLE-CANCELLED
-
EXTERNAL GENERIC-FUNCTION CLIENT
- CONDITION
Accessor to the client that this object holds. See CLIENT-CONDITION
-
EXTERNAL GENERIC-FUNCTION CONSUMER
- ID
- TARGET
Retrieve a consumer from the core. If no consumer that matches the ID is found, NIL is returned. See MATCHES
-
EXTERNAL GENERIC-FUNCTION CONSUMERS
- OBJECT
-
EXTERNAL GENERIC-FUNCTION (SETF CONSUMERS)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION CORE
- CONDITION
Accessor to the core that this object holds. See CORE-CONDITION
-
EXTERNAL GENERIC-FUNCTION CORE-HANDLERS
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION (SETF CORE-HANDLERS)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION CORES
- OBJECT
Accessor to the list of cores the consumer is currently registered with. See CONSUMER
-
EXTERNAL GENERIC-FUNCTION (SETF CORES)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION DATA
- OBJECT
Accessor to the data storage container for the data entity. See DATA-ENTITY See DATA-VALUE
-
EXTERNAL GENERIC-FUNCTION (SETF DATA)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION DATA-VALUE
- FIELD
- ENTITY
Accessor for a single data field in the data entity. See DATA See DATA-ENTITY
-
EXTERNAL GENERIC-FUNCTION (SETF DATA-VALUE)
- VALUE
- FIELD
- ENTITY
No documentation provided. -
EXTERNAL GENERIC-FUNCTION DIRECT-HANDLERS
- OBJECT
Accessor to the list of direct handler definitions on the consumer class. This only holds handler definitions that have been defined for this specific class directly. Also note that the handler objects contained in this list are only abstract-handler instances and cannot be directly used as handlers. When this place is set, the consumer-class' inheritance is finalized. See CONSUMER-CLASS See ABSTRACT-HANDLER See MOP:FINALIZE-INHERITANCE
-
EXTERNAL GENERIC-FUNCTION (SETF DIRECT-HANDLERS)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION EFFECTIVE-HANDLERS
- OBJECT
Accessor to the list of effective handler definitions on the consumer class. This holds all handler definitions, including inherited ones. Note that the handler objects contained in this list are only abstract-handler instances and cannot be directly used as handlers. When this place is set, the list of INSTANCES is updated and each existing instance is reinitialised through REINITIALIZE- HANDLERS. See CONSUMER-CLASS See ABSTRACT-HANDLER See INSTANCES See REINITIALIZE-HANDLERS
-
EXTERNAL GENERIC-FUNCTION (SETF EFFECTIVE-HANDLERS)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION EXISTING-AGENT
- CONDITION
Reader for the agent that already exists on the core. See AGENT-ALREADY-EXISTS-ERROR
-
EXTERNAL GENERIC-FUNCTION EXISTING-CONSUMER
- CONDITION
Reader for the consumer that previously already existed on the core. See CONSUMER-NAME-DUPLICATED-WARNING
-
EXTERNAL GENERIC-FUNCTION HANDLERS
- OBJECT
An EQL hash-table of the registered handlers on the event-loop. Be careful when modifying this table, as it is not synchronised. See EVENT-LOOP-LOCK
-
EXTERNAL GENERIC-FUNCTION (SETF HANDLERS)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION ID
- OBJECT
Accessor to the IDentity of an entity. By default this is initialised to a fresh UUIDv4 string. See ENTITY
-
EXTERNAL GENERIC-FUNCTION (SETF ID)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION INSTANCES
- OBJECT
Accessor to the list of weak-pointers to consumer instances. The elements in the list are instances of TG:WEAK-POINTER and may point to instances of the consumer class. This list is necessary to keep track of and properly synchronise the handlers upon redefinition. This list is updated whenever a new CONSUMER instance is created or when EFFECTIVE-HANDLERS of its class is set. See TG:WEAK-POINTER See CONSUMER
-
EXTERNAL GENERIC-FUNCTION (SETF INSTANCES)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION INSTANTIATE-HANDLER
- HANDLER
- CONSUMER
This function creates an actual handler instance from the abstract handler definition. The instantiation proceeds as follows: 1. The options :FILTER, :DELIVERY-FUNCTION, and :MATCH-CONSUMER are extracted from the options list. 2. If :MATCH-CONSUMER is given and is eql to T, then the :FILTER option is extended by surrounding it as follows: (and (eq ,consumer consumer) ..) where ,consumer denotes the consumer instance passed to instantiate-handler. 3. If :MATCH-CONSUMER is given and is not eql to T, then the :FILTER option is extended by surrounding it as follows: (and (eq ,consumer ,match-consumer) ..) where ,consumer is as above and ,match-consumer is the value of the :MATCH-CONSUMER option. 4. MAKE-INSTANCE is called with the TARGET-CLASS of the abstract handler, a :delivery-function initarg that is a function that calls the :DELIVERY-FUNCTION extracted from the option with the consumer and the event, a :filter initarg that is the value of the :FILTER option, and the rest of the OPTIONS of the abstract handler. See ABSTRACT-HANDLER -
EXTERNAL GENERIC-FUNCTION ISSUE
- EVENT
- EVENT-DELIVERY
Issue an event to the delivery so that it is sent out to the handlers. The exact point in time when the issued event is handled and processed is not specified. However, the order in which events are handled must be the same as the order in which they are issued. An event should only ever be issued once. There is no check made to ensure this, but issuing an event multiple times or on multiple deliveries leads to undefined behaviour. There is also no check made to see whether the event delivery is actually started and ready to accept events. If it is not started, the events might pile up or be dropped on the floor. This is, essentially, undefined behaviour.
-
EXTERNAL GENERIC-FUNCTION LOCK
- OBJECT
Accessor to the lock that is used to synchronise access to this object. See CONSUMER
-
EXTERNAL GENERIC-FUNCTION (SETF LOCK)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION MATCHES
- A
- B
Generic comparator operator. This compares in a potentially ambiguous "dwim" sense. Various components in the system add methods to make the matching work as much as expected as possible.
-
EXTERNAL GENERIC-FUNCTION NAME
- OBJECT
Aecessor to the name of the entity. See NAMED-ENTITY
-
EXTERNAL GENERIC-FUNCTION (SETF NAME)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION NEW-CONSUMER
- CONDITION
Reader for the new consumer that is being added to the core. See CONSUMER-NAME-DUPLICATED-WARNING
-
EXTERNAL GENERIC-FUNCTION OPTIONS
- OBJECT
Accessor to the list of initargs that the handler should receive upon instantiation. See ABSTRACT-HANDLER
-
EXTERNAL GENERIC-FUNCTION (SETF OPTIONS)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION PRIMARY-LOOP
- OBJECT
Accessor to the primary loop of the Maiden core. This should take care of the bulk of handlers and events. See CORE
-
EXTERNAL GENERIC-FUNCTION (SETF PRIMARY-LOOP)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION REMOVE-CONSUMER
- CONSUMER
- TARGET
Remove the consumer from the core. If the consumer doesn't exist on the core, nothing is done. Otherwise the consumer is removed from the core's list. If a consumer has been removed, an event of type CONSUMER- REMOVED is issued onto the core. See CONSUMER-REMOVED
-
EXTERNAL GENERIC-FUNCTION RESPOND
- EVENT
- &KEY
- PAYLOAD
- CLASS
- &ALLOW-OTHER-KEYS
Respond to the event in an appropriate way. The response event will be issued on to the same core that the event being responded to was issued to. If the event does not have a specific response event already (through a specialised method on RESPOND), then you may specify the class to use with the :CLASS initarg.
-
EXTERNAL GENERIC-FUNCTION RESPONSE-EVENT
- OBJECT
Accessor to the response event the handler captures.
-
EXTERNAL GENERIC-FUNCTION (SETF RESPONSE-EVENT)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL GENERIC-FUNCTION RUNNING
- STUFF
Returns T if the event delivery is able to process events.
-
EXTERNAL GENERIC-FUNCTION START
- EVENT-DELIVERY
Start the event delivery and make it ready to accept and deliver events. If the delivery is already running this does nothing.
-
EXTERNAL GENERIC-FUNCTION STOP
- EVENT-DELIVERY
Stop the event delivery to prevent it from accepting and delivering events. If there are events that the handler has yet to process, there is no guarantee that they will be processed before the event delivery is stopped. If the delivery is already stopped this does nothing.
-
EXTERNAL GENERIC-FUNCTION TARGET-CLASS
- OBJECT
Accessor to the target class that the actual handler should be of when the abstract-handler is instantiated. Defaults to DEEDS:QUEUED-HANDLER See ABSTRACT-HANDLER See DEEDS:QUEUED-HANDLER
-
EXTERNAL GENERIC-FUNCTION (SETF TARGET-CLASS)
- NEW-VALUE
- OBJECT
No documentation provided. -
EXTERNAL MACRO DEFINE-CONSUMER
- NAME
- DIRECT-SUPERCLASSES
- DIRECT-SLOTS
- &REST
- OPTIONS
Shorthand to define a consumer class. This is like CL:DEFCLASS, with the appropriate superclass and metaclass injected for you. It also makes sure that the class definition is available during compile-time as well. See CONSUMER See CONSUMER-CLASS
-
EXTERNAL MACRO DEFINE-EVENT
- NAME
- DIRECT-SUPERCLASSES
- DIRECT-SLOTS
- &REST
- OPTIONS
Shorthand macro to define an event class. This takes care of potentially injecting the EVENT superclass and setting the necessary EVENT-CLASS metaclass. Otherwise it is identical to CL:DEFCLASS. See CL:DEFCLASS See EVENT See EVENT-CLASS
-
EXTERNAL MACRO DEFINE-FUNCTION-HANDLER
- CONSUMER
- NAME
- &OPTIONAL
- EVENT-TYPE
- ARGS
- &BODY
- BODY
Shorthand macro to define an event an a corresponding handler in one go. Special body options are extracted to provide further control over the definition of the event: :SUPERCLASSES The superclass list to use. :EXTRA-SLOTS A list of extra slot definitions. :CLASS-OPTIONS A list of extra class options. :DOCUMENTATION The docstring to use for the class. :ADVICE The advice value to use for the event. Note that these options will NOT be passed on to the DEFINE-HANDLER form. The ARGS are used both for the arguments to DEFINE-HANDLER and as slot definitions by way of SLOT-ARGS->SLOTS. See SLOT-ARGS->SLOTS See DEFINE-EVENT See DEFINE-HANDLER See REMOVE-FUNCTION-HANDLER
-
EXTERNAL MACRO DEFINE-HANDLER
- CONSUMER
- NAME
- EVENT-TYPE
- ARGS
- &BODY
- BODY
Defines a new handler on the consumer class. CONSUMER must be the class-name of the consumer to define on. NAME must be a symbol denoting the name of the handler definition. Note that this name will not be carried over to actual handler instances, as they would otherwise clash on multiple consumer instances on the same core. EVENT-TYPE must be a base class for all events that the handler will receive. ARGS must be a list of arguments, of which the first two will be bound to the consumer instance and the event respectively. The rest of the arguments denote fuzzy slot bindings of the event. BODY a number of extra handler definition options as a plist followed directly by a number of forms to evaluate upon receiving an event. The body options are evaluated and passed as class initargs to the resulting handler instance once one is constructed. Note that as such the values will be shared across all instances of the handler defined here. Also note that there are three options which are exempt from this and play special roles: :DELIVERY-FUNCTION This option is already provided by default. Supplying it manually will mean that the body forms of the DEFINE-HANDLER will be ignored. :MATCH-CONSUMER Should be a slot name of the event that needs to match the consumer for the event to be handled. You'll want to use this option for handlers of clients, in order to ensure that the handler from the client instance that matches the client the event is intended for is called. :ADD-TO-CONSUMER By default T; decides whether the resulting handler instances should be added to the consumer directly, or to the cores the consumer is added to. In effect this constructs an appropriate ABSTRACT-HANDLER instance and calls UPDATE-HANDLER with it on the consumer class. See DEEDS:WITH-FUZZY-SLOT-BINDINGS See DEEDS:WITH-ORIGIN See ABSTRACT-HANDLER See UPDATE-HANDLER See REMOVE-HANDLER -
EXTERNAL MACRO DEFINE-INSTRUCTION
- CONSUMER
- INSTRUCTION
- &OPTIONAL
- EVENT-TYPE
- ARGS
- &BODY
- BODY
Shorthand macro to define an instruction-like event. This is essentially the same as DEFINE-FUNCTION-HANDLER with the following additions: - INSTRUCTION-EVENT is always injected as a superclass. - A function of the same name as the instruction is generated that creates the appropriate event and sends it off to a core. This thus allows you to simulate a standard function interface for code that runs over the event-loop. Note that the generated function will not wait for a response to the event and immediately returns. The returned value is the generated event instance. See DEFINE-FUNCTION-HANDLER See BROADCAST See REMOVE-INSTRUCTION
-
EXTERNAL MACRO DEFINE-QUERY
- CONSUMER
- INSTRUCTION
- &OPTIONAL
- EVENT-TYPE
- EVENT-RESPONSE-TYPE
- ARGS
- &BODY
- BODY
Shorthand macro to define a query-like event. This is similar to DEFINE-INSTRUCTION, with the exception that possibly two events (one for issue and one for response) are generated, and that the issue function will await a response and return with the intended return value, thus simulating a complete function API over the event system. If no explicit EVENT-RESPONSE-TYPE is specified, a generic response event is used instead. See RESPOND. See RESPOND See REMOVE-QUERY
-
EXTERNAL MACRO DO-ISSUE
- CORE
- EVENT-TYPE
- &REST
- INITARGS
Shorthand macro to construct and issue an event onto a core. The event-type should not be quoted. See DEEDS:DO-ISSUE
-
EXTERNAL MACRO NAMED-LAMBDA
- NAME
- ARGS
- &BODY
- BODY
Attempt to construct a lambda with a name. Note that standard name clashing rules apply and naming the lambda after a CL function will likely fail if the implementation supports package locks.
-
EXTERNAL MACRO UPDATE-LIST
- THING
- LIST
- &KEY
- KEY
- TEST
Macro to update the list with a new item. The item is added to the list if it is not yet contained and updated in-place otherwise. See MAKE-UPDATED-LIST
-
EXTERNAL MACRO WITH-AWAITING
- CORE
- EVENT-TYPE
- ARGS
- SETUP-FORM
- &BODY
- BODY
Waits for a response event to arrive on the core before evaluating the body. This is useful to write event-driven, reactionary code. The temporary handler to catch the code is added to the core's back loop. Note that CORE can be one of - CORE The temporary handler is attached to the core's block-loop. - CONSUMER The first core on the client's list of cores is used as above. - DEEDS:EVENT-LOOP The temporary handler is directly attached to it. You can also specify a maximum waiting timeout with the :TIMEOUT body options. The timeout is in seconds. Similar to DEFINE-HANDLER, you can also specify a :FILTER test body option. See DEEDS:WITH-AWAITING -
EXTERNAL MACRO WITH-DEFAULT-ENCODING
- &OPTIONAL
- ENCODING
- &BODY
- BODY
Evaluate BODY in an environment where the default external format is set to the given encoding. Only works on: - SBCL - CCL
-
EXTERNAL MACRO WITH-RETRY-RESTART
- RESTART
- FORMAT-STRING
- &REST
- FORMAT-ARGS
- &BODY
- BODY
Evaluates body around which a restart is established that allows retrying the evaluation of the body. Similar to CL:WITH-SIMPLE-RESTART.
-
MAIDEN-USER
- ORG.SHIRAKUMO.MAIDEN.USER
No documentation provided.