Module: IRC::RFC2812::Commands

Defined in:
lib/irc/rfc2812/commands.rb

Overview

Implements all IRC commands that can be sent as described in RFC 2812: Internet Relay Chat Protocol (tools.ietf.org/html/rfc2812). The module only concerns itself with sending commands.

Examples:

class Connection
  include Banter::IRC::Commands
# Some methods that set up a socket and whatnot.
def raw(message)
    @socket.write "message\r\n"
  end
end
x = Connection.new
x.join '#channel'

Instance Method Summary (collapse)

Instance Method Details

- (Object) admin(target = nil)

Sends an ADMIN command. The ADMIN command is used to find information about the administrator of the given server, or current server if target parameter is omitted.

Parameters:

  • target (defaults to: nil) —

    A target (server name) String (default: nil).



329
330
331
 
# File 'lib/irc/rfc2812/commands.rb', line 329

def admin(target = nil)
  raw "ADMIN #{target}".strip
end

- (Object) away(text = nil)

Sends an AWAY command. With the AWAY command, clients can set an automatic reply string for any PRIVMSG commands directed at them (not to a channel they are on).

Parameters:

  • text (defaults to: nil) —

    A message String (default: nil).



461
462
463
 
# File 'lib/irc/rfc2812/commands.rb', line 461

def away(text = nil)
  raw text.nil? ? "AWAY" : "AWAY :#{text}"
end

- (Object) connect(target, port = 6667, remote = nil)

Sends a CONNECT command. The CONNECT command can be used to request a server to try to establish a new connection to another server immediately.

Parameters:

  • target —

    A target (server name) String.

  • port (defaults to: 6667) —

    A port number Integer (default: 6667).

  • remote (defaults to: nil) —

    A remote (server name) String (default: nil).



312
313
314
 
# File 'lib/irc/rfc2812/commands.rb', line 312

def connect(target, port = 6667, remote = nil)
  raw "CONNECT #{target} #{port} #{remote}".strip
end

- (Object) die

Sends a DIE command. An operator can use the DIE command to shutdown the server.



474
475
476
 
# File 'lib/irc/rfc2812/commands.rb', line 474

def die
  raw 'DIE'
end

- (Object) error(message)

Sends an ERROR command. The ERROR command is for use by servers when reporting a serious or fatal error to its peers.

Parameters:

  • message —

    A message String.



450
451
452
 
# File 'lib/irc/rfc2812/commands.rb', line 450

def error(message)
  raw "ERROR :#{message}"
end

- (Object) info(target = nil)

Sends an INFO command. The INFO command is REQUIRED to return information describing the server.

Parameters:

  • target (defaults to: nil) —

    A target (server name) String (default: nil).



337
338
339
 
# File 'lib/irc/rfc2812/commands.rb', line 337

def info(target = nil)
  raw "INFO #{target}".strip
end

- (Object) invite(nickname, channel)

Sends an INVITE command.

Parameters:

  • nickname —

    The nickname String of the user that should be invited.

  • channel —

    The channel name String.



212
213
214
 
# File 'lib/irc/rfc2812/commands.rb', line 212

def invite(nickname, channel)
  raw "INVITE #{String(nickname)} #{String(channel)}"
end

- (Object) ison(nicknames)

Sends an ISON command. The ISON command requests wether or not a nickname is currently on IRC.

Parameters:

  • nicknames —

    A nickname String or an Array of such Strings (max. 5).



525
526
527
 
# File 'lib/irc/rfc2812/commands.rb', line 525

def ison(nicknames)
  raw "ISON #{Array(nicknames).map { |nick| String(nick) }.join ' '}"
end

- (Object) join(channel, key = nil)

Sends a JOIN command (joins a channel). The JOIN command is used by a user to request to start listening to the specific channel. Note that this method doesn’t automatically add #s, &s, +s or !s.

Examples:

