package ircregistry

import "github.com/hlandau/ircproto/egobot/ircregistry"

Package ircregistry provides a service discovery and registration facility for IRC message handling modules.

Each handler exposes zero or more services. Each service has a name. Services are consumed by both other handlers, and non-handler code, by looking up a service by name to get a Handler interface, and then performing an interface upgrade on that Handler interface.

Multiple handlers can be registered as providing the given service. In this case, the first (highest priority; lowest numerical priority value) handler implementing the service can, if it wishes, chain calls to the methods of that service to the next service in the list, and so on.

Index ¶

• Variables
• func CurNickName(port Port) string
• func InjectDisconnected(reg *Registry) error
• func InjectMsgRx(reg *Registry, env *Envelope) error
• func InjectNegotiationComplete(reg *Registry, res *ircneg.Result) error
• func IsOnChannel(port Port, channelName string) bool
• func NextDisconnected(port Port, f func() error) error
• func NextMsgRx(port Port, env *Envelope, f func() error) error
• func NextMsgTx(port Port, env *Envelope, f func() error) error
• func NextNegotiationComplete(port Port, res *ircneg.Result, f func() error) error
• func TxCmd(port Port, cmdName string, cmdArgs ...string) error
• func TxCommaSeparated(port Port, cmd string, items []string) error
• func TxMsg(port Port, msg *ircparse.Msg) error
• func TxNotice(port Port, tgt, body string) error
• func TxPrivmsg(port Port, tgt, body string) error
• type DisconnectedService
• type Envelope
• type GetNickService
• type Handler
• type HandlerInfo
• type NegotiationCompleteService
• type OnChannelService
• type Port
• type RXService
• type Registry
• func New() (*Registry, error)
• func (r *Registry) Destroy()
• func (r *Registry) GetFirstHandler(serviceName string) Handler
• func (r *Registry) InstantiateHandler(hi *HandlerInfo, args interface{}) error
• type ServiceInfo
• type TXService

Variables ¶

var _, Log = xlog.New("ircregistry")

Functions ¶

func CurNickName ¶

func CurNickName(port Port) string

Returns the current nickname using the "getnick" service. If the service is unavailable or the nickname is unknown, returns "".

func InjectDisconnected ¶

func InjectDisconnected(reg *Registry) error

Injects an OnDisconnected event into a registry's registered "disconnected" service chain.

func InjectMsgRx ¶

func InjectMsgRx(reg *Registry, env *Envelope) error

Injects an OnMsgRx event into a registry's registered "rx" service chain.

func InjectNegotiationComplete ¶

func InjectNegotiationComplete(reg *Registry, res *ircneg.Result) error

Injects an OnNegotiationComplete event into a registry's registered "negotiation-complete" service chain.

func IsOnChannel ¶

func IsOnChannel(port Port, channelName string) bool

Determines whether the bot is currently joined to a given channel via the "on-channel" service. Returns false if no implementation of the service is found.

func NextDisconnected ¶

func NextDisconnected(port Port, f func() error) error

Helper function for chaining "disconnected" service handlers. A "disconnected" service implementation should immediately call (only) this function in its OnDisconnected implementation. f() will immediately be called which should implement the body of the processing; this is expected to be a closure.

After f() returns, whether or not it returns an error, the next handler in the chain is called using the passed port.

func NextMsgRx ¶

func NextMsgRx(port Port, env *Envelope, f func() error) error

Helper function for chaining "rx" service handers. An "rx" service implementation should immediately call (only) this function in its OnMsgRx implementation. f() will immediately be called which should implement the body of the processing; this is expected to be a closure which captures env.

After f() returns, whether or not it returns an error, the next handler in the chain is called using the passed port.

func NextMsgTx ¶

func NextMsgTx(port Port, env *Envelope, f func() error) error

Helper function for chaining "tx" service handlers. A "tx" service implementation should immediately call (only) this function in its OnMsgTx implementation. f() will immediately be called which should implement the body of the processing; this is expected to be a closure which captures env.

After f() returns, whether or not it returns an error, the next handler in the chain is called using the passed port.

func NextNegotiationComplete ¶

func NextNegotiationComplete(port Port, res *ircneg.Result, f func() error) error

Helper function for chaining "negotiation-complete" service handlers. A "negotiation-complete" service implementation should immediately call (only) this function in its OnNegotiationComplete implementation. f() will immediately be called which should implement the body of the processing; this is expected to be a closure which captures env.

After f() returns, whether or not it returns an error, the next handler in the chain is called using the passed port.

func TxCmd ¶

func TxCmd(port Port, cmdName string, cmdArgs ...string) error

Transmit a new command. This function is intended for use primarily by handlers.

func TxCommaSeparated ¶

func TxCommaSeparated(port Port, cmd string, items []string) error

Transmit the given items as a comma separated list in a command with the given name. If there are too many items to fit on one command, multiple commands are sent.

func TxMsg ¶

func TxMsg(port Port, msg *ircparse.Msg) error

Transmit a new message in a fresh envelope. This function is intended for use primarily by handlers.

func TxNotice ¶

