Class: Cinch::Channel

Inherits:
Target
  • Object
show all
Includes:
Helpers, Syncable
Defined in:
lib/cinch/channel.rb

Overview

Version:

  • 2.0.0

Instance Attribute Summary collapse

Attributes inherited from Target

#bot, #name

Checks collapse

User groups collapse

Channel Manipulation collapse

Instance Method Summary collapse

Methods included from Helpers

#Channel, #Color, #Format, #Sanitize, #Target, #Timer, #Unformat, #User, #debug, #error, #exception, #fatal, #incoming, #info, #log, #outgoing, #rescue_exception, sanitize, #warn

Methods included from Syncable

#attr, #attribute_synced?, #mark_as_synced, #sync, #unsync, #unsync_all, #wait_until_synced

Methods inherited from Target

#<=>, #action, #concretize, #ctcp, #eql?, #notice, #safe_action, #safe_msg, #safe_notice, #safe_privmsg, #safe_send

Constructor Details

#initialize(name, bot) ⇒ Channel

Note:

Generally, you shouldn’t initialize new instances of this class. Use Cinch::ChannelList#find_ensured instead.

Returns a new instance of Channel.



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
 
# File 'lib/cinch/channel.rb', line 49

def initialize(name, bot)
  @bot = bot
  @name = name
  @users = Hash.new { |h, k| h[k] = [] }
  @bans = []
  @owners = []

  @modes = {}
  # TODO raise if not a channel

  @topic = nil

  @in_channel = false

  @synced_attributes = Set.new
  @when_requesting_synced_attribute = lambda { |attr|
    if @in_channel && attr == :topic && !attribute_synced?(:topic)
      # Even if we are in the channel, if there's no topic set,
      # the attribute won't be synchronised yet. Explicitly
      # request the topic.
      @bot.irc.send "TOPIC #{@name}"
      next
    end

    unless @in_channel
      unsync(attr)
      case attr
      when :users
        @bot.irc.send "NAMES #{@name}"
      when :topic
        @bot.irc.send "TOPIC #{@name}"
      when :bans
        @bot.irc.send "MODE #{@name} +b"
      when :owners
        if @bot.irc.network.owner_list_mode
          @bot.irc.send "MODE #{@name} +#{@bot.irc.network.owner_list_mode}"
        else
          # the current IRCd does not support channel owners, so
          # just mark the empty array as synced
          mark_as_synced(:owners)
        end
      when :modes
        @bot.irc.send "MODE #{@name}"
      end
    end
  }
end

Instance Attribute Details

#bans ⇒ Array<Ban> (readonly)

Returns all active bans.

Returns:

  • all active bans



30
31
32
 
# File 'lib/cinch/channel.rb', line 30

def bans
  @bans
end

#invite_only ⇒ Boolean Also known as: invite_only?

Returns true if the channel is invite only (+i).

Returns:

  • true if the channel is invite only (+i)



13
14
15
 
# File 'lib/cinch/channel.rb', line 13

def invite_only
  @invite_only
end

#key ⇒ String?

Returns The channel’s key (aka password).

Returns:

  • The channel’s key (aka password)



13
14
15
 
# File 'lib/cinch/channel.rb', line 13

def key
  @key
end

#limit ⇒ Integer

Returns The maximum number of allowed users in the channel. 0 if unlimited.

Returns:

  • The maximum number of allowed users in the channel. 0 if unlimited.



13
14
15
 
# File 'lib/cinch/channel.rb', line 13

def limit
  @limit
end

#moderated ⇒ Boolean Also known as: moderated?

Returns true if the channel is moderated.

Returns:

  • true if the channel is moderated



13
14
15
 
# File 'lib/cinch/channel.rb', line 13

def moderated
  @moderated
end

#modes ⇒ Hash{String => Object} (readonly)

This attribute describes all modes set in the channel. They’re represented as a Hash, mapping the mode (e.g. “i”, “k”, …) to either a value in the case of modes that take an option (e.g. “k” for the channel key) or true.

Returns:



44
45
46
 
# File 'lib/cinch/channel.rb', line 44

def modes
  @modes
end

#owners ⇒ Array<User> (readonly)

Note:

Only some networks implement this

Returns all channel owners.

Returns:

  • all channel owners



35
36
37
 
# File 'lib/cinch/channel.rb', line 35

def owners
  @owners
end

#secret ⇒ Boolean Also known as: secret?

Returns true if the channel is secret (+s).

Returns:

  • true if the channel is secret (+s)



13
14
15
 
# File 'lib/cinch/channel.rb', line 13

def secret
  @secret
end

#topic ⇒ String

Returns the channel’s topic.

Returns:

  • the channel’s topic



26
27
28
 
# File 'lib/cinch/channel.rb', line 26

def topic
  @topic
end

#users ⇒ Hash{User => Array<String}> (readonly)

Users are represented by a Hash, mapping individual users to an array of modes (e.g. “o” for opped).

Returns:

  • all users in the channel

Version:

  • 1.1.0



22
23
24
 
# File 'lib/cinch/channel.rb', line 22

def users
  @users
