hugot

package module
v0.0.0-...-ea28c76 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 4, 2016 License: GPL-3.0 Imports: 16 Imported by: 0

README

Hugot GoDoc

Hugot is a package for building chat bots. It is inspired by Go's http stdlib package.

Please see the GoDoc for examples and usage.

Documentation

Overview

Package hugot provides a simple interface for building extensible chat bots in an idiomatic go style. It is heavily influenced by net/http, and uses an internal message format that is compatible with Slack messages.

Adapters

Adapters are used to integrate with external chat systems. Currently the following adapters exist: 

slack - github.com/tcolgate/hugot/adapters/slack - for https://slack.com/
irc - github.com/tcolgate/hugot/adapters/irc - simple irc adapter
shell - github.com/tcolgate/hugot/adapters/shell - simple readline based adapter

Examples of using these adapters can be found in github.com/tcolgate/hugot/cmd

Handlers

Handlers process messages. There are a several built in handler types:

RawHandlers will execute for every message sent to them.

HearsHandlers will execute for any message which matches a given regular expression. They are passed all string sub-matches from any capture groups.

Command Handlers act on any direct message. Message are attempted to be processed as a command line. Quoted text is handle as a single argument. The passed message can be used as a flag.FlagSet

Background handlers, are started when the bot is started. They do not receive messages but can send them. They are intended to implement long lived background tasks that react to external inputs.

HTTP handlers can be used to implement web hooks by adding the bot to a http.ServeMux. A URL is build from the name of the handler.

Mux

The Mux, and CommandMux will multiplex message across a set of handlers. In addition, a top level "help" Command handler is added to provide help on usage of the various handlers added to it.

WARNING: the interface is new and is subject to change. In particular, the Comman/CommandMux code is overly complex and the interface may be simplified to make this easier to use. The HTTP support is currently unused and the interface may change depending on experience of actually using it.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrSkipHears is used by Command handlers to indicate they have
	// handled a mesage and that any following Hear handlers should be
	// skipped.
	ErrSkipHears = errors.New("skip hear messages")

	// ErrNextCommand is returned if the command wishes the message
	// to be passed to one of the sub-ommands of a CommandMux.
	ErrNextCommand = errors.New("pass this to the next command")

	// ErrUnknownCommand is returned by a command mux if the command did
	// not match any of it's registered handlers.
	ErrUnknownCommand = errors.New("unknown command")

	// ErrBadCLI implies that we could not process this message as a
	// command line. E.g. due to potentially mismatched quoting or bad
	// escaping.
	ErrBadCLI = errors.New("coul not process as command line")
)

Functions

func Add 

func Add(h Handler) error

Add adds the provided handler to the DefaultMux

func AddBackgroundHandler 

func AddBackgroundHandler(h BackgroundHandler) error

AddBackgroundHandler adds the provided handler to the DefaultMux

func AddHTTPHandler 

func AddHTTPHandler(h HTTPHandler) *url.URL

AddHTTPHandler adds the provided handler to the DefaultMux

func AddHearsHandler 

func AddHearsHandler(h HearsHandler) error

AddHearsHandler adds the provided handler to the DefaultMux

func AddRawHandler 

func AddRawHandler(h RawHandler) error

AddRawHandler adds the provided handler to the DefaultMux

func ListenAndServe 

func ListenAndServe(ctx context.Context, a Adapter, h Handler)

ListenAndServe runs the handler h, passing all messages to/from the provided adapter. The context may be used to gracefully shut down the server.

func RunBackgroundHandler 

func RunBackgroundHandler(ctx context.Context, h BackgroundHandler, w ResponseWriter)

RunBackgroundHandler starts the provided BackgroundHandler in a new go routine. WARNING: probably not to be used directly and may be made private in the future.

func RunCommandHandler 

func RunCommandHandler(ctx context.Context, h CommandHandler, w ResponseWriter, m *Message) error

RunCommandHandler initializes the message m as a command message and passed it to the given handler.WARNING: probably not to be used directly and may be made private in the future.