func TxNotice(port Port, tgt, body string) error

Transmit a new NOTICE. This function is intended for use primarily by handlers.

func TxPrivmsg ¶

func TxPrivmsg(port Port, tgt, body string) error

Transmit a new PRIVMSG. This function is intended for use primarily by handlers.

Types ¶

type DisconnectedService ¶

type DisconnectedService interface {
	OnDisconnected() error
}

The "disconnected" service is used to notify handlers that the connection has been disconnected, and that further transmissions will not be possible until a negotiation complete event. Each handler should pass the message to the next "disconnected" service handler in a chain, unless it wishes to eat the message.

type Envelope ¶

type Envelope struct {
	// The received message.
	Msg *ircparse.Msg

	Incoming        bool // This is an incoming (RX) message, else TX.
	StopHandling    bool // Don't pass this to further handlers (but do to the ultimate client (RX) or server (TX).)
	InhibitDelivery bool // If set, don't pass this to the ultimate client (RX) or server (TX).

	// Escape hatch.
	Values map[interface{}]interface{}
}

Wrapper for an ircproto.Message used to pass both the IRC message, and information about the message, from handler to handler.

type GetNickService ¶

type GetNickService interface {
	CurNickName() string
}

The "getnick" service is used by handlers to ask other handlers if they know what the client's current nickname is.

type Handler ¶

type Handler interface {
	Destroy() error

	// Called immediately after handler instantiation to get a list of services
	// implemented by the handler. The handler is registered as providing the
	// given service, and each service is registered according to the priority
	// specified, which determines its order in the list of handlers providing
	// that service.
	ListServices() []*ServiceInfo
}

All handlers must implement this interface.

type HandlerInfo ¶

type HandlerInfo struct {
	// A short name of the handler. Should be lowercase without spaces.
	Name string

	// A single-line description of the handler.
	Description string

	// Function used to instantiate the handler. It is passed a handler-specific
	// port interface which the handler should note.
	NewFunc func(port Port) (Handler, error)
}

Information which can be used to instantiate a handler. A *HandlerInfo global should be provided by each handler implementation to allow it to be instantiated.

type NegotiationCompleteService ¶

type NegotiationCompleteService interface {
	OnNegotiationComplete(res *ircneg.Result) error
}

The "negotiation-complete" service is used to notify handlers that the negotiation sequence of a new IRC connection has been completed. This can be used by handlers to determine that the current IRC connection has changed, and as a cue to take actions that should be taken at the start of a new connection. Each handler should pass the message to the next "negotiation-complete" service handler in a chain, unless it wishes to eat the message.

type OnChannelService ¶

type OnChannelService interface {
	IsOnChannel(channelName string) bool
}

The "on-channel" service is used by handlers to ask other handlers if they know that the bot is currently joined to a given channel.

type Port ¶

type Port interface {
	// Returns the value of args passed to InstantiateHandler.
	Args() interface{}

	// If the handler whose port this is provides the given service, returns the
	// handler immediately following it in the list for the given service.
	// Otherwise, it returns the first handler for the given service. If no
	// handler is registered for the service or this handler is the last handler
	// in the list for the given service, returns nil.
	GetNextHandler(service string) Handler
}

When a handler is instantiated, it is passed a Port, which provides a handler-specific interface to the registry. It should not be used by handlers other than the handler which received it.

type RXService ¶

type RXService interface {
	OnMsgRx(env *Envelope) error
}

The "rx" service is used to notify handlers of received IRC messages. Each handler should pass the message to the next "rx" service handler in a chain, unless it wishes to eat the message.

RX events are initially injected into the "rx" handler chain by non-handler code which calls GetFirstHandler("rx") on a registry.

type Registry ¶

type Registry struct {
	// contains filtered or unexported fields
}

A registry keeps a register of registered handlers.

func New ¶

func New() (*Registry, error)

Instantiates a new registry.

func (*Registry) Destroy ¶

func (r *Registry) Destroy()

Destroy the registry and all handlers attached to it.

func (*Registry) GetFirstHandler ¶

func (r *Registry) GetFirstHandler(serviceName string) Handler

Gets the first handler for a given service. Returns nil if no handler is registered for that service.

func (*Registry) InstantiateHandler ¶

func (r *Registry) InstantiateHandler(hi *HandlerInfo, args interface{}) error

Instantiates a handler using the given HandlerInfo. The args argument is optional and made available via the Args() method on the port passed to the newly instantiated handler.

type ServiceInfo ¶

type ServiceInfo struct {
	// The name of the service implemented.
	Name string

	// Service priority. Zero is a sensible default. This determines the ordering
	// of the handler in the list of handlers implementing this service.
	Priority int
}

Information about a service implemented by a handler.

type TXService ¶

type TXService interface {
	OnMsgTx(env *Envelope) error
}

The "tx" service is used to notify handlers of transmitted IRC messages. Each handler should pass the message to the next "tx" service handler in a chain, unless it wishes to eat the message. The final "tx" handler is generally configured to transmit the message to the network; this handler has a very high priority for the "tx" service.

Source Files ¶

ircregistry.go txrx.go