package module
Version: v0.0.0-...-9d5712f Latest Latest

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

Go to latest
Published: Jul 19, 2014 License: Apache-2.0 Imports: 12 Imported by: 0



A chat bot in Go, now with 100% less CoffeeScript!

Getting started

"Good morning, Dr. Chandra. This is HAL. I'm ready for my first lesson."

Hal is Go all the way down, and uses standard packages wherever possible. For an idea of how you can use it, look at a simple example, or a more complex example. API Documentation is available here.

Is it any good?

Probably not.


Hal doesn't have any command line options; instead we utilize environment variables exclusively. See configuration options for an exhaustive list of options.


Adapters are what hal uses to integrate with your chat services. Visit the following links for detailed information.

If you don't see your preferred chat service listed, let me know!


Stores are the brains of hal, used to persist long-term data and retrieve when needed. Review the links below for your store of choice.

If you think support for a particular store is needed, just open a ticket 🍻

Bugs, features, rants, hate-mail, etc.

Please use the issue tracker for development progress tracking, feature requests, or bug reports. Thank you! ❤️


Copyright 2014 Applied Awesome LLC.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at


Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.





View Source
const (
	HEAR    = "HEAR"

Handler constants


View Source
var (
	// Config is a global config
	Config = newConfig()
	// Logger is a global logger
	Logger = newLogger()
	// Router is a global HTTP muxer
	Router = newRouter()
View Source
var Adapters = map[string]adapter{}

Adapters is a map of registered adapters

View Source
var Handlers = map[string]handler{}

Handlers is a map of registered handlers

View Source
var Stores = map[string]store{}

Stores is a map of registered stores


func Close

func Close() error

Close shuts down the robot. Unused?

func Enter

func Enter(fn func(res *Response) error) handler

Enter returns a new listener for Enter messages

func Hear

func Hear(pattern string, fn func(res *Response) error) handler

Hear a message

func Leave

func Leave(fn func(res *Response) error) handler

Leave creates a new listener for Leave messages

func NewHandler

func NewHandler(h handler) handler

NewHandler func

func RegisterAdapter

func RegisterAdapter(name string, newFunc func(*Robot) (Adapter, error))

RegisterAdapter registers an adapter

func RegisterStore

func RegisterStore(name string, newFunc func(*Robot) (Store, error))

RegisterStore registers a new store

func Respond

func Respond(pattern string, fn func(res *Response) error) handler

Respond creates a new listener for Respond messages

func Topic

func Topic(pattern string, fn func(res *Response) error) handler

Topic returns a new listener for Topic messages


type Adapter

type Adapter interface {
	// New() (Adapter, error)
	Run() error
	Stop() error

	Receive(*Message) error
	Send(*Response, ...string) error
	Emote(*Response, ...string) error
	Reply(*Response, ...string) error
	Topic(*Response, ...string) error
	Play(*Response, ...string) error

	String() string

Adapter interface

func NewAdapter

func NewAdapter(robot *Robot) (Adapter, error)

NewAdapter creates a new initialized adapter

type BasicAdapter

type BasicAdapter struct {

BasicAdapter declares common functions shared by all adapters

func (*BasicAdapter) SetRobot

func (a *BasicAdapter) SetRobot(r *Robot)

SetRobot sets the adapter's Robot

func (*BasicAdapter) String

func (a *BasicAdapter) String() string

type BasicHandler

type BasicHandler struct {
	Method  string
	Pattern string
	Usage   string
	Run     func(res *Response) error

BasicHandler is used to construct handlers that are low complexity and may not benefit from creating a custom handler type.

Example (Hear)
package main

import (

func main() {
	res := hal.Response{
		Match: []string{},
	h := &hal.BasicHandler{
		Method:  hal.HEAR,
		Pattern: `echo (.+)`,
		Usage:   "echo <string> - repeats <string> back",
		Run: func(res *hal.Response) error {

> echo foo bar baz
foo bar baz
Example (Respond)
	Method:  hal.RESPOND,
	Pattern: `(?i)ping`, // (?i) is a flag that makes the match case insensitive
	Usage:   `hal ping - replies with "PONG"`,
	Run: func(res *hal.Response) error {

func (*BasicHandler) Handle

func (h *BasicHandler) Handle(res *Response) error

Handle implements the hal.Handler interface

type BasicStore

type BasicStore struct {
	Robot *Robot

BasicStore struct to be embedded in other stores

func (*BasicStore) SetRobot

func (s *BasicStore) SetRobot(r *Robot)

SetRobot sets the adapter's Robot

func (*BasicStore) String

func (s *BasicStore) String() string

type Envelope

type Envelope struct {
	Room string
	User *User

Envelope contains metadata about the chat message.

type Handler

type Handler struct {
	// contains filtered or unexported fields

Handler declares common functions shared by all handlers

func (*Handler) Handle

func (h *Handler) Handle(res *Response) error

Handle func

func (*Handler) Match

func (h *Handler) Match(res *Response) bool

Match func

func (*Handler) Method

func (h *Handler) Method() string

Method func

func (*Handler) Pattern

func (h *Handler) Pattern() string

Pattern func

func (*Handler) Regexp

func (h *Handler) Regexp() *regexp.Regexp

Regexp func

func (*Handler) Run

func (h *Handler) Run(res *Response) error

Run func

func (*Handler) Usage

func (h *Handler) Usage() string

Usage func

type Message

type Message struct {
	ID   string
	User User
	Room string
	Text string
	Type string

Message represents an incoming chat message.

func (*Message) String

func (msg *Message) String() string

String implements the Stringer interface

type Response

type Response struct {
	Robot    *Robot
	Envelope *Envelope
	Message  *Message
	Match    []string

Response struct

func NewResponse

func NewResponse(robot *Robot) *Response

NewResponse returns a new Response object

func NewResponseFromMessage

func NewResponseFromMessage(robot *Robot, msg *Message) *Response

NewResponseFromMessage returns a new Response object with an associated Message

func (*Response) Emote

func (res *Response) Emote(strings ...string) error

Emote posts an emote back to the chat source

func (*Response) Play

func (res *Response) Play(strings ...string) error

Play posts a sound message

func (*Response) Reply

func (res *Response) Reply(strings ...string) error

Reply posts a message mentioning the current user

func (*Response) Room

func (res *Response) Room() string

Room is the room of the response's message

func (*Response) Send

func (res *Response) Send(strings ...string) error

Send posts a message back to the chat source

func (*Response) Text

func (res *Response) Text() string

Text is the text of the response's message

func (*Response) Topic

func (res *Response) Topic(strings ...string) error

Topic posts a topic changing message

func (*Response) UserID

func (res *Response) UserID() string

UserID returns the id of the Message's User

func (*Response) UserName

func (res *Response) UserName() string

UserName returns the id of the Message's User

func (*Response) UserRoles

func (res *Response) UserRoles() []string

UserRoles returns the roles of the Message's User

type Robot

type Robot struct {
	Name    string
	Alias   string
	Adapter Adapter
	Store   Store

	Users *UserMap
	// contains filtered or unexported fields

Robot receives messages from an adapter and sends them to listeners

func New

func New() (*Robot, error)

New returns a Robot instance.

func NewRobot

func NewRobot() (*Robot, error)

NewRobot returns a new Robot instance

func (*Robot) Handle

func (robot *Robot) Handle(handlers ...handler)

Handle registers a new handler with the robot

func (*Robot) Handlers

func (robot *Robot) Handlers() []handler

Handlers returns the robot's handlers

func (*Robot) Receive

func (robot *Robot) Receive(msg *Message) error

Receive dispatches messages to our handlers

func (*Robot) Run

func (robot *Robot) Run() error

Run initiates the startup process

func (*Robot) SetAdapter

func (robot *Robot) SetAdapter(adapter Adapter)

SetAdapter sets robot's adapter

func (*Robot) SetName

func (robot *Robot) SetName(name string)

SetName sets robot's name

func (*Robot) SetStore

func (robot *Robot) SetStore(store Store)

SetStore sets robot's adapter

func (*Robot) Stop

func (robot *Robot) Stop() error

Stop initiates the shutdown process

type Store

type Store interface {
	Open() error
	Close() error
	Get(string) ([]byte, error)
	Set(key string, data []byte) error
	Delete(string) error

Store interface for storage backends to implement

func NewStore

func NewStore(robot *Robot) (Store, error)

NewStore returns an initialized store

type User

type User struct {
	ID      string
	Name    string
	Roles   []string
	Options map[string]interface{}

User is a chat participant

type UserMap

type UserMap struct {
	Map map[string]User
	// contains filtered or unexported fields

UserMap handles the known users

func NewUserMap

func NewUserMap(robot *Robot) *UserMap

NewUserMap returns an initialized UserMap

func (*UserMap) All

func (um *UserMap) All() map[string]User

All returns the underlying map of all users

func (*UserMap) Decode

func (um *UserMap) Decode() (map[string]User, error)

Decode unmarshals a JSON object into a map of strings to Users

func (*UserMap) Encode

func (um *UserMap) Encode() ([]byte, error)

Encode marshals a UserMap to JSON

func (*UserMap) Get

func (um *UserMap) Get(id string) (User, error)

Get looks up a user by id and returns a User object

func (*UserMap) GetByName

func (um *UserMap) GetByName(name string) (User, error)

GetByName looks up a user by name and returns a User object

func (*UserMap) Load

func (um *UserMap) Load() error

Load retrieves known users from the store and populates the UserMap

func (*UserMap) Save

func (um *UserMap) Save() error

Save persists known users to the store

func (*UserMap) Set

func (um *UserMap) Set(id string, user User) error

Set adds or updates a user in the UserMap and persists it to the store


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL