maiden-client-entities

0.0.0

Support for the concepts of users and channels.

About

This is a Maiden subsystem to provide commonly used objects and methods that deal with entities usually found on clients that interact with remote systems-- particularly chat systems. If you are implementing a client, you will want to subclass the various classes provided by this system and flesh them out with the required functionality. If you are implementing an agent that should stay agnostic to the client it interacts with, you should handle the events and objects presented by this system.

How To

There's no particular "how to" for this. Read through the symbol index to see what's contained in here. What you should use and how should be fairly self-explanatory after that.

Copyright

maiden-client-entities is licensed under the Artistic license. © Nicolas Hafner <shinmera@tymoon.eu> . This library can be obtained on https://github.com/Shinmera/maiden.

Package Index

MAIDEN-CLIENT-ENTITIES (ORG.SHIRAKUMO.MAIDEN.MODULES.CLIENT-ENTITIES)

class

`CHANNEL`

Object representing a channel on a remote system somewhere.

Channels are virtual "rooms" over which one or more users may
communicate with each other.

Channels have a name and a number of users that inhabit it.
Additional properties are not guaranteed, but may be provided by a
client.

See CLIENT-ENTITY
See USERS

class

`CHANNEL-CLIENT`

Superclass for clients that provide the concept of a channel over which users can communicate with each other in a group.

See FIND-CHANNEL
See CHANNELS
See ENSURE-CHANNEL
See CHANNEL

class

`CHANNEL-CONTAINER`

Mixin for objects that contain channels in some way.

The standard implementation this offers uses an equalp hash-table
for the channel storage, mapping channel names to channel objects.

See CHANNEL
See CHANNEL-MAP
See CHANNELS
See FIND-CHANNEL
See REMOVE-CHANNEL
See ENSURE-CHANNEL

class

`CHANNEL-EVENT`

Superclass for all events relating to a channel.

See CHANNEL
See CLIENT-EVENT

class

`CLIENT`

A type of consumer of which multiple instances can exist on a core.

See CONSUMER

class

`CLIENT-ENTITY`

Superclass for all entities that are tied to a client instance somehow.

See NAMED-ENTITY
See CLIENT

class

`MESSAGE-EVENT`

Event issued when a textual message of some kind is sent.

Note that not all message-events are channel-events.

See MESSAGE
See USER-EVENT

class

`SIMPLE-CHANNEL`

Superclass for simple channels.

Channels can contain a number of users.

See CHANNEL
See USER-CONTAINER

class

`SIMPLE-USER`

Superclass for simple users.

Users can be in a number of channels.

See USER
See CHANNEL-CONTAINER

class

`SIMPLE-USER-CHANNEL-CLIENT`

Superclass for a client that has both users and channels.

This class already handles the association/storage of user and
channel objects. User ENSURE-USER/CHANNEL to register users and
channels.

If you need to subclass USER or CHANNEL --which you probably
should anyway-- you should subclass SIMPLE-USER and SIMPLE-CHANNEL
instead, and override ENSURE-USER and ENSURE-CHANNEL to create
instances of the appropriate classes instead.

You will have to make sure that, when a user enters a channel, the
channel is registered to the user via FIND-CHANNEL on the user,
and the user is registered to the channel via FIND-USER on the
channel. The same goes when a user leaves a channel. However, you
do not need to do anything should a channel or a user be removed
from the client altogether, as in that case this generic system
can figure out what to do on its own and ensure consistency.

See USER-CLIENT
See CHANNEL-CLIENT
See USER-CONTAINER
See CHANNEL-CONTAINER
See SIMPLE-USER
See SIMPLE-CHANNEL

class

`USER`

Object representing a user on a remote system somewhere.

Users have a name and may be authenticated. Additional properties
are not guaranteed, but may be provided by a client.

See CLIENT-ENTITY
See AUTHENTICATE
See AUTHENTICATED-P
See USERNAME

class

`USER-ADDED`

Event issued when a user is now tracked by the client.

See USER-EVENT

class

`USER-CLIENT`

Superclass for clients that communicate with users of some form.

See FIND-USER
See USERS
See ENSURE-USER
See AUTHENTICATE
See USER
See USERNAME

class

`USER-CONTAINER`

Mixin for objects that can contain users in some way.

The standard implementation this offers uses an equalp hash-table
for the user storage, mapping user names to user objects.

