Module: IRC::RFC2812::Commands

Extended by:
Commands
Included in:
Commands
Defined in:
lib/irc/rfc2812/commands.rb

Overview

Public: 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 IRC::RFC2812::Commands

  # Some methods that set up a socket and whatnot.

  def raw(message)
    @socket.write message
  end
end

x = Connection.new
x.join "#channel"

Defined Under Namespace

Modules: Helpers

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.raw(message) ⇒ Object



544
545
546
# File 'lib/irc/rfc2812/commands.rb', line 544

def self.raw(message)
  message
end

Instance Method Details

#admin(target = nil) ⇒ Object

Public: 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.

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



344
345
346
# File 'lib/irc/rfc2812/commands.rb', line 344

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

#away(text = nil) ⇒ Object

Public: 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).

text - A message String (default: nil).



476
477
478
# File 'lib/irc/rfc2812/commands.rb', line 476

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

#connect(target, port = 6667, remote = nil) ⇒ Object

Public: 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.

target - A target (server name) String. port - A port number Integer (default: 6667). remote - A remote (server name) String (default: nil).



327
328
329
# File 'lib/irc/rfc2812/commands.rb', line 327

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

#dieObject

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



489
490
491
# File 'lib/irc/rfc2812/commands.rb', line 489

def die
  raw "DIE\r\n"
end

#error(message) ⇒ Object

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

message - A message String.



465
466
467
# File 'lib/irc/rfc2812/commands.rb', line 465

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

#info(target = nil) ⇒ Object

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

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



352
353
354
# File 'lib/irc/rfc2812/commands.rb', line 352

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

#invite(nickname, channel) ⇒ Object

Public: Sends an INVITE command.

nickname - The nickname String of the user that should be invited. channel - The channel name String.



231
232
233
# File 'lib/irc/rfc2812/commands.rb', line 231

def invite(nickname, channel)
  raw "INVITE #{nickname} #{channel}\r\n"
end

#ison(nicknames) ⇒ Object

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

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



540
541
542
# File 'lib/irc/rfc2812/commands.rb', line 540

def ison(nicknames)
  raw "ISON #{Array(nicknames).map(&:to_s).join " "}\r\n"
end

#join(channels, keys = nil) ⇒ Object

Public: 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.

channel - The channel name String or an Array of them. key - The key for the channel as a String (default: nil).

Examples

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


152
153
154
155
156
157
158
159
160
161
162
163
164
# File 'lib/irc/rfc2812/commands.rb', line 152

def join(channels, keys = nil)
  channel_slices = Array(channels).each_slice(5).to_a
  key_slices     = Array(keys).each_slice(5).to_a

  messages = channel_slices.zip(key_slices).map do |cs, ks|
    channel_list = cs.map(&:to_s).join ','
    key_list     = ks ? ks.join(" ") : ks

    "JOIN #{channel_list} #{key_list}".strip << "\r\n"
  end

  raw messages.join
end

#kick(channel, user, comment = nil) ⇒ Object

Public: Sends a KICK command.

channel - The channel name String. user - The nickname String. comment - The kick message String (default: nil).



240
241
242
243
244
245
246
# File 'lib/irc/rfc2812/commands.rb', line 240

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

#kill(nickname, comment) ⇒ Object

Public: 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.

nickname - A nickname String. comment - A comment String (the reason for the kill).



438
439
440
# File 'lib/irc/rfc2812/commands.rb', line 438

def kill(nickname, comment)
  raw "KILL #{nickname} :#{comment}\r\n"
end

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

mask - A host mask String (default: nil). remote - A remote server name String (default: nil).



308
309
310
# File 'lib/irc/rfc2812/commands.rb', line 308

def links(mask = nil, remote = nil)
  raw "LINKS #{remote}".strip << " #{mask}".rstrip << "\r\n"
end

#list(channels = nil, target = nil) ⇒ Object

Public: Sends a LIST command. Lists channels and their topics.

channels - The channel name String or an Array of channel name Strings

(default: nil).

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

Examples

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


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

def list(channels = nil, target = nil)
  channel_list = Array(channels).map(&:to_s).join ',' 
  
  raw "LIST #{channel_list} #{target}".strip << "\r\n"
