README.md
1# go-irc
2
3[](https://godoc.org/github.com/go-irc/irc)
4[](https://github.com/go-irc/irc/actions)
5[](https://coveralls.io/github/go-irc/irc?branch=master)
6
7This package was originally created to only handle message parsing,
8but has since been expanded to include a small abstraction around a
9connection and a simple client.
10
11This library is not designed to hide any of the IRC elements from
12you. If you just want to build a simple chat bot and don't want to
13deal with IRC in particular, there are a number of other libraries
14which provide a more full featured client if that's what you're
15looking for.
16
17This library is meant to stay as simple as possible so it can be a
18building block for other packages.
19
20This library aims for API compatibility whenever possible. New
21functions and other additions will most likely not result in a major
22version increase unless they break the API. This library aims to
23follow the semver recommendations mentioned on gopkg.in.
24
25Due to complications in how to support x/net/context vs the built-in context
26package, only go 1.7+ is officially supported.
27
28## Import Paths
29
30All development happens on the `master` branch and when features are
31considered stable enough, a new release will be tagged.
32
33* `gopkg.in/irc.v3` should be used to develop against the commits
34 tagged as stable
35* In previous versions, `github.com/go-irc/irc` used to be able to be
36 used to develop against the master branch but module support in go
37 seems to have broken this.
38
39## Development
40
41In order to run the tests, make sure all submodules are up to date. If you are
42just using this library, these are not needed.
43
44## Example
45
46```go
47package main
48
49import (
50 "log"
51 "net"
52
53 "gopkg.in/irc.v3"
54)
55
56func main() {
57 conn, err := net.Dial("tcp", "chat.freenode.net:6667")
58 if err != nil {
59 log.Fatalln(err)
60 }
61
62 config := irc.ClientConfig{
63 Nick: "i_have_a_nick",
64 Pass: "password",
65 User: "username",
66 Name: "Full Name",
67 Handler: irc.HandlerFunc(func(c *irc.Client, m *irc.Message) {
68 if m.Command == "001" {
69 // 001 is a welcome event, so we join channels there
70 c.Write("JOIN #bot-test-chan")
71 } else if m.Command == "PRIVMSG" && c.FromChannel(m) {
72 // Create a handler on all messages.
73 c.WriteMessage(&irc.Message{
74 Command: "PRIVMSG",
75 Params: []string{
76 m.Params[0],
77 m.Trailing(),
78 },
79 })
80 }
81 }),
82 }
83
84 // Create the client
85 client := irc.NewClient(conn, config)
86 err = client.Run()
87 if err != nil {
88 log.Fatalln(err)
89 }
90}
91```
92
93## Major Version Changes
94
95### v1
96
97Initial release
98
99### v2
100
101- CTCP messages will no longer be rewritten. The decision was made that this
102 library should pass through all messages without mangling them.
103- Remove Message.FromChannel as this is not always accurate, while
104 Client.FromChannel should always be accurate.
105
106### v3
107
108- Import path changed back to `gopkg.in/irc.v3` without the version suffix.
109
){kind=link}
){kind=link}
){kind=link}