end

Instance Method Details

#add_user(user, modes = []) ⇒ User

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns The added user.

Returns:

  • The added user

API:

  • private



387
388
389
390
391
 
# File 'lib/cinch/channel.rb', line 387

def add_user(user, modes = [])
  @in_channel = true if user == @bot
  @users[user] = modes
  user
end

#admins ⇒ Array<User>

Returns All admins in the channel.

Returns:

  • All admins in the channel

Since:

  • 2.0.0



148
149
150
 
# File 'lib/cinch/channel.rb', line 148

def admins
  @users.select { |user, modes| modes.include?("a") }.keys
end

#ban(target) ⇒ Mask

Bans someone from the channel.

Parameters:

  • the mask, or an object having a mask, to ban

Returns:

  • the mask used for banning

See Also:



251
252
253
254
255
256
 
# File 'lib/cinch/channel.rb', line 251

def ban(target)
  mask = Mask.from(target)

  @bot.irc.send "MODE #{@name} +b #{mask}"
  mask
end

#clear_users ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Removes all users

API:

  • private



404
405
406
 
# File 'lib/cinch/channel.rb', line 404

def clear_users
  @users.clear
end

#deop(user) ⇒ void

This method returns an undefined value.

Deops a user.

Parameters:

  • the user to deop



282
283
284
 
# File 'lib/cinch/channel.rb', line 282

def deop(user)
  @bot.irc.send "MODE #{@name} -o #{user}"
end

#devoice(user) ⇒ void

This method returns an undefined value.

Devoices a user.

Parameters:

  • the user to devoice



298
299
300
 
# File 'lib/cinch/channel.rb', line 298

def devoice(user)
  @bot.irc.send "MODE #{@name} -v #{user}"
end

#half_opped?(user) ⇒ Boolean

Returns true if ‘user` is half-opped in the channel.

Returns:

  • true if ‘user` is half-opped in the channel

Since:

  • 1.1.0



115
116
117
 
# File 'lib/cinch/channel.rb', line 115

def half_opped?(user)
  @users[User(user)].include? "h"
end

#half_ops ⇒ Array<User>

Returns All half-ops in the channel.

Returns:

  • All half-ops in the channel

Since:

  • 2.0.0



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

def half_ops
  @users.select { |user, modes| modes.include?("h") }.keys
end

#has_user?(user) ⇒ Boolean

Returns Check if a user is in the channel.

Parameters:

Returns:

  • Check if a user is in the channel

Since:

  • 1.1.0

Version:

  • 1.1.2



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

def has_user?(user)
  @users.has_key?(User(user))
end

#hash ⇒ Fixnum

Returns:



434
435
436
 
# File 'lib/cinch/channel.rb', line 434

def hash
  @name.hash
end

#inspect ⇒ String

Returns:



452
453
454
 
# File 'lib/cinch/channel.rb', line 452

def inspect
  "#<Channel name=#{@name.inspect}>"
end

#invite(user) ⇒ void

This method returns an undefined value.

Invites a user to the channel.

Parameters:

  • the user to invite



306
307
308
 
# File 'lib/cinch/channel.rb', line 306

def invite(user)
  @bot.irc.send("INVITE #{user} #{@name}")
end

#join(key = nil) ⇒ void

This method returns an undefined value.

Joins the channel

Parameters:

  • (defaults to: nil)

    the channel key, if any. If none is specified but @key is set, @key will be used



376
377
378
379
380
381
 
# File 'lib/cinch/channel.rb', line 376

def join(key = nil)
  if key.nil? && self.key != true
    key = self.key
  end
  @bot.irc.send "JOIN #{[@name, key].compact.join(" ")}"
end

#kick(user, reason = nil) ⇒ void

This method returns an undefined value.

Kicks a user from the channel.

Parameters:

  • the user to kick

  • (defaults to: nil)

    a reason for the kick

Raises:



329
330
331
332
333
334
335
 
# File 'lib/cinch/channel.rb', line 329

def kick(user, reason = nil)
  if reason.to_s.size > @bot.irc.isupport["KICKLEN"] && @bot.strict?
    raise Exceptions::KickReasonTooLong, reason
  end

  @bot.irc.send("KICK #{@name} #{user} :#{reason}")
end

#mode(s) ⇒ void

This method returns an undefined value.

Sets or unsets modes. Most of the time you won’t need this but use setter methods like #invite_only=.

Examples:

channel.mode "+n"

Parameters:

  • a mode string



359
360
361
 
# File 'lib/cinch/channel.rb', line 359

def mode(s)
  @bot.irc.send "MODE #{@name} #{s}"
end

#msg(*args) ⇒ Object

Deprecated. 


422
423
424
425
 
# File 'lib/cinch/channel.rb', line 422

def msg(*args)
  Cinch::Utilities::Deprecation.print_deprecation("2.2.0", "Channel#msg", "Channel#send")
  send(*args)
end

#op(user) ⇒ void

This method returns an undefined value.

Ops a user.

Parameters:

  • the user to op



274
275
276
 
# File 'lib/cinch/channel.rb', line 274

