class Cinch::Channel
@attr limit @attr secret @attr moderated @attr invite_only
@attr key
@version 2.0.0
Attributes
@return [Array<Ban>] all active bans
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.
@return [Hash{String => Object}]
@return [Array<User>] all channel owners @note Only some networks implement this
@return [String] the channel's topic
Users are represented by a Hash, mapping individual users to an array of modes (e.g. “o” for opped).
@return [Hash{User => Array<String}>] all users in the channel @version 1.1.0
Public Class Methods
@note Generally, you shouldn't initialize new instances of this
class. Use {ChannelList#find_ensured} instead.
# File lib/cinch/channel.rb, line 50 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
Public Instance Methods
@api private @return [User] The added user
# File lib/cinch/channel.rb, line 387 def add_user(user, modes = []) @in_channel = true if user == @bot @users[user] = modes user end
@return [Array<User>] All admins in the channel @since 2.0.0
# File lib/cinch/channel.rb, line 149 def admins @users.select { |_user, modes| modes.include?("a") }.keys end
Bans someone from the channel.
@param [Mask, String
, mask] target the mask, or an object having a mask, to ban @return [Mask] the mask used for banning @see unban
unban
for unbanning users
# File lib/cinch/channel.rb, line 252 def ban(target) mask = Mask.from(target) @bot.irc.send "MODE #{@name} +b #{mask}" mask end
Removes all users
@api private @return [void]
# File lib/cinch/channel.rb, line 404 def clear_users @users.clear end
Deops a user.
@param [String, User] user the user to deop @return [void]
# File lib/cinch/channel.rb, line 283 def deop(user) @bot.irc.send "MODE #{@name} -o #{user}" end
Devoices a user.
@param [String, User] user the user to devoice @return [void]
# File lib/cinch/channel.rb, line 299 def devoice(user) @bot.irc.send "MODE #{@name} -v #{user}" end
@return [Boolean] true if `user` is half-opped in the channel @since 1.1.0
# File lib/cinch/channel.rb, line 116 def half_opped?(user) @users[User(user)].include? "h" end
@return [Array<User>] All half-ops in the channel @since 2.0.0
# File lib/cinch/channel.rb, line 137 def half_ops @users.select { |_user, modes| modes.include?("h") }.keys end
@param [User, String] user An {User}-object or a nickname @return [Boolean] Check if a user is in the channel @since 1.1.0 @version 1.1.2
# File lib/cinch/channel.rb, line 104 def has_user?(user) @users.key?(User(user)) end
@return [Fixnum]
# File lib/cinch/channel.rb, line 438 def hash @name.hash end
@return [String]
# File lib/cinch/channel.rb, line 458 def inspect "#<Channel name=#{@name.inspect}>" end
Invites a user to the channel.
@param [String, User] user the user to invite @return [void]
# File lib/cinch/channel.rb, line 307 def invite(user) @bot.irc.send("INVITE #{user} #{@name}") end
@return [Boolean] true if the channel is invite only (+i)
# File lib/cinch/channel.rb, line 197 def invite_only @modes["i"] end
# File lib/cinch/channel.rb, line 202 def invite_only=(bool) if bool mode "+i" else mode "-i" end end
Joins the channel
@param [String] key the channel key, if any. If none is
specified but @key is set, @key will be used
@return [void]
# File lib/cinch/channel.rb, line 378 def join(key = nil) key = self.key if key.nil? && (self.key != true) @bot.irc.send "JOIN #{[@name, key].compact.join(" ")}" end
@return [String, nil] The channel's key (aka password)
# File lib/cinch/channel.rb, line 211 def key @modes["k"] end
# File lib/cinch/channel.rb, line 215 def key=(new_key) if new_key.nil? mode "-k #{key}" else mode "+k #{new_key}" end end
Kicks a user from the channel.
@param [String, User] user the user to kick @param [String] reason a reason for the kick @raise [Exceptions::KickReasonTooLong] @return [void]
# File lib/cinch/channel.rb, line 331 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
@return [Integer] The maximum number of allowed users in the
channel. 0 if unlimited.
# File lib/cinch/channel.rb, line 156 def limit @modes["l"].to_i end
# File lib/cinch/channel.rb, line 160 def limit=(val) if (val == -1) || val.nil? mode "-l" else mode "+l #{val}" end end
Sets or unsets modes. Most of the time you won't need this but use setter methods like {Channel#invite_only=}.
@param [String] s a mode string @return [void] @example
channel.mode "+n"
# File lib/cinch/channel.rb, line 361 def mode(s) @bot.irc.send "MODE #{@name} #{s}" end
@return [Boolean] true if the channel is moderated
# File lib/cinch/channel.rb, line 183 def moderated @modes["m"] end
# File lib/cinch/channel.rb, line 188 def moderated=(bool) if bool mode "+m" else mode "-m" end end
Ops a user.
@param [String, User] user the user to op @return [void]
# File lib/cinch/channel.rb, line 275 def op(user) @bot.irc.send "MODE #{@name} +o #{user}" end
@return [Boolean] true if `user` is opped in the channel @since 1.1.0
# File lib/cinch/channel.rb, line 110 def opped?(user) @users[User(user)].include? "o" end
@group User
groups @return [Array<User>] All ops in the channel @since 2.0.0
# File lib/cinch/channel.rb, line 131 def ops @users.select { |_user, modes| modes.include?("o") }.keys end
Causes the bot to part from the channel.
@param [String] message the part message. @return [void]
# File lib/cinch/channel.rb, line 369 def part(message = nil) @bot.irc.send "PART #{@name} :#{message}" end
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.
@param [User] user the user to remove @param [String] reason a reason for the removal @return [void]
# File lib/cinch/channel.rb, line 350 def remove(user, reason = nil) @bot.irc.send("REMOVE #{@name} #{user} :#{reason}") end
@api private @return [User, nil] The removed user
# File lib/cinch/channel.rb, line 395 def remove_user(user) @in_channel = false if user == @bot @users.delete(user) end
@return [Boolean] true if the channel is secret (+s)
# File lib/cinch/channel.rb, line 169 def secret @modes["s"] end
# File lib/cinch/channel.rb, line 174 def secret=(bool) if bool mode "+s" else mode "-s" end end
@note The aliases `msg` and `privmsg` are deprecated and will be
removed in a future version.
# 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(text, notice) end
@api private @return [void]
# File lib/cinch/channel.rb, line 225 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
@return [String] @note The alias `to_str` is deprecated and will be removed in a
future version. Channel objects should not be treated like strings.
# File lib/cinch/channel.rb, line 446 def to_s @name end
Sets the topic.
@param [String] new_topic the new topic @raise [Exceptions::TopicTooLong] Raised if the bot is operating
in {Bot#strict? strict mode} and when the new topic is too long.
# File lib/cinch/channel.rb, line 317 def topic=(new_topic) if new_topic.size > @bot.irc.isupport["TOPICLEN"] && @bot.strict? raise Exceptions::TopicTooLong, new_topic end @bot.irc.send "TOPIC #{@name} :#{new_topic}" end
Voices a user.
@param [String, User] user the user to voice @return [void]
# File lib/cinch/channel.rb, line 291 def voice(user) @bot.irc.send "MODE #{@name} +v #{user}" end
@return [Array<User>] All voiced users in the channel @since 2.0.0
# File lib/cinch/channel.rb, line 143 def voiced @users.select { |_user, modes| modes.include?("v") }.keys end
@return [Boolean] true if `user` is voiced in the channel @since 1.1.0
# File lib/cinch/channel.rb, line 122 def voiced?(user) @users[User(user)].include? "v" end