Class: Cereal::Bot

Inherits:
Object
  • Object
show all
Defined in:
lib/cereal.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Bot

Returns a new instance of Bot.



65
66
67
68
69
70
71
72
73
 
# File 'lib/cereal.rb', line 65

def initialize
  @name = 'Cereal'
  @nick = @name
  @login = 'cereal'
  @version = "Cereal #{Cereal::VERSION} (Ruby #{RUBY_VERSION})"
  @finger = 'You ought to be arrested for fingering a bot!'
  @message_delay = 1.0
  @verbose = false
end

Instance Attribute Details

#finger ⇒ Object

Returns the value of attribute finger.



62
63
64
 
# File 'lib/cereal.rb', line 62

def finger
  @finger
end

#login ⇒ Object

Returns the value of attribute login.



62
63
64
 
# File 'lib/cereal.rb', line 62

def 
  @login
end

#message_delay ⇒ Object

Returns the value of attribute message_delay.



62
63
64
 
# File 'lib/cereal.rb', line 62

def message_delay
  @message_delay
end

#name ⇒ Object

Returns the value of attribute name.



62
63
64
 
# File 'lib/cereal.rb', line 62

def name
  @name
end

#nick ⇒ Object

Returns the value of attribute nick.



63
64
65
 
# File 'lib/cereal.rb', line 63

def nick
  @nick
end

#verbose ⇒ Object

Returns the value of attribute verbose.



62
63
64
 
# File 'lib/cereal.rb', line 62

def verbose
  @verbose
end

#version ⇒ Object

Returns the value of attribute version.



62
63
64
 
# File 'lib/cereal.rb', line 62

def version
  @version
end

Instance Method Details

#ban(channel, hostmask) ⇒ Object

Ban a user from a channel. An example of a valid hostmask is “*!compu@.18hp.net”. This may be used in conjunction with the kick method to permanently remove a user from a channel. This action may require the bot have operator status in the channel. Some IRC networks allow banning by nick in adddition to hostmask.

channel

The channel to ban the user from.

hostmask

A hostmask representing the user we’re banning.



161
162
163
 
# File 'lib/cereal.rb', line 161

def ban(channel, hostmask)
  send_raw("MODE #{channel} +b #{hostmask}")
end

#channels ⇒ Object

Returns a hash of channels that the bot is currently in. The hash’s keys are strings representing the channel name, so that channels.keys will return an array of channel name strings. The hash’s values are arrays of Cereal::User objects representing the users in that channel, which is the same data returned by get_users.



122
123
124
 
# File 'lib/cereal.rb', line 122

def channels
  @connection.channels
end

#confirm_nick(confirmed_nick) ⇒ Object

Used by Cereal::Connection to change @nick after we’ve received a confirmation that our requested nick has been assigned to us.

confirmed_nick

The nick that has been assigned to us.



252
253
254
255
 
# File 'lib/cereal.rb', line 252

def confirm_nick(confirmed_nick)
  @nick = confirmed_nick
  @connection.temp_nick = confirmed_nick
end

#connect(server, port = 6667, password = nil) ⇒ Object

Connect to a server, optionally specifying a port and password. This method starts the “main event loop.” You may want to rescue IrcError and/or NickAlreadyInUseError here, as they may be raised upon a connection failure or other trouble.

server

The server hostname to connect to.

[port]

The port to connect to. Most IRC servers use port 6667 or similar.

[password]

The password to connect to the server with. A value of nil (the default) will cause Cereal to skip this step.



83
84
85
86
87
88
 
# File 'lib/cereal.rb', line 83

def connect(server, port=6667, password=nil)
  EventMachine::run {
    @connection = EventMachine::connect(server, port, Cereal::Connection,
        :bot => self, :password => password)
  }
end

#connected? ⇒ Boolean

Returns true if the bot is currently connected to a server, and false if otherwise (even if the bot is currently negotiating a connection).

Returns:

  • (Boolean) 


259
260
261
 
# File 'lib/cereal.rb', line 259

def connected?
  @connection && @connection.state == Cereal::Connection::STATE_CONNECTED
end

#get_users(channel) ⇒ Object

Returns an array of Cereal::User objects representing the users in the specified channel. Note that the bot must be in a channel to be aware of its users. In addition, this method may return an incomplete list of the bot has not received the entire user list for a channel immediately after joining. To be sure you receive a full list, you may want to override on_user_list instead.

channel

The channel to fetch an array of Cereal::User objects for.



113
114
115
116
 
# File 'lib/cereal.rb', line 113

def get_users(channel)
  channel.downcase!
  @connection.channels.fetch(channel, {}).keys
end

#join(channel, key = nil) ⇒ Object

Join a channel with an optional key.

channel

The channel to join.

[key]

The key that will be used to join the channel.



129
130
131
 
# File 'lib/cereal.rb', line 129

def join(channel, key=nil)
  send_raw("JOIN #{channel}" + (key.nil? ? '' : " #{key}"))