func RunHandlers 

func RunHandlers(ctx context.Context, h Handler, a Adapter)

RunHandlers process messages from adapter a, and passes them to the provided handler h. ctx can be used to stop the processesing and inform any running handlers. WARNING: probably not to be used directly and may be made private in the future.

func RunHearsHandler 

func RunHearsHandler(ctx context.Context, h HearsHandler, w ResponseWriter, m *Message) bool

RunHearsHandler will match the go routine. WARNING: probably not to be used directly and may be made private in the future.

func RunRawHandler 

func RunRawHandler(ctx context.Context, h RawHandler, w ResponseWriter, m *Message) bool

RunRawHandler passing message m to the provided handler. go routine. WARNING: probably not to be used directly and may be made private in the future.

Types

type Adapter 

type Adapter interface {
	Sender
	Receiver
}

Adapter can be used to communicate with an external chat system such as slack or IRC.

type Attachment 

type Attachment slack.Attachment

Attachment represents a rich message attachment and is directly modeled on the Slack attachments API

type BackgroundFunc 

type BackgroundFunc func(ctx context.Context, w ResponseWriter)

BackgroundFunc describes the calling convention for Background handlers

type BackgroundHandler 

type BackgroundHandler interface {
	Handler
	StartBackground(ctx context.Context, w ResponseWriter)
}

BackgroundHandler gets run when the bot starts listening. They are intended for publishing messages that are not in response to any specific incoming message.

func NewBackgroundHandler 

func NewBackgroundHandler(name, desc string, f BackgroundFunc) BackgroundHandler

NewBackgroundHandler wraps f up as a BackgroundHandler with the name and description provided.

type Channel 

type Channel string

Channel represents discussion channel, such as an IRC channel or Slack channel. The Adapter is responsible for translating between a human name for the channel, and any internal representation

type CommandFunc 

type CommandFunc func(ctx context.Context, w ResponseWriter, m *Message) error

CommandFunc describes the calling convention for CommandHandler

type CommandHandler 

type CommandHandler interface {
	Handler
	Command(ctx context.Context, w ResponseWriter, m *Message) error
}

CommandHandler handlers are used to implement CLI style commands. Before the Command method is called, the in the incoming message m will have the Text of the message parsed into invidual strings, accouting for quoting. m.Args(0) will be the name of the command as the handler was called, as per os.Args(). Command should add any requires falgs to m and then call m.Parse() ErrNextCommand can be returned to inform the command mux to hand the resulting Args to any known sub CommandHandler.

func NewCommandHandler 

func NewCommandHandler(name, desc string, f CommandFunc) CommandHandler

NewCommandHandler wraps the given function f as a CommandHandler with the provided name and description.

type CommandMux 

type CommandMux struct {
	CommandHandler
	// contains filtered or unexported fields
}

CommandMux is a handler that support "nested" command line commands.

func AddCommandHandler 

func AddCommandHandler(h CommandHandler) *CommandMux

AddCommandHandler adds the provided handler to the DefaultMux

func NewCommandMux 

func NewCommandMux(base CommandHandler) *CommandMux

NewCommandMux creates a new CommandMux. The provided base command handler will be called first. This can process any initial flags if desired. If the base command handler returns ErrNextCommand, any command handlers that have been added to this mux will then be called with the message Args having been appropriately adjusted

func (*CommandMux) AddCommandHandler 

func (cx *CommandMux) AddCommandHandler(c CommandHandler) *CommandMux

AddCommandHandler adds a sub-command to an existing CommandMux

func (*CommandMux) Command 

func (cx *CommandMux) Command(ctx context.Context, w ResponseWriter, m *Message) error

Command implements the Command handler for a CommandMux

func (*CommandMux) SubCommands 

func (cx *CommandMux) SubCommands() map[string]*CommandMux

SubCommands returns any known subcommands of this command mux

type Describer 

type Describer interface {
	Describe() (string, string)
}

Describer returns the name and description of a handler. This is used to identify the handler within Command and HTTP Muxs, and to provide a descriptive name for the handler in help text.