def op(user)
  @bot.irc.send "MODE #{@name} +o #{user}"
end

#opped?(user) ⇒ Boolean

Returns true if ‘user` is opped in the channel.

Returns:

  • true if ‘user` is opped in the channel

Since:

  • 1.1.0



109
110
111
 
# File 'lib/cinch/channel.rb', line 109

def opped?(user)
  @users[User(user)].include? "o"
end

#ops ⇒ Array<User>

Returns All ops in the channel.

Returns:

  • All ops in the channel

Since:

  • 2.0.0



130
131
132
 
# File 'lib/cinch/channel.rb', line 130

def ops
  @users.select { |user, modes| modes.include?("o") }.keys
end

#part(message = nil) ⇒ void

This method returns an undefined value.

Causes the bot to part from the channel.

Parameters:

  • (defaults to: nil)

    the part message.



367
368
369
 
# File 'lib/cinch/channel.rb', line 367

def part(message = nil)
  @bot.irc.send "PART #{@name} :#{message}"
end

#privmsg(*args) ⇒ Object

Deprecated. 


428
429
430
431
 
# File 'lib/cinch/channel.rb', line 428

def privmsg(*args)
  Cinch::Utilities::Deprecation.print_deprecation("2.2.0", "Channel#privmsg", "Channel#send")
  send(*args)
end

#remove(user, reason = nil) ⇒ void

This method returns an undefined value.

Removes a user from the channel.

This uses the REMOVE command, which is a non-standardized extension. Unlike a kick, it makes a user part. This prevents auto-rejoin scripts from firing and might also be perceived as less aggressive by some. Not all IRC networks support this command.

Parameters:

  • the user to remove

  • (defaults to: nil)

    a reason for the removal



348
349
350
 
# File 'lib/cinch/channel.rb', line 348

def remove(user, reason = nil)
  @bot.irc.send("REMOVE #{@name} #{user} :#{reason}")
end

#remove_user(user) ⇒ User?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns The removed user.

Returns:

  • The removed user

API:

  • private



395
396
397
398
 
# File 'lib/cinch/channel.rb', line 395

def remove_user(user)
  @in_channel = false if user == @bot
  @users.delete(user)
end

#send(text, notice = false) ⇒ Object

Note:

The aliases ‘msg` and `privmsg` are deprecated and will be removed in a future version.



410
411
412
413
414
415
416
417
418
419
 
# File 'lib/cinch/channel.rb', line 410

def send(text, notice = false)
  # TODO deprecate 'notice' argument
  text = text.to_s
  if @modes["c"]
    # Remove all formatting and colors if the channel doesn't
    # allow colors.
    text = Cinch::Formatting.unformat(text)
  end
  super
end

#sync_modes ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

API:

  • private



224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/cinch/channel.rb', line 224

def sync_modes
  unsync :users
  unsync :bans
  unsync :modes
  unsync :owners

  if @bot.irc.isupport["WHOX"]
    @bot.irc.send "WHO #{@name} %acfhnru"
  else
    @bot.irc.send "WHO #{@name}"
  end
  @bot.irc.send "MODE #{@name} +b" # bans
  @bot.irc.send "MODE #{@name}"
  if @bot.irc.network.owner_list_mode
    @bot.irc.send "MODE #{@name} +#{@bot.irc.network.owner_list_mode}"
  else
    mark_as_synced :owners
  end
end

#to_s ⇒ String

Note:

The alias ‘to_str` is deprecated and will be removed in a future version. Channel objects should not be treated like strings.

Returns:



442
443
444
 
# File 'lib/cinch/channel.rb', line 442

def to_s
  @name
end

#to_str ⇒ Object 



446
447
448
449
 
# File 'lib/cinch/channel.rb', line 446

def to_str
  Cinch::Utilities::Deprecation.print_deprecation("2.2.0", "Channel#to_str", "Channel#to_s")
  to_s
end

#unban(target) ⇒ Mask

Unbans someone from the channel.

Parameters:

  • the mask to unban

Returns:

  • the mask used for unbanning

See Also:



263
264
265
266
267
268
 
# File 'lib/cinch/channel.rb', line 263

def unban(target)
  mask = Mask.from(target)

  @bot.irc.send "MODE #{@name} -b #{mask}"
  mask
end

#voice(user) ⇒ void

This method returns an undefined value.

Voices a user.

Parameters:

  • the user to voice



290
291
292
 
# File 'lib/cinch/channel.rb', line 290

def voice(user)
  @bot.irc.send "MODE #{@name} +v #{user}"
end

#voiced ⇒ Array<User>

Returns All voiced users in the channel.

Returns:

  • All voiced users in the channel

Since:

  • 2.0.0



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

def voiced
  @users.select { |user, modes| modes.include?("v") }.keys
end

#voiced?(user) ⇒ Boolean

Returns true if ‘user` is voiced in the channel.

Returns:

  • true if ‘user` is voiced in the channel

Since:

  • 1.1.0



121
122
123
 
# File 'lib/cinch/channel.rb', line 121

def voiced?(user)
  @users[User(user)].include? "v"
end