end

#kick(channel, nick, reason = '') ⇒ Object

Attempt to kick a user from a channel, optionally giving a reason. This action may require the bot have operator status in the channel.

channel

The channel to kick the user from.

nick

The nick of the user to kick.

[reason]

The reason for kicking the user.



151
152
153
 
# File 'lib/cereal.rb', line 151

def kick(channel, nick, reason='')
  send_raw("KICK #{channel} #{nick} :#{reason}")
end

#log(line) ⇒ Object

Add a line to the log. The default behavior is to output to STDOUT using the “PircBot” log format, which is recognized by pisg, the Perl IRC Statistics Generator. This is only done if @verbose is set to true.

The PircBot log format is described as each line beginning with an integer that is the number of milliseconds since the epoch, followed by a single space, “ ”, then the log message. Outgoing messages are prefixed by “>>>” immediately following the space character after the timestamp:

1233871496459 >>>NICK Wheaties
1233871496459 >>>USER wheaties 0 * :Botfast of Champions!
1233871496488 :ravaged.mule.anus 001 Wheaties :Welcome to the Internet Relay Network Wheaties!~wheaties@Stig
line

The line to add to the log.



103
104
105
 
# File 'lib/cereal.rb', line 103

def log(line)
  puts (Time.now.to_f * 1000).to_i.to_s + " #{line}" if @verbose
end

#on_action(sender, target, action) ⇒ Object 



271
272
273
 
# File 'lib/cereal.rb', line 271

def on_action(sender, target, action)
  
end

#on_channel_info(channel, user_count, topic) ⇒ Object 



275
276
277
 
# File 'lib/cereal.rb', line 275

def on_channel_info(channel, user_count, topic)
  
end

#on_connect(host) ⇒ Object 



279
280
281
 
# File 'lib/cereal.rb', line 279

def on_connect(host)
  
end

#on_disconnect ⇒ Object 



283
284
285
 
# File 'lib/cereal.rb', line 283

def on_disconnect
  
end

#on_finger(sender, target) ⇒ Object 



287
288
289
 
# File 'lib/cereal.rb', line 287

def on_finger(sender, target)
  send_raw "NOTICE #{sender.nick} :\1FINGER #{@finger}\1"
end

#on_invite(sender, target, channel) ⇒ Object 



291
292
293
 
# File 'lib/cereal.rb', line 291

def on_invite(sender, target, channel)
  
end

#on_join(sender, channel) ⇒ Object 



295
296
297
 
# File 'lib/cereal.rb', line 295

def on_join(sender, channel)
  
end

#on_kick(sender, channel, recipient, reason) ⇒ Object 



299
300
301
 
# File 'lib/cereal.rb', line 299

def on_kick(sender, channel, recipient, reason)
  
end

#on_message(sender, target, message) ⇒ Object 



303
304
305
 
# File 'lib/cereal.rb', line 303

def on_message(sender, target, message)
  
end

#on_nick_change(sender, new_nick) ⇒ Object 



307
308
309
 
# File 'lib/cereal.rb', line 307

def on_nick_change(sender, new_nick)
  
end

#on_notice(sender, target, notice) ⇒ Object 



311
312
313
 
# File 'lib/cereal.rb', line 311

def on_notice(sender, target, notice)
  
end

#on_part(sender, channel) ⇒ Object 



315
316
317
 
# File 'lib/cereal.rb', line 315

def on_part(sender, channel)
  
end

#on_ping(sender, target, ping_value) ⇒ Object 



319
320
321
 
# File 'lib/cereal.rb', line 319

def on_ping(sender, target, ping_value)
  send_raw("NOTICE #{sender.nick} :\1PING #{ping_value}\1")
end

#on_private_message(sender, message) ⇒ Object 



323
324
325
 
# File 'lib/cereal.rb', line 323

def on_private_message(sender, message)
  
end

#on_quit(sender, reason) ⇒ Object 



327
328
329
 
# File 'lib/cereal.rb', line 327

def on_quit(sender, reason)
  
end

#on_server_ping(response) ⇒ Object 



331
332
333
 
# File 'lib/cereal.rb', line 331

def on_server_ping(response)
  @connection.send_data("PONG #{response}")
end

#on_server_response(code, response) ⇒ Object

Called when we receive a numeric response from the IRC server. Numeric replies are received in response to commands sent to the server, and are documented in RFC 2812, Section 5, “Replies”.

For example, we can use this method to discover the topic of a channel when we join it. If we join the channel ##test which has a topic of “My spoon is too big” then the response will be "Cereal ##test :My spoon is too big" with a code of 332 to signify that this is a topic. (Note that this is just an example, and that overriding on_topic is an easier way of finding the topic for a channel.)

code

Integer numeric code for the response.

response

Full response string from the IRC server.



347
348
349
 
# File 'lib/cereal.rb', line 347

def on_server_response(code, response)
  
end

#on_time(sender, target) ⇒ Object 



