gophirc, an event based, multi server IRC framework written from scratch, in Go
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
config
logger
.gitignore
.travis.yml
LICENSE
README.md
commands.go
helpers.go
helpers_test.go
irc.go
irc_test.go
user.go
user_test.go

README.md

GoDoc Go Report Card Build Status gophirc version Twitter URL

gophirc

A simple IRC bot framework written from scratch, in Go.

Description

Event based IRC framework.

Warning

The API might break anytime.

Framework managed events

  • Manages server PING requests (not CTCP PING)
  • Registers on first NOTICE *
  • Identifies on RPL_WELCOME (event 001)
  • Joins the received invites & sends a greeting to the channel
  • Logs if the bot gets kicked from a channel

Features

  • Capability to connect to multiple servers
  • Multiple per event callbacks
  • State & general logging
  • Graceful exit handled either by a SIGINT (Ctrl-C)
  • Parses a user from an IRC formatted nick!user@host to a User{}
  • Config implements a basic checking on values
  • Already implemented basic commands - JOIN, PART, PRIVMSG, NOTICE, KICK, INVITE, MODE, CTCP commands
  • Many (?) more

Events & callbacks

An event follows the next schema:

type Event struct {
    Raw       string   // the whole raw line
    Code      string   // the reply code
    Source    string   // the source of the event (server, user)
    Arguments []string // the arguments after the event code

    User    *User  // if we can parse a user from the source, add the parsed user here
    Message string // if it's a PRIVMSG, add the message here
    ReplyTo string // if it's a PRIVMSG, add the recipient here (user or channel)
}

You can set callbacks for, technically, all events - numeric reply codes (e.g. "001", "900", etc.) or alpha codes (e.g. "NOTICE", "INVITE", etc.).

Note: CTCP events will have the code set to the corresponding CTCP action, not PRIVMSG.

The framework already binds callbacks for:

  • 001 - to identify with NickServ
  • 900 - to join the channels specified in config
  • NOTICE - only the first event, in order to register with the network
  • INVITE - joins the channel & greets

Examples

Setting up a simple config:

{
  "servers": {
    "first": {
      "address": "irc.server.tld",
      "port": 6667,
      "nickname": "gophirc",
      "nickserv_password": "my_nick_pass",
      "channels": [
        "#my_chan"
      ],
      "admins": [
        "my_nickname"
      ]
    }
  }
}

Note: a full config example can be found in the config/config.json.example file.

Setting a simple bot:

package main

import (
    "sync"
    "github.com/vlad-s/gophirc"
    "github.com/vlad-s/gophirc/config"
)

func main() {
    var wg sync.WaitGroup
    conf, _ := config.Parse("config.json")
    irc := gophirc.New(conf.Servers["name"], &wg)
    irc.Connect()
    irc.Loop()
}

Note: error handling remains an exercise for the reader

Setting up a callback to respond to a CTCP VERSION:

irc.AddEventCallback("VERSION", func(e *gophirc.Event) {
    irc.Notice(e.User.Nick, "\001My own Go bot!\001")
})

Setting up a callback to check for custom messages:

irc.AddEventCallback("PRIVMSG", func(e *gophirc.Event) {
    replyTo := e.Arguments[0]
    message := strings.Join(e.Arguments[1:], " ")[1:]

    switch message {
    case "shrug":
        irc.PrivMsg(replyTo, `¯\_(ツ)_/¯`)
    }
})

For more examples on usage, please see gophircbot.

To do

  • Add tests
    • Config
    • User
    • Logger
    • Helpers
    • IRC
    • commands
  • Add defaults
    • Nickname, Username, Realname
  • Parse CTCP messages into events
  • Add more commands: MODE, KICK, etc.
  • Add regex matching for nicknames, channels
  • Connect Multiple servers
  • Add ignored users