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, #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_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.



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

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:

  • (Array<Ban>) —

    all active bans



32
33
34
 
# File 'lib/cinch/channel.rb', line 32

def bans
  @bans
end

#invite_only ⇒ Boolean Also known as: invite_only?

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

Returns:

  • (Boolean) —

    true if the channel is invite only (+i)



15
16
17
 
# File 'lib/cinch/channel.rb', line 15

def invite_only
  @invite_only
end

#key ⇒ String?

Returns The channel’s key (aka password).

Returns:

  • (String, nil) —

    The channel’s key (aka password)



15
16
17
 
# File 'lib/cinch/channel.rb', line 15

def key
  @key
end

#limit ⇒ Integer

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

Returns:

  • (Integer) —

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



15
16
17
 
# File 'lib/cinch/channel.rb', line 15

def limit
  @limit
end

#moderated ⇒ Boolean Also known as: moderated?

Returns true if the channel is moderated.

Returns:

  • (Boolean) —

    true if the channel is moderated



15
16
17
 
# File 'lib/cinch/channel.rb', line 15

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:



46
47
48
 
# File 'lib/cinch/channel.rb', line 46

def modes
  @modes
end

#owners ⇒ Array<User> (readonly)

Note:

Only some networks implement this

Returns all channel owners.

Returns:

  • (Array<User>) —

    all channel owners



37
38
39
 
# File 'lib/cinch/channel.rb', line 37

def owners
  @owners
end

#secret ⇒ Boolean Also known as: secret?

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

Returns:

  • (Boolean) —

    true if the channel is secret (+s)



15
16
17
 
# File 'lib/cinch/channel.rb', line 15

def secret
  @secret
end

#topic ⇒ String

Returns the channel’s topic.

Returns:

  • (String) —

    the channel’s topic



28
29
30
 
# File 'lib/cinch/channel.rb', line 28

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:

  • (Hash{User => Array<String}>) —

    all users in the channel

Version:

  • 1.1.0



24
25
26
 
# File 'lib/cinch/channel.rb', line 24

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:

  • (User) —

    The added user



390
391
392
393
394
 
# File 'lib/cinch/channel.rb', line 390

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:

  • (Array<User>) —

    All admins in the channel

Since:

  • 2.0.0



150
151
152
 
# File 'lib/cinch/channel.rb', line 150

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

#ban(target) ⇒ Mask

Bans someone from the channel.

Parameters:

  • target (Mask, String, #mask) —

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

Returns:

  • (Mask) —

    the mask used for banning

See Also:



253
254
255
256
257
258
 
# File 'lib/cinch/channel.rb', line 253

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



407
408
409
 
# File 'lib/cinch/channel.rb', line 407

def clear_users
  @users.clear
end

#deop(user) ⇒ void

This method returns an undefined value.

Deops a user.

Parameters:



284
285
286
 
# File 'lib/cinch/channel.rb', line 284

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

#devoice(user) ⇒ void

This method returns an undefined value.

Devoices a user.

Parameters:



300
301
302
 
# File 'lib/cinch/channel.rb', line 300

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:

  • (Boolean) —

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

Since:

  • 1.1.0



117
118
119
 
# File 'lib/cinch/channel.rb', line 117

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

#half_ops ⇒ Array<User>

Returns All half-ops in the channel.

Returns:

  • (Array<User>) —

    All half-ops in the channel

Since:

  • 2.0.0



138
139
140
 
# File 'lib/cinch/channel.rb', line 138

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:

  • (Boolean) —

    Check if a user is in the channel

Since:

  • 1.1.0

Version:

  • 1.1.2



105
106
107
 
# File 'lib/cinch/channel.rb', line 105

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

#hash ⇒ Fixnum

Returns:

  • (Fixnum) 


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

def hash
  @name.hash
end

#inspect ⇒ String

Returns:



461
462
463
 
# File 'lib/cinch/channel.rb', line 461

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

#invite(user) ⇒ void

This method returns an undefined value.

Invites a user to the channel.

Parameters:



308
309
310
 
# File 'lib/cinch/channel.rb', line 308

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

#join(key = nil) ⇒ void

This method returns an undefined value.

Joins the channel

Parameters:

  • key (String) (defaults to: nil) —

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



379
380
381
382
383
384
 
# File 'lib/cinch/channel.rb', line 379

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:

  • user (String, User) —

    the user to kick

  • reason (String) (defaults to: nil) —

    a reason for the kick

Raises:



332
333
334
335
336
337
338
 
# File 'lib/cinch/channel.rb', line 332

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:

  • s (String) —

    a mode string



362
363
364
 
# File 'lib/cinch/channel.rb', line 362

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

#op(user) ⇒ void

This method returns an undefined value.

Ops a user.

Parameters:



276
277
278
 
# File 'lib/cinch/channel.rb', line 276

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

#opped?(user) ⇒ Boolean

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

Returns:

  • (Boolean) —

    true if ‘user` is opped in the channel

Since:

  • 1.1.0



111
112
113
 
# File 'lib/cinch/channel.rb', line 111

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

#ops ⇒ Array<User>

Returns All ops in the channel.

Returns:

  • (Array<User>) —

    All ops in the channel

Since:

  • 2.0.0



132
133
134
 
# File 'lib/cinch/channel.rb', line 132

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:

  • message (String) (defaults to: nil) —

    the part message.



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

def part(message = nil)
  @bot.irc.send "PART #{@name} :#{message}"
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:

  • user (User) —

    the user to remove

  • reason (String) (defaults to: nil) —

    a reason for the removal



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

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:

  • (User, nil) —

    The removed user



398
399
400
401
 
# File 'lib/cinch/channel.rb', line 398

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

#send(text, notice = false) ⇒ Object Also known as: msg, privmsg

Note:

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



413
414
415
416
417
418
419
420
421
422
 
# File 'lib/cinch/channel.rb', line 413

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(text, notice)
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.



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

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 Also known as: to_str

Note:

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

Returns:



449
450
451
 
# File 'lib/cinch/channel.rb', line 449

def to_s
  @name
end

#unban(target) ⇒ Mask

Unbans someone from the channel.

Parameters:

  • target (Mask, String, #mask) —

    the mask to unban

Returns:

  • (Mask) —

    the mask used for unbanning

See Also:



265
266
267
268
269
270
 
# File 'lib/cinch/channel.rb', line 265

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:



292
293
294
 
# File 'lib/cinch/channel.rb', line 292

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

#voiced ⇒ Array<User>

Returns All voiced users in the channel.

Returns:

  • (Array<User>) —

    All voiced users in the channel

Since:

  • 2.0.0



144
145
146
 
# File 'lib/cinch/channel.rb', line 144

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

#voiced?(user) ⇒ Boolean

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

Returns:

  • (Boolean) —

    true if ‘user` is voiced in the channel

Since:

  • 1.1.0



123
124
125
 
# File 'lib/cinch/channel.rb', line 123

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