end

#lusers(mask = nil, target = nil) ⇒ Object

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

mask - A mask String (default: nil). target - A target String (default: nil).



282
283
284
# File 'lib/irc/rfc2812/commands.rb', line 282

def lusers(mask = nil, target = nil)
  raw "LUSERS #{mask} #{target}".strip << "\r\n"
end

#mode(target, modes = [], parameters = []) ⇒ Object

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

target - The channel name String or nickname String. modes - A mode Symbol or an Array of mode Symbols (default: []). options - A parameter String or an Array or parameter Strings (default:

[]).

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], '*!*@*'


91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
# File 'lib/irc/rfc2812/commands.rb', line 91

def mode(target, modes = [], parameters = [])
  if modes.size > 3
    messages = (modes.size / 3 + 1).times.map do
      mode target, modes.shift(3), parameters.shift(3)
    end

    raw messages.join
  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 #{target} #{mode_string} #{parameters.join " "}".strip << "\r\n"
  end
end

#motd(target = nil) ⇒ Object

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

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



273
274
275
# File 'lib/irc/rfc2812/commands.rb', line 273

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

#names(channels = nil, target = nil) ⇒ Object

Public: 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.

channels - The channel name String or an Array of channel name Strings

(default: nil)

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

Examples

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

Returns an Array of IRC::Messages or nil.



205
206
207
208
209
# File 'lib/irc/rfc2812/commands.rb', line 205

def names(channels = nil, target = nil)
  channel_list = Array(channels).map(&:to_s).join ','
  
  raw "NAMES #{channel_list} #{target}".strip << "\r\n"
end

#nick(nickname) ⇒ Object

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

nickname - The desired nickname String.



50
51
52
# File 'lib/irc/rfc2812/commands.rb', line 50

def nick(nickname)
  raw "NICK #{nickname}\r\n"
end

#notice(receiver, message) ⇒ Object

Public: Sends a NOTICE command.

receiver - The nickname, channel name, host mask or server mask String. message - The message String.



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

def notice(receiver, message)
  raw Helpers.splitted("NOTICE #{receiver}", message.to_s)
end

#oper(user, password) ⇒ Object

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

user - The username String. password - The password String.



69
70
71
# File 'lib/irc/rfc2812/commands.rb', line 69

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

#part(channels, message = nil) ⇒ Object

Public: Sends a PART command (leaves a channel).

channels - The channel name String or an Array of channel name Strings. message - A part message String (default: nil).



170
171
172
# File 'lib/irc/rfc2812/commands.rb', line 170

def part(channels, message = nil)
  raw "PART #{Array(channels).map(&:to_s).join ','} :#{message}\r\n"
end

#pass(password) ⇒ Object

Public: Sends a PASS command. The PASS command is used to set a 'connection password'.

password - The server password String.



42
43
44
# File 'lib/irc/rfc2812/commands.rb', line 42

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

#ping(server, forward = nil) ⇒ Object

Public: Sends a PING command.

server - The name String of the server. forward - The name String of the server the PING message should be

forwarded to (default: nil).


447
448
449
# File 'lib/irc/rfc2812/commands.rb', line 447

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

#pong(server, forward = nil) ⇒ Object

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

deamon - The name String of the server. deamon2 - The name String of the server the PONG message should be

forwarded to (default: nil).


457
458
459
# File 'lib/irc/rfc2812/commands.rb', line 457

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

#privmsg(receiver, message) ⇒ Object

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

receiver - The nickname, channel name, host mask, server mask String. message - The message String.



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

def privmsg(receiver, message)
  raw Helpers.splitted("PRIVMSG #{receiver}", message.to_s)
end

#quit(message = nil) ⇒ Object

Public: Sends a QUIT command.

message - The quit message String (default: nil).



125
126
127
# File 'lib/irc/rfc2812/commands.rb', line 125

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

#rehashObject

Public: 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.



483
484
485
# File 'lib/irc/rfc2812/commands.rb', line 483

def rehash
  raw "REHASH\r\n"
end

#restartObject

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



495
496
497
# File 'lib/irc/rfc2812/commands.rb', line 495

def restart
  raw "RESTART\r\n"
end

