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.



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:

  • (Array<Ban>) —

    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:

  • (Boolean) —

    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:

  • (String, nil) —

    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:

  • (Integer) —

    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:

  • (Boolean) —

    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:

  • (Array<User>) —

    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:

  • (Boolean) —

    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:

  • (String) —

    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:

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

    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:

  • (User) —

    The added user



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

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



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:

  • target (Mask, String, #mask) —

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

Returns:

  • (Mask) —

    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

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



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

def clear_users
  @users.clear
end

#deop(user)

This method returns an undefined value.

Deops a user.

Parameters:



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

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

#devoice(user)

This method returns an undefined value.

Devoices a user.

Parameters:



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:

  • (Boolean) —

    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:

  • (Array<User>) —

    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:

  • (Boolean) —

    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:

  • (Fixnum) 


439
440
441
 
# File 'lib/cinch/channel.rb', line 439

def hash
  @name.hash
end

#inspect ⇒ String

Returns:



459
460
461
 
# File 'lib/cinch/channel.rb', line 459

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

#invite(user)

This method returns an undefined value.

Invites a user to the channel.

Parameters:



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

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

#join(key = nil)

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



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

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

#kick(user, reason = nil)

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:



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

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)

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



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

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

#op(user)

This method returns an undefined value.

Ops a user.

Parameters:



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:

  • (Boolean) —

    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:

  • (Array<User>) —

    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)

This method returns an undefined value.

Causes the bot to part from the channel.

Parameters:

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

    the part message.



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

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

#remove(user, reason = nil)

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



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

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



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

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.



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

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

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.



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



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

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:



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)

This method returns an undefined value.

Voices a user.

Parameters:



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:

  • (Array<User>) —

    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:

  • (Boolean) —

    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