type ErrUsage 

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

ErrUsage indicates that Command handler was used incorrectly. The string returned is a usage message generated by a call to -help for this command

func (ErrUsage) Error 

func (e ErrUsage) Error() string

Error implements the Error interface for an ErrUsage.

type HTTPHandler 

type HTTPHandler interface {
	Handler
	http.Handler
}

HTTPHandler handlers are used to add webhooks to your handlers.

func NewHTTPHandler 

func NewHTTPHandler(name, desc string, h http.Handler) HTTPHandler

NewHTTPHandler creates a new HTTPHandler with the http.Handler h, and the provided name and description

func NewHTTPHandlerFunc 

func NewHTTPHandlerFunc(name, desc string, h http.HandlerFunc) HTTPHandler

NewHTTPHandlerFunc creates a new HTTPHandler with the http.HandlerFunc h, and the provided name and description

type Handler 

type Handler interface {
	Describer
}

Handler is a handler with no actual functionality

type HeardFunc 

type HeardFunc func(ctx context.Context, w ResponseWriter, m *Message, submatches [][]string) // Called once a message matches, and is passed any submatches from the regexp capture groups

HeardFunc describes the calling convention for a Hears handler.

type HearsHandler 

type HearsHandler interface {
	Handler
	Hears() *regexp.Regexp                                                          // Returns the regexp we want to hear
	Heard(ctx context.Context, w ResponseWriter, m *Message, submatches [][]string) // Called once a message matches, and is passed any submatches from the regexp capture groups
}

HearsHandler is a handler which responds to messages matching a specific pattern

func NewHearsHandler 

func NewHearsHandler(name, desc string, rgxp *regexp.Regexp, f HeardFunc) HearsHandler

NewHearsHandler wraps f as a Hears handler that reponnds to the regexp provided, with the given name a description

type Message 

type Message struct {
	To      string
	From    string
	Channel string

	Text        string // A plain text message
	Attachments []Attachment

	Private bool
	ToBot   bool

	*flag.FlagSet
	// contains filtered or unexported fields
}

Message describes a Message from or to a user. It is intended to provided a resonable lowest common denominator for modern chat systems. It takes the Slack message format to provide that minimum but makes no assumption about support for any markup. If used within a command handler, the message can also be used as a flag.FlagSet for adding and processing the message as a CLI command.

func (*Message) Parse 

func (m *Message) Parse() error

Parse process any Args for this message in line with any flags that have been added to the message.

func (*Message) Reply 

func (m *Message) Reply(txt string) *Message

Reply returns a messsage with Text tx and the From and To fields switched

func (*Message) Replyf 

func (m *Message) Replyf(s string, is ...interface{}) *Message

Replyf returns message with txt set to the fmt.Printf style formatting, and the from/to fields switched.

type Mux 

type Mux struct {
	*sync.RWMutex
	// contains filtered or unexported fields
}

Mux is a Handler that multiplexes messages to a set of Command, Hears, and Raw handlers. 

var DefaultMux *Mux

DefaultMux is a default Mux instance, http Handlers will be added to http.DefaultServeMux

func NewMux 

func NewMux(name, desc string) *Mux

NewMux creates a new Mux.

func (*Mux) Add 

func (mx *Mux) Add(h Handler) error

Add a generic handler that supports one or more of the handler types. WARNING: This may be removed in the future. Prefer to the specific Add*Handler methods.

func (*Mux) AddBackgroundHandler 

func (mx *Mux) AddBackgroundHandler(h BackgroundHandler) error

AddBackgroundHandler adds the provided handler to the Mux. It will be started with the Mux is started.

func (*Mux) AddCommandHandler 

func (mx *Mux) AddCommandHandler(h CommandHandler) *CommandMux

AddCommandHandler Adds the provided handler to the mux. The returns CommandMux can be used to add sub-commands to this command handler.

func (*Mux) AddHTTPHandler 

func (mx *Mux) AddHTTPHandler(h HTTPHandler) *url.URL

