bot

README

go-bot

Nice to meet you! I'm a IRC bot written in Go using go-ircevent for IRC connectivity.

I can be deployed to heroku and used in slack to overpower slackbot.

#go-bot @ irc.freenode.org

I'm always hanging out as go-bot in the channel #go-bot @ irc.freenode.org

To see what I can do, type !help in the channel or send me a private message.

My awesome commands

Active commands

• !gif: Posts a random gif url from giphy.com. Try it with: !gif cat
• !catgif: Posts a random cat gif url from thecatapi.com
• !godoc: Searches packages in godoc.org. Try it with: !godoc net/http
• !puppet: Allows you to send messages through the bot: Try it with: !puppet say #go-bot Hello!

Passive commands (triggers)

Passive commands are triggered by keywords, urls, etc.

These commands differ from the active commands as they are executed for every match in any text. Ex: The Chuck Norris command, replies with a Chuck Norris fact every time the words "chuck" or "norris" are mentioned on a channel.

• url: Detects url and gets it's title (very naive implementation, works sometimes)
• catfacts: Tells a random cat fact based on some cat keywords
• jira: Detects jira issue numbers and posts the url (necessary to configure the JIRA URL)
• chucknorris: Shows a random chuck norris quote every time the word "chuck" is mentioned

Brazilian commands (pt-br)

I also have some brazilian commands which only makes sense to brazillians:

• megasena: Gera um número da megasena ou mostra o último resultado
• cotacao: Informa a cotação atual do Dólar e Euro
• dilma (passivo): Diz alguma frase da Dilma quando a palavra "dilma" é citada

Example commands

If you wish to write your own commands, start with the 2 example commands, they are in the example directory.

Joining and parting channels

IRC

If you want me to join your channel, send me a private message with:

!join #channel pass

If I'm boring you, just send a !part command in a channel I'm in.

Slack

!join and !part does not work on slack (yet), so use the slack commands like /invite and /remove to invite the bot to the desired channels.

Connecting to Slack

To deploy your go-bot to slack, you need to:

• Create a new bot user integration on slack and get your token
• Import the package bot
• Import the commands you would like to use
• Call Bot.RunSlack(token)

Here is a full example reading the slack token from the `SLACK_TOKEN env var:

package main

import (
    "os"

    "github.com/fabioxgn/go-bot"
    _ "github.com/fabioxgn/go-bot/commands/catfacts"
    _ "github.com/fabioxgn/go-bot/commands/catgif"
    _ "github.com/fabioxgn/go-bot/commands/chucknorris"
    // Import all the commands you wish to use
)

func main() {
    bot.RunSlack(os.Getenv("SLACK_TOKEN")
}

Connecting to IRC

To deploy your own go-bot, you need to:

• Import the package bot
• Import the commands you would like to use
• Fill the Config struct
• Call Bot.Run(config)

Here is a full example:

package main
	import (
		"github.com/fabioxgn/go-bot"
		_ "github.com/fabioxgn/go-bot/commands/catfacts"
		_ "github.com/fabioxgn/go-bot/commands/catgif"
		_ "github.com/fabioxgn/go-bot/commands/chucknorris"
		// Import all the commands you wish to use
		"os"
		"strings"
	)

	func main() {
		bot.Run(&bot.Config{
			Server:   os.Getenv("IRC_SERVER"),
			Channels: strings.Split(os.Getenv("IRC_CHANNELS"), ","),
			User:     os.Getenv("IRC_USER"),
			Nick:     os.Getenv("IRC_NICK"),
			Password: os.Getenv("IRC_PASSWORD"),
			UseTLS:   true,
			Debug:    os.Getenv("DEBUG") != "",})
	}

To join channels with passwords just put the password after the channel name separated by a space:

Channels: []string{"#mychannel mypassword", "#go-bot"}

Deploying to heroku

To see an example project on how to deploy it to heroku, please see my own configuration:

• IRC: https://github.com/fabioxgn/go-bot-heroku
• Slack: https://github.com/fabioxgn/go-bot-slack

Documentation

Overview

Package bot provides a simple to use IRC bot

Index

• Constants
• func RegisterCommand(command, description, exampleArgs string, cmdFunc activeCmdFuncV1)
• func RegisterCommandV2(command, description, exampleArgs string, cmdFunc activeCmdFuncV2)
• func RegisterPassiveCommand(command string, cmdFunc func(cmd *PassiveCmd) (string, error))
• func Run(c *Config)
• func RunSlack(token string)
• type Cmd
• type CmdResult
• type Config
• type PassiveCmd

Constants

const (
	// CmdPrefix is the prefix used to identify a command.
	// !hello whould be identified as a command
	CmdPrefix = "!"
)

Functions

func RegisterCommand

func RegisterCommand(command, description, exampleArgs string, cmdFunc activeCmdFuncV1)

RegisterCommand adds a new command to the bot. The command(s) should be registered in the Init() func of your package command: String which the user will use to execute the command, example: reverse decription: Description of the command to use in !help, example: Reverses a string exampleArgs: Example args to be displayed in !help <command>, example: string to be reversed cmdFunc: Function which will be executed. It will received a parsed command as a Cmd value

func RegisterCommandV2

func RegisterCommandV2(command, description, exampleArgs string, cmdFunc activeCmdFuncV2)

RegisterCommandV2 adds a new command to the bot. It is the same as RegisterCommand but the command can specify the channel to reply to

func RegisterPassiveCommand

func RegisterPassiveCommand(command string, cmdFunc func(cmd *PassiveCmd) (string, error))

RegisterPassiveCommand adds a new passive command to the bot. The command should be registered in the Init() func of your package Passive commands receives all the text posted to a channel without any parsing command: String used to identify the command, for internal use only (ex: logs) cmdFunc: Function which will be executed. It will received the raw message, channel and nick

func Run

func Run(c *Config)

Run reads the Config, connect to the specified IRC server and starts the bot. The bot will automatically join all the channels specified in the configuration

func RunSlack

func RunSlack(token string)

RunSlack connects to slack RTM API using the provided token

Types

type Cmd

type Cmd struct {
	Raw     string   // Raw is full string passed to the command
	Channel string   // Channel where the command was called
	Nick    string   // User who sent the message
	Message string   // Full string without the prefix
	Command string   // Command is the first argument passed to the bot
	FullArg string   // Full argument as a single string
	Args    []string // Arguments as array
}

Cmd holds the parsed user's input for easier handling of commands

type CmdResult

type CmdResult struct {
	Channel string // The channel where the bot should send the message
	Message string // The message to be sent
}

CmdResult is the result message of V2 commands

type Config

type Config struct {
	Server        string   // IRC server:port. Ex: irc.freenode.org:7000
	Channels      []string // Channels to connect. Ex: []string{"#go-bot", "#channel mypassword"}
	User          string   // The IRC username the bot will use
	Nick          string   // The nick the bot will use
	Password      string   // Server password
	UseTLS        bool     // Should connect using TLS?
	TLSServerName string   // Must supply if UseTLS is true
	Debug         bool     // This will log all IRC communication to standad output
}

Config must contain the necessary data to connect to an IRC server

type PassiveCmd

type PassiveCmd struct {
	Raw     string // Raw message sent to the channel
	Channel string // Channel which the message was sent to
	Nick    string // Nick of the user which sent the message
}

PassiveCmd holds the information which will be passed to passive commands when receiving a message