See USER
See USER-MAP
See USERS
See FIND-USER
See REMOVE-USER
See ENSURE-USER

class

`USER-ENTERED`

Event issued when a user entered a channel.

See USER-EVENT
See CHANNEL-EVENT

class

`USER-EVENT`

Superclass for all events relating to a user.

See CLIENT-EVENT
See USER

class

`USER-LEFT`

Event issued when a user left a channel.

See USER-EVENT
See CHANNEL-EVENT

class

`USER-NAME-CHANGED`

Event issued when the name of a user has changed for some reason.

If you track users by name rather than by their object, you should
use this to update your records. The old name is kept in the OLD-
NAME slot.

See USER-EVENT
See OLD-NAME

class

`USER-REMOVED`

Event issued when a user can no longer be tracked by the client.

This does not necessarily mean that the user has left the remote
server.

See USER-EVENT

accessor (

`CHANNEL`

OBJECT)

Accessor to the channel that the game is being played on.

See MAIDEN-CLIENT-ENTITIES:CHANNEL
See GAME

accessor (

`CHANNEL-MAP`

OBJECT)

Accessor to the hash-table that maps channel names to channel objects on the channel-container

See CHANNEL-CONTAINER

accessor (

`CLIENT`

CONDITION)

Accessor to the client that this object holds.

See CLIENT-CONDITION

accessor (

`FIND-CHANNEL`

NAME CLIENT)

Attempt to find the channel object of the given name on the client.

Note that if the channel cannot be found, it does not necessarily
mean that the channel does not exist at all, or does not exist on
the server at this time. You can only find channels that the
system has already learned about in some way.

For some clients this may also be an accessor that allows you to
register channel objects with the client.

See CHANNEL
See CHANNEL-CLIENT

accessor (

`FIND-USER`

NAME CLIENT)

Attempt to find the user object of the given name on the client.

Note that if the user cannot be found, it does not necessarily
mean that the user does not exist at all, or does not exist on
the server at this time. You can only find users that the system
has already learned about in some way.

For some clients this may also be an accessor that allows you to
register user objects with the client.

See USER
See USER-CLIENT

accessor (

`MESSAGE`

OBJECT)

Accessor to the message string carried by the event.

See MESSAGE-EVENT

accessor (

`USER`

OBJECT)

Reader for the user object the event relates to.

See USER-EVENT

accessor (

`USER-MAP`

OBJECT)

Accessor to the hash-table that maps user names to user objects on the user-container.

See USER-CONTAINER

accessor (

`USERNAME`

USER)

Accessor to the entity's name on the client network.

This may or may not be distinct from the entity's NAME.
Especially clients may often want to keep a separate NAME
and USERNAME, as the name should stay the same on the local
core, but the username may possibly change or be different
depending on the network.

See USER
See USER-CLIENT

generic (

`AUTHENTICATE`

USER CLIENT)

Return whether it is known that the given user object is really that particular user, or might also be someone else.

In other words, this returns whether the identity of the user can
be trusted or not. Note that the check is not cached, and may thus
take some time or be costly in some fashion, as outside
communication might be necessary to confirm the identity.

See AUTHENTICATED-P

generic (

`AUTHENTICATED-P`

USER)

Returns whether the user is authenticated or not.

This value is cached. The first time this is called on a user, it
may take a while.

See USER
See AUTHENTICATE

generic (

`CHANNELS`

USER)

Return a list of all known channel objects on the client.

See CHANNEL
See CHANNEL-CLIENT

generic (

`ENSURE-CHANNEL`

CHANNEL CLIENT)

Either return the existing channel of that name, or create it new. Either way, ensure it exists.

See CHANNEL
See FIND-CHANNEL
See CHANNEL-CLIENT

generic (

`ENSURE-USER`

USER CLIENT)

Either return the existing user of that name, or create it new. Either way, ensure it exists.

See USER
See FIND-USER
See USER-CLIENT

generic (

`REMOVE-CHANNEL`

NAME CONTAINER)

Remove the given channel from the channel-container.

See CHANNEL
See CHANNEL-CONTAINER

generic (

`REMOVE-USER`

NAME CONTAINER)

Remove the given user from the user-container.

See USER
See USER-CONTAINER

generic (
REPLY
EVENT FORMAT-STRING &REST FORMAT-ARGS)
```
 
```

generic (

`USERS`

CHANNEL)

Return a list of all known user objects on the client.

See USER
See USER-CLIENT