351
352
353
 
# File 'lib/cereal.rb', line 351

def on_time(sender, target)
  send_raw("NOTICE #{sender.nick} :\1TIME #{Time.new}\1")
end

#on_topic(set_by, channel, date, topic, changed) ⇒ Object

Called whenever a user sets the topic of a channel, or when Cereal joins a new channel and discovers its topic.

set_by

The nick of the user that set the topic.

channel

The channel whose topic has been set or discovered.

date

When the topic was set as a Time.

topic

The topic for the channel.

changed

True if the topic has just been changed, false if we’re simply discovering a new channel’s topic.



363
364
365
 
# File 'lib/cereal.rb', line 363

def on_topic(set_by, channel, date, topic, changed)
  
end

#on_unknown(line) ⇒ Object

Called whenever we receive a line from the IRC server that Cereal does not recognize.

line

The raw line that was received from the server.



370
371
372
 
# File 'lib/cereal.rb', line 370

def on_unknown(line)
  
end

#on_user_list(channel, users) ⇒ Object

Called when we receive a user list from the server after joining a channel.

After joining a channel, Cereal collects this information provided by the IRC server and calls this method as soon as it has the full list.

channel

The name of the channel.

users

An array of User objects residing in channel.



382
383
384
 
# File 'lib/cereal.rb', line 382

def on_user_list(channel, users)
  
end

#on_version(sender, target) ⇒ Object

Called whenever we receive a VERSION CTCP request. The default implementation responds with Cereal’s generic version string, so if you override this method, be sure to either mimic its functionality or call super(...).

sender

An OpenStruct object describing the sender of this request. See on_message.

target

The target of the VERSION request, be it our nick or a channel name.



394
395
396
 
# File 'lib/cereal.rb', line 394

def on_version(sender, target)
  send_raw("NOTICE #{sender.nick} :\1VERSION #{@version}\1")
end

#part(channel, reason = nil) ⇒ Object

Part a channel with an optional reason.

channel

The channel to leave.

[reason]

The reason for parting the channel.



136
137
138
 
# File 'lib/cereal.rb', line 136

def part(channel, reason=nil)
  send_raw("PART #{channel}" + (reason.nil? ? '' : " :#{reason}"))
end

#quit(reason = '') ⇒ Object

Quit from the IRC server with an optional reason.

[reason]

The reason for quitting the server.



142
143
144
 
# File 'lib/cereal.rb', line 142

def quit(reason = '')
  @connection.send_data("QUIT :#{reason}")
end

#send(target, message) ⇒ Object

send is a convenience combination of send_message and send_action. If message begins with “/me ”, Cereal sends an ACTION to target. Otherwise, a regular message is sent.

target

The channel or user to send to.

message

The message to send. If message begins with “/me ”, an ACTION is sent.



197
198
199
200
201
202
203
 
# File 'lib/cereal.rb', line 197

def send(target, message)
  if message =~ /^\/me (.*)$/
    send_action(target, $~[1])
  else
    send_message(target, message)
  end
end

#send_action(target, action) ⇒ Object Also known as: action

Send an action to a channel or user.

target

The channel or user to send to.

action

The action to send.



185
186
187
 
# File 'lib/cereal.rb', line 185

def send_action(target, action)
  send_ctcp(target, "ACTION #{action}")
end

#send_ctcp(target, command) ⇒ Object Also known as: ctcp

Send a CTCP (client-to-client protocol) command to a channel or user. Examples of such commands are PING <number>, FINGER, VERSION, etc.

# Request the version of the user DeadEd
send_ctcp('DeadEd', 'VERSION')
target

The channel or user to send the CTCP message to.

command

The CTCP command to send.



222
223
224
 
# File 'lib/cereal.rb', line 222

def send_ctcp(target, command)
  send_raw("PRIVMSG #{target} :\1#{command}\1")
end

#send_message(target, message) ⇒ Object Also known as: message, msg, pm

Send a message to a channel or a private message to a user.

# Send the message "Hello!" to the channel #perkele.
send_message('#perkele', 'Hello!')

# Send a private message to Jibbler that says "Hi!"
send_message('Jibbler', 'Hi!')
target

The channel or user nick to send to.

message

The message to send.



174
175
176
 
# File 'lib/cereal.rb', line 174

def send_message(target, message)
  send_raw("PRIVMSG #{target} :#{message}")
end

#send_notice(target, notice) ⇒ Object Also known as: notice

Send a notice to a channel or user.

target

The channel or user to send to.

notice

The notice to send.



208
209
210
 
# File 'lib/cereal.rb', line 208

def send_notice(target, notice)
  send_raw("NOTICE #{target} :#{notice}")
end

#send_raw(data) ⇒ Object Also known as: <<

Send raw data to the IRC server.

data

The data to send to the server.



265
266
267
 
# File 'lib/cereal.rb', line 265

def send_raw(data)
  @connection.send_raw(data) if !data.nil?
end