AddHTTPHandler registers h as a HTTP handler. The name of the Mux, and the name of the handler are used to construct a unique URL that can be used to send web requests to this handler

func (*Mux) AddHearsHandler 

func (mx *Mux) AddHearsHandler(h HearsHandler) error

AddHearsHandler adds the provided handler to the mux. All messages matching the Hears patterns will be forwarded to the handler.

func (*Mux) AddRawHandler 

func (mx *Mux) AddRawHandler(h RawHandler) error

AddRawHandler adds the provided handler to the Mux. All messages sent to the mux will be forwarded to this handler.

func (*Mux) Describe 

func (mx *Mux) Describe() (string, string)

Describe implements the Describe method of Handler for the Mux

func (*Mux) Handle 

func (mx *Mux) Handle(ctx context.Context, w ResponseWriter, m *Message) error

Handle implements the Handler interface. Message will first be passed to any registered RawHandlers. If the message has been deemed, by the Adapter to have been sent directly to the bot, any comand handlers will be processed. Then, if appropriate, the message will be matched against any Hears patterns and all matching Heard functions will then be called. Any unrecognized errors from the Command handlers will be passed back to the user that sent us the message.

func (*Mux) ServeHTTP 

func (mx *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP iplements http.ServeHTTP for a Mux to allow it to act as a web server.

func (*Mux) StartBackground 

func (mx *Mux) StartBackground(ctx context.Context, w ResponseWriter)

StartBackground starts any registered background handlers.

type RawFunc 

type RawFunc func(ctx context.Context, w ResponseWriter, m *Message) error

RawFunc describes the calling convention for RawHandler. m is the incoming message. Responses can be written to w.

type RawHandler 

type RawHandler interface {
	Handler
	Handle(ctx context.Context, w ResponseWriter, m *Message) error
}

RawHandler will recieve every message sent to the handler, without any filtering.

func NewRawHandler 

func NewRawHandler(name, desc string, f RawFunc) RawHandler

NewRawHandler will wrap the function f as a RawHandler with the name and description provided

type Receiver 

type Receiver interface {
	Receive() <-chan *Message // Receive returns a channel that can be used to read one message, nil indicated there will be no more messages
}

Receiver cam ne used to receive messages

type ResponseWriter 

type ResponseWriter interface {
	Sender
	io.Writer

	SetChannel(c string) // Forces messages to a certain channel
	SetTo(to string)     // Forces messages to a certain user
	SetSender(a Sender)  // Forces messages to a different sender or adapter
}

ResponseWriter is used to Send messages back to a user.

func NewNullResponseWriter 

func NewNullResponseWriter(m Message) ResponseWriter

NewNullResponseWriter creates a ResponseWriter that discards all message sent to it.

type Sender 

type Sender interface {
	Send(ctx context.Context, m *Message)
}

Sender can be used to send messages

type User 

type User string

User represents a user within the chat sytems. The adapter is responsible for translating the string User to and from it's external representation

Source Files

View all Source files

Directories

Path Synopsis
adapters
irc
Package irc implements a simple adapter for IRC using github.com/thoj/go-ircevent
 Package irc implements a simple adapter for IRC using github.com/thoj/go-ircevent
shell
Package shell implements a simple adapter that provides a readline style shell adapter for debugging purposes
 Package shell implements a simple adapter that provides a readline style shell adapter for debugging purposes
slack
Package slac implements an adapter for http://slack.com using github.com/nlopes/slack
 Package slac implements an adapter for http://slack.com using github.com/nlopes/slack
cmd
hugot
hugot-irc
hugot-shell
handlers
ping
Package ping provides a handler that replies to any message sent
 Package ping provides a handler that replies to any message sent
tableflip
Package tableflip provides an exacmple Hears handler that will flip tables on behalf of embittered users.
 Package tableflip provides an exacmple Hears handler that will flip tables on behalf of embittered users.
testcli
Package testcli provides an example Command handler with nested command handling.
 Package testcli provides an example Command handler with nested command handling.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.