1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
# ExIRC
[](https://travis-ci.org/bitwalker/exirc)
[](https://hex.pm/packages/exirc)
ExIRC is a IRC client library for Elixir projects. It aims to have a clear, well
documented API, with the minimal amount of code necessary to allow you to connect and
communicate with IRC servers effectively. It aims to implement the full RFC2812 protocol,
and relevant parts of RFC1459.
## Getting Started
Add ExIRC as a dependency to your project in mix.exs, and add it as an application:
```elixir
defp deps do
[{:exirc, "~> x.x.x"}]
end
defp application do
[applications: [:exirc],
...]
end
```
Then fetch it using `mix deps.get`.
To use ExIRC, you need to start a new client process, and add event handlers. An example event handler module
is located in `lib/exirc/example_handler.ex`. **The example handler is kept up to date with all events you can
expect to receive from the client**. A simple module is defined below as an example of how you might
use ExIRC in practice. ExampleHandler here is the one that comes bundled with ExIRC.
There is also a variety of examples in `examples`, the most up to date of which is `examples/bot`.
```elixir
defmodule ExampleSupervisor do
defmodule State do
defstruct host: "chat.freenode.net",
port: 6667,
pass: "",
nick: "bitwalker",
user: "bitwalker",
name: "Paul Schoenfelder",
client: nil,
handlers: []
end
def start_link(_) do
:gen_server.start_link(__MODULE__, [%State{}])
end
def init(state) do
# Start the client and handler processes, the ExIRC supervisor is automatically started when your app runs
{:ok, client} = ExIRC.start_link!()
{:ok, handler} = ExampleHandler.start_link(nil)
# Register the event handler with ExIRC
ExIRC.Client.add_handler client, handler
# Connect and logon to a server, join a channel and send a simple message
ExIRC.Client.connect! client, state.host, state.port
ExIRC.Client.logon client, state.pass, state.nick, state.user, state.name
ExIRC.Client.join client, "#elixir-lang"
ExIRC.Client.msg client, :privmsg, "#elixir-lang", "Hello world!"
{:ok, %{state | :client => client, :handlers => [handler]}}
end
def terminate(_, state) do
# Quit the channel and close the underlying client connection when the process is terminating
ExIRC.Client.quit state.client, "Goodbye, cruel world."
ExIRC.Client.stop! state.client
:ok
end
end
```
A more robust example usage will wait until connected before it attempts to logon and then wait until logged
on until it attempts to join a channel. Please see the `examples` directory for more in-depth examples cases.
```elixir
defmodule ExampleApplication do
use Application
# See http://elixir-lang.org/docs/stable/elixir/Application.html
# for more information on OTP Applications
def start(_type, _args) do
import Supervisor.Spec, warn: false
{:ok, client} = ExIRC.start_link!
children = [
# Define workers and child supervisors to be supervised
worker(ExampleConnectionHandler, [client]),
# here's where we specify the channels to join:
worker(ExampleLoginHandler, [client, ["#ohaibot-testing"]])
]
# See http://elixir-lang.org/docs/stable/elixir/Supervisor.html
# for other strategies and supported options
opts = [strategy: :one_for_one, name: ExampleApplication.Supervisor]
Supervisor.start_link(children, opts)
end
end
defmodule ExampleConnectionHandler do
defmodule State do
defstruct host: "chat.freenode.net",
port: 6667,
pass: "",
nick: "bitwalker",
user: "bitwalker",
name: "Paul Schoenfelder",
client: nil
end
def start_link(client, state \\ %State{}) do
GenServer.start_link(__MODULE__, [%{state | client: client}])
end
def init([state]) do
ExIRC.Client.add_handler state.client, self
ExIRC.Client.connect! state.client, state.host, state.port
{:ok, state}
end
def handle_info({:connected, server, port}, state) do
debug "Connected to #{server}:#{port}"
ExIRC.Client.logon state.client, state.pass, state.nick, state.user, state.name
{:noreply, state}
end
# Catch-all for messages you don't care about
def handle_info(msg, state) do
debug "Received unknown messsage:"
IO.inspect msg
{:noreply, state}
end
defp debug(msg) do
IO.puts IO.ANSI.yellow() <> msg <> IO.ANSI.reset()
end
end
defmodule ExampleLoginHandler do
@moduledoc """
This is an example event handler that listens for login events and then
joins the appropriate channels. We actually need this because we can't
join channels until we've waited for login to complete. We could just
attempt to sleep until login is complete, but that's just hacky. This
as an event handler is a far more elegant solution.
"""
def start_link(client, channels) do
GenServer.start_link(__MODULE__, [client, channels])
end
def init([client, channels]) do
ExIRC.Client.add_handler client, self
{:ok, {client, channels}}
end
def handle_info(:logged_in, state = {client, channels}) do
debug "Logged in to server"
channels |> Enum.map(&ExIRC.Client.join client, &1)
{:noreply, state}
end
# Catch-all for messages you don't care about
def handle_info(_msg, state) do
{:noreply, state}
end
defp debug(msg) do
IO.puts IO.ANSI.yellow() <> msg <> IO.ANSI.reset()
end
end
```
## Projects using ExIRC (in the wild!)
Below is a list of projects that we know of (if we've missed anything,
send a PR!) that use ExIRC in the wild.
- [Kuma][kuma] by @ryanwinchester
- [Offension][offension] by @shymega
- [hedwig_irc][hedwig_irc] by @jeffweiss
[kuma]: https://github.com/ryanwinchester/kuma
[offension]: https://github.com/shymega/offension
[hedwig_irc]: https://github.com/jeffweiss/hedwig_irc
|