join '#foo'
join '#foo', 'key'
join ['#foo', #bar], ['key_for_#foo']

Parameters:

  • channel —

    The channel name String or an Array of them.

  • key (defaults to: nil) —

    The key for the channel as a String (default: nil).



136
137
138
139
140
141
142
143
144
145
 
# File 'lib/irc/rfc2812/commands.rb', line 136

def join(channel, key = nil)
  channel = Array(channel).each_slice(5).to_a
  key     = Array(key).each_slice(5).to_a
  
  channel.zip(key).map do |channels,keys|
    channels.map! { |chan| String(chan) }

    raw "JOIN #{channels.join ','} #{Array(keys).join ','}".strip
  end
end

- (Object) kick(channel, user, comment = nil)

Sends a KICK command.

Parameters:

  • channel —

    The channel name String.

  • user —

    The nickname String.

  • comment (defaults to: nil) —

    The kick message String (default: nil).



221
222
223
224
225
226
227
 
# File 'lib/irc/rfc2812/commands.rb', line 221

def kick(channel, user, comment = nil)
  if comment.nil?
    raw "KICK #{String(channel)} #{String(user)}"
  else
    raw "KICK #{String(channel)} #{String(user)} :#{comment}"
  end
end

- (Object) kill(nickname, comment)

Sends a KILL command. The KILL command is used to cause a client-server connection to be closed by the server which has the actual connection.

Parameters:

  • nickname —

    A nickname String.

  • comment —

    A comment String (the reason for the kill).



423
424
425
 
# File 'lib/irc/rfc2812/commands.rb', line 423

def kill(nickname, comment)
  raw "KILL #{String(nickname)} :#{comment}"
end

- (Object) links(mask = nil, remote = nil)

Sends a LINKS command. The LINKS command is used to list all servernames, which are known by the server answering the query.

Parameters:

  • mask (defaults to: nil) —

    A host mask String (default: nil).

  • remote (defaults to: nil) —

    A remote server name String (default: nil).



289
290
291
292
293
294
295
 
# File 'lib/irc/rfc2812/commands.rb', line 289

def links(mask = nil, remote = nil)
  if remote.nil?
    raw "LINKS #{String(mask)}".strip
  else
    "LINKS #{remote} #{String(mask)}".strip
  end
end

- (Object) list(channels = nil, target = nil)

Sends a LIST command. Lists channels and their topics.

Examples:

list # => requests to list all channels
list ['#ruby', '#rails'] # requests to list channels #ruby and #rails

Parameters:

  • channels (defaults to: nil) —

    The channel name String or an Array of channel name Strings (default: nil).

  • target (defaults to: nil) —

    The target (server name) String (default: nil).



202
203
204
205
206
 
# File 'lib/irc/rfc2812/commands.rb', line 202

def list(channels = nil, target = nil)
  channels = Array(channels).map { |chan| String(chan) }.join ','

  raw "LIST #{channels} #{target}".strip
end

- (Object) lusers(mask = nil, target = nil)

Sends a LUSERS command. The LUSERS command is used to get statistics about the size of the IRC network.

Parameters:

  • mask (defaults to: nil) —

    A mask String (default: nil).

  • target (defaults to: nil) —

    A target String (default: nil).



263
264
265
 
# File 'lib/irc/rfc2812/commands.rb', line 263

def lusers(mask = nil, target = nil)
  raw "LUSERS #{String(mask)} #{target}".strip
end

- (Object) mode(target, modes = [], parameters = [])

Sends a MODE command. This either requests the modes (when the modes parameter is empty) or changes the modes (when it’s not).

Examples:

# User modes messages:
mode 'nickname'
mode 'nickname', [:a, -:i] # -:i translates to :"-i"
# Channel mode messages:
mode '#channel'
mode '#channel', :b, '*!*@*'
mode '#channel', [+:b, :i, :m], '*!*@*'

Parameters:

  • target —

    The channel name String or nickname String.

  • modes (defaults to: []) —

    A mode Symbol or an Array of mode Symbols (default: []).

  • options —

    A parameter String or an Array or parameter Strings (default: []).



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/irc/rfc2812/commands.rb', line 77

def mode(target, modes = [], parameters = [])
  if modes.size > 3
    (modes.size / 3 + 1).times.map do
      mode target, modes.shift(3), parameters.shift(3)
    end
  else
    parameters = Array(parameters)
    modes      = Array(modes).map! { |m| m.to_s.start_with?('-') ? m : +m }
    groups     = modes.group_by { |m| m[0] }
    pos, neg   = Array(groups['+']), Array(groups['-'])

    mode_string = String.new
    mode_string << "+#{pos.map { |m| m[1] }.join}" unless pos.empty?
    mode_string << "-#{neg.map { |m| m[1] }.join}" unless neg.empty?

    raw "MODE #{String(target)} #{mode_string} #{parameters.join ' '}".strip
  end
end

- (Object) motd(target = nil)

Sends a MOTD command. The MOTD command is used to get the “Message Of The Day” of a server.

Parameters:

  • target (defaults to: nil) —

    A server name String (default: nil).



254
255
256
 
# File 'lib/irc/rfc2812/commands.rb', line 254

def motd(target = nil)
  raw "MOTD #{target}".strip
end

- (Object) names(channels = nil, target = nil)

Sends a NAMES command. Requests all nicknames that are visible on any channel that isn’t private (+p) or secret (+s), unless they’re joined.

Examples:

names # => requests a list of all visible channels and users
names '#ruby' # => requests a list off all visible users on #ruby

Parameters:

  • channels (defaults to: nil) —

    The channel name String or an Array of channel name Strings (default: nil)

  • target (defaults to: nil) —

    The target (server name) String (default: nil).

Returns:

  • an Array of IRC::Messages or nil.



186
187
188
189
190
 
# File 'lib/irc/rfc2812/commands.rb', line 186

def names(channels = nil, target = nil)
  channels = Array(channels).map { |chan| String(chan) }.join ','

  raw "NAMES #{channels} #{target}".strip
end

- (Object) nick(nickname)

Sends a NICK command. The NICK command is used to give a user a nickname or change the current one.

Parameters:

  • nickname —

    The desired nickname String.



36
37
38
 
# File 'lib/irc/rfc2812/commands.rb', line 36

def nick(nickname)
  raw "NICK #{String(nickname)}"
end

- (Object) notice(receiver, message)

Sends a NOTICE command.

Parameters:

  • receiver —

    The nickname, channel name, host mask or server mask String.

  • message —

    The message String.



244
245
246
 
# File 'lib/irc/rfc2812/commands.rb', line 244

def notice(receiver, message)
  raw "NOTICE #{String(receiver)} :#{message}"
end

- (Object) oper(user, password)

Sends an OPER command. The OPER command is used by a normal user to obtain operator privileges.

Parameters:

  • user —

    The username String.

  • password —

    The password String.



55
56
57
 
# File 'lib/irc/rfc2812/commands.rb', line 55

def oper(user, password)
  raw "OPER #{user} #{password}"
end

- (Object) part(channels, message = nil)

Sends a PART command (leaves a channel).

Parameters:

  • channels —

    The channel name String or an Array of channel name Strings.

  • message (defaults to: nil) —

    A part message String (default: nil).



151
152
153
154
155
 
# File 'lib/irc/rfc2812/commands.rb', line 151

def part(channels, message = nil)
  channels = Array(channels).map { |chan| String(chan) }.join ','

  raw "PART #{channels} :#{message}"
end

- (Object) pass(password)

Sends a PASS command. The PASS command is used to set a ‘connection password’.

Parameters:

  • password —

    The server password String.



28
29
30
 
# File 'lib/irc/rfc2812/commands.rb', line 28

def pass(password)
  raw "PASS #{password}"
end

- (Object) ping(server, forward = nil)

Sends a PING command.

Parameters:

  • server —

    The name String of the server.

  • forward (defaults to: nil) —

    The name String of the server the PING message should be forwarded to (default: nil).



432
433
434
 
# File 'lib/irc/rfc2812/commands.rb', line 432

def ping(server, forward = nil)
  raw "PING #{server} #{forward}".strip
end

- (Object) pong(server, forward = nil)

Sends a PONG command. The PONG command is a reply to a PING command.

Parameters:

  • deamon —

    The name String of the server.

  • deamon2 —

    The name String of the server the PONG message should be forwarded to (default: nil).



442
443
444
 
# File 'lib/irc/rfc2812/commands.rb', line 442

def pong(server, forward = nil)
  raw "PONG #{server} #{forward}".strip
end

- (Object) privmsg(receiver, message)

Sends a PRIVMSG command. The PRIVMSG command is used to send private messages between users, as well as to send messages to channels.

Parameters:

  • receiver —

    The nickname, channel name, host mask, server mask String.

  • message —

    The message String.



236
237
238
 
# File 'lib/irc/rfc2812/commands.rb', line 236

def privmsg(receiver, message)
  raw "PRIVMSG #{String(receiver)} :#{message}"
end

- (Object) quit(message = nil)

Sends a QUIT command.

Parameters:

  • message (defaults to: nil) —

    The quit message String (default: nil).



109
110
111
 
# File 'lib/irc/rfc2812/commands.rb', line 109

def quit(message = nil)
  raw message.nil? ? "QUIT" : "QUIT :#{message}"
end

- (Object) raw(*args)

Raises:

  • (NotImplementedError) 


529
530
531
 
# File 'lib/irc/rfc2812/commands.rb', line 529

def raw(*args)
  raise NotImplementedError, "#{self.class}#raw not defined."
end

- (Object) rehash

Sends a REHASH command. The REHASH command is an administrative command which can be used by an operator to force the server to re-read and process its configuration file.



468
469
470
 
# File 'lib/irc/rfc2812/commands.rb', line 468

def rehash
  raw 'REHASH'
end

- (Object) restart

Sends a RESTART command. An operator can use the RESTART command to force the server to restart itself.



480
481
482
 
# File 'lib/irc/rfc2812/commands.rb', line 480

def restart
  raw 'RESTART'
end

- (Object) service(nickname, info, distribution = '*')

Sends a SERVICE command. The SERVICE command is used to register a new service.

Parameters:

  • nickname —

    A nickname String.

  • info —

    An info String.

  • distribution (defaults to: '*') —

    A String servers have to match against.



102
103
104
 
# File 'lib/irc/rfc2812/commands.rb', line 102

def service(nickname, info, distribution = '*')
  raw "SERVICE #{String(nickname)} * #{distribution} 0 0 :#{info}"
end

- (Object) servlist(mask = nil, type = nil)

Pubic: Sends a SERVLIST command. The SERVLIST command is used to list services currently connected to the network and visible to the user issuing the command.

Parameters:

  • mask (defaults to: nil) —

    A mask String (default: nil).

  • target —

    A type String (default: nil).



350
351
352
 
# File 'lib/irc/rfc2812/commands.rb', line 350

def servlist(mask = nil, type = nil)
  raw "SERVLIST #{String(mask)} #{type}".strip
end

- (Object) squery(servicename, text)

Sends a SQUERY command. The SQUERY command is used similarly to PRIVMSG. The only difference is that the recipient MUST be a service.

Parameters:

  • servicename —

    A service name String.

  • text —

    A text String.



359
360
361
 
# File 'lib/irc/rfc2812/commands.rb', line 359

def squery(servicename, text)
  raw "SQUERY #{servicename} :#{text}"
end

- (Object) squit(server, comment)

Sends a SQUIT command. The SQUIT command is used to disconnect server links (only available to IRC operators).

Parameters:

  • server —

    A server name String.

  • comment —

    A comment String.



118
119
120
 
# File 'lib/irc/rfc2812/commands.rb', line 118

def squit(server, comment)
  raw "SQUIT #{server} :#{comment}"
end

- (Object) stats(query = nil, target = nil)

Sends a STATS command. The STATS command is used to query statistics of certain server.

Parameters:

  • query (defaults to: nil) —

    A single character query Symbol (default: nil).

  • target (defaults to: nil) —

    A server name String (default: nil).



280
281
282
 
# File 'lib/irc/rfc2812/commands.rb', line 280

def stats(query = nil, target = nil)
  raw "STATS #{query} #{target}".strip
end

- (Object) summon(user, target = nil, channel = nil)

Sends a SUMMON command. The SUMMON command can be used to give users who are on a host running an IRC server a message asking them to please join IRC.

Parameters:

  • user —

    A user name String.

  • target (defaults to: nil) —

    A target (server name) String (default: nil).

  • channel (defaults to: nil) —

    A channel name String (default: nil).



491
492
493
 
# File 'lib/irc/rfc2812/commands.rb', line 491

def summon(user, target = nil, channel = nil)
  raw "SUMMON #{String(user)} #{target} #{String(channel)}".strip
end

- (Object) time(target = nil)

Sends a TIME command. The time command is used to query local time from the specified server.

Parameters:

  • target (defaults to: nil) —

    A target (server name) String (default: nil).



301
302
303
 
# File 'lib/irc/rfc2812/commands.rb', line 301

def time(target = nil)
  raw "TIME #{target}".strip
end

- (Object) topic(channel, topic = nil)

Sends a TOPIC command.

Examples:

topic '#ruby' 
topic '#ruby', 'welcome to #ruby!'

Parameters:

  • channel —

    The channel name String.

  • topic (defaults to: nil) —

    The new topic String (default: nil).



166
167
168
169
170
 
# File 'lib/irc/rfc2812/commands.rb', line 166

def topic(channel, topic = nil)
  channel = String(channel)

  raw topic.nil? ? "TOPIC #{channel}" : "TOPIC #{channel} :#{topic}"
end

- (Object) trace(target = nil)

Sends a TRACE command. The TRACE command is used to find the route to specific server and information about its peers.

Parameters:

  • target (defaults to: nil) —

    A target (server name) String (default: nil).



320
321
322
 
# File 'lib/irc/rfc2812/commands.rb', line 320

def trace(target = nil)
  raw "TRACE #{target}".strip
end

- (Object) user(username, realname, invisible = true)

Sends a USER command. The USER command is used at the beginning of connection to specify the username, hostname and realname of a new user.

Parameters:

  • username —

    The username String.

  • realname —

    The real name String.

  • invisible (defaults to: true) —

    A Boolean that asks for the user mode 'i' (default: true).



46
47
48
 
# File 'lib/irc/rfc2812/commands.rb', line 46

def user(username, realname, invisible = true)
  raw "USER #{username} #{invisible ? 8 : 0} * :#{realname}"
end

- (Object) userhost(nicknames)

Sends an USERHOST command. The USERHOST command requests a list of information about each nickname that it found.

Parameters:

  • nicknames —

    A nickname String or an Array of such Strings (max. 5).



517
518
519
 
# File 'lib/irc/rfc2812/commands.rb', line 517

def userhost(nicknames)
  raw "USERHOST #{Array(nicknames).map { |nick| String(nick) }.join ' '}"
end

- (Object) users(target = nil)

Sends a USERS command. The USERS command returns a list of users logged into the server in a format similar to the UNIX commands who(1), rusers(1) and finger(1).

Parameters:

  • target (defaults to: nil) —

    A target (server name) String (default: nil).



500
501
502
 
# File 'lib/irc/rfc2812/commands.rb', line 500

def users(target = nil)
  raw "USERS #{target}".strip
end

- (Object) version(target = nil)

Sends a VERSION command. The VERSION command is used to query the version of the server program.

Parameters:

  • target (defaults to: nil) —

    A server name String (default: nil).



271
272
273
 
# File 'lib/irc/rfc2812/commands.rb', line 271

def version(target = nil)
  raw "VERSION #{target}".strip
end

- (Object) wallops(text)

Sends a WALLOPS command. The WALLOPS command is used to send a message to all currently connected users who have set the ‘w’ user mode for themselves.

Parameters:

  • text —

    A text String.



509
510
511
 
# File 'lib/irc/rfc2812/commands.rb', line 509

def wallops(text)
  raw "WALLOPS :#{text}"
end

- (Object) who(name = nil, operators_only = false)

Sends a WHO command. The WHO command is used by a client to generate a query which returns a list of information which ‘matches’ the <mask> parameter given by the client.

Examples:

who
who '*.fi'
who '*.fi', true

Parameters:

  • name (defaults to: nil) —

    The nickname, channel name, host mask, server mask String or an Array of such Strings.

  • operaters_only —

    A Boolean (default: false).



378
379
380
 
# File 'lib/irc/rfc2812/commands.rb', line 378

def who(name = nil, operators_only = false)
  raw "WHO #{String(name)} #{"o" if operators_only}".strip
end

- (Object) whois(masks, server = nil)

Sends a WHOIS command. The WHOIS command is used to query information about particular user.

Examples:

whois 'Alfredo'
whois 'Alfredo', 'gibson.freenode.net'

Parameters:

  • nickmask —

    The nickname String.

  • server (defaults to: nil) —

    A servername String (default: nil).



392
393
394
395
396
 
# File 'lib/irc/rfc2812/commands.rb', line 392

def whois(masks, server = nil)
  masks = Array(masks).map { |mask| String(mask) }.join ','

  raw server.nil? ? "WHOIS #{masks}" : "WHOIS #{server} #{masks}"
end

- (Object) whowas(nicknames, count = nil, target = nil)

Sends a WHOWAS command. The WHOWAS command requests information about a nickname which no longer exists.

Examples:

whowas 'Alfredo', 8
whowas ['Alfredo', 'Angel'], 2

Parameters:

  • nicknames —

    The nickname String or an Array of nickname Strings.

  • count (defaults to: nil) —

    The maximum amount of entries as Integer (default: nil).

  • target (defaults to: nil) —

    The server String (default: nil).



409
410
411
412
413
 
# File 'lib/irc/rfc2812/commands.rb', line 409

def whowas(nicknames, count = nil, target = nil)
  nicknames = Array(nicknames).map { |mask| String(mask) }.join ','

  raw "WHOWAS #{nicknames} #{count} #{target}".strip
end