#service(nickname, info, distribution = '*') ⇒ Object

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

nickname - A nickname String. info - An info String. distribution - A String servers have to match against.



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

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

#servlist(mask = nil, type = nil) ⇒ Object

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.

mask - A mask String (default: nil). target - A type String (default: nil).



365
366
367
# File 'lib/irc/rfc2812/commands.rb', line 365

def servlist(mask = nil, type = nil)
  raw "SERVLIST #{mask} #{type}".strip << "\r\n"
end

#squery(servicename, text) ⇒ Object

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

servicename - A service name String. text - A text String.



374
375
376
# File 'lib/irc/rfc2812/commands.rb', line 374

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

#squit(server, comment) ⇒ Object

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

server - A server name String. comment - A comment String.



134
135
136
# File 'lib/irc/rfc2812/commands.rb', line 134

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

#stats(query = nil, target = nil) ⇒ Object

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

query - A single character query Symbol (default: nil). target - A server name String (default: nil).



299
300
301
# File 'lib/irc/rfc2812/commands.rb', line 299

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

#summon(user, target = nil, channel = nil) ⇒ Object

Public: 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.

user - A user name String. target - A target (server name) String (default: nil). channel - A channel name String (default: nil).



506
507
508
# File 'lib/irc/rfc2812/commands.rb', line 506

def summon(user, target = nil, channel = nil)
  raw "SUMMON #{user} #{target} #{channel}".strip << "\r\n"
end

#time(target = nil) ⇒ Object

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

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



316
317
318
# File 'lib/irc/rfc2812/commands.rb', line 316

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

#topic(channel, topic = nil) ⇒ Object

Public: Sends a TOPIC command.

channel - The channel name String. topic - The new topic String (default: nil).

Examples

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


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

def topic(channel, topic = nil)
  if topic.nil?
    raw "TOPIC #{channel}\r\n"
  else
    raw "TOPIC #{channel} :#{topic}\r\n"
  end
end

#trace(target = nil) ⇒ Object

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

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



335
336
337
# File 'lib/irc/rfc2812/commands.rb', line 335

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

#user(username, realname, invisible = true) ⇒ Object

Public: 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.

username - The username String. realname - The real name String. invisible - A Boolean that asks for the user mode 'i' (default: true).



60
61
62
# File 'lib/irc/rfc2812/commands.rb', line 60

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

#userhost(nicknames) ⇒ Object

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

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



532
533
534
# File 'lib/irc/rfc2812/commands.rb', line 532

def userhost(nicknames)
  raw "USERHOST #{Array(nicknames).map(&:to_s).join " "}\r\n"
end

#users(target = nil) ⇒ Object

Public: 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).

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



515
516
517
# File 'lib/irc/rfc2812/commands.rb', line 515

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

#version(target = nil) ⇒ Object

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

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



290
291
292
# File 'lib/irc/rfc2812/commands.rb', line 290

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

#wallops(text) ⇒ Object

Public: 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.

text - A text String.



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

def wallops(text)
  raw Helpers.splitted("WALLOPS", text)
end

#who(name = nil, operators_only = false) ⇒ Object

Public: 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.

name - The nickname, channel name, host mask, server mask

String or an Array of such Strings.

operaters_only - A Boolean (default: false).

Examples

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


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

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

#whois(masks, server = nil) ⇒ Object

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

nickmask - The nickname String. server - A servername String (default: nil).

Examples

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


407
408
409
410
411
# File 'lib/irc/rfc2812/commands.rb', line 407

def whois(masks, server = nil)
  masks = Array(masks).map(&:to_s).join ','

  raw "WHOIS #{server}".strip << " #{masks}\r\n"
end

#whowas(nicknames, count = nil, target = nil) ⇒ Object

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

nicknames - The nickname String or an Array of nickname Strings. count - The maximum amount of entries as Integer (default: nil). target - The server String (default: nil).

Examples

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


424
425
426
427
428
# File 'lib/irc/rfc2812/commands.rb', line 424

def whowas(nicknames, count = nil, target = nil)
  nicknames = Array(nicknames).map(&:to_s).join ','

  raw "WHOWAS #{nicknames} #{count} #{target}".strip << "\r\n"
end