---
-- This module implements a channel object representing a single channel we
--- have joined
--- @release 0.02
+-- have joined.
module 'irc.channel'
-- object metatable {{{
-- }}}
-- }}}
+-- internal methods {{{
+-- TODO: is there a better way to do this? also, storing op/voice as initial
+-- substrings of the username is just ugly
+-- _add_user {{{
+--
+-- Add a user to the channel's internal user list.
+-- @param self Channel object
+-- @param user Nick of the user to add
+-- @param mode Mode (op/voice) of the user, in symbolic form (@/+)
+function _add_user(self, user, mode)
+ mode = mode or ''
+ self._members[user] = mode .. user
+end
+-- }}}
+
+-- _remove_user {{{
+--
+-- Remove a user from the channel's internal user list.
+-- @param self Channel object
+-- @param user Nick of the user to remove
+function _remove_user(self, user)
+ self._members[user] = nil
+end
+-- }}}
+
+-- _change_status {{{
+--
+-- Change the op/voice status of a user in the channel's internal user list.
+-- @param self Channel object
+-- @param user Nick of the user to affect
+-- @param on True if the mode is being set, false if it's being unset
+-- @param mode 'o' for op, 'v' for voice
+function _change_status(self, user, on, mode)
+ if on then
+ if mode == 'o' then
+ self._members[user] = '@' .. user
+ elseif mode == 'v' then
+ self._members[user] = '+' .. user
+ end
+ else
+ if (mode == 'o' and self._members[user]:sub(1, 1) == '@') or
+ (mode == 'v' and self._members[user]:sub(1, 1) == '+') then
+ self._members[user] = user
+ end
+ end
+end
+-- }}}
+
+-- _change_nick {{{
+--
+-- Change the nick of a user in the channel's internal user list.
+-- @param self Channel object
+-- @param old_nick User's old nick
+-- @param new_nick User's new nick
+function _change_nick(self, old_nick, new_nick)
+ for member in self:each_member() do
+ local member_nick = member:gsub('@+', '')
+ if member_nick == old_nick then
+ local mode = self._members[old_nick]:sub(1, 1)
+ if mode ~= '@' and mode ~= '+' then mode = "" end
+ self._members[old_nick] = nil
+ self._members[new_nick] = mode .. new_nick
+ break
+ end
+ end
+end
+-- }}}
+-- }}}
+
-- constructor {{{
---
-- Creates a new Channel object.
-- @param self Channel object
function each_op(self)
return function(state, arg)
- return misc.value_iter(state, arg,
- function(v)
- return v:sub(1, 1) == "@"
- end)
+ return misc._value_iter(state, arg,
+ function(v)
+ return v:sub(1, 1) == "@"
+ end)
end,
self._members,
nil
-- @param self Channel object
function each_voice(self)
return function(state, arg)
- return misc.value_iter(state, arg,
- function(v)
- return v:sub(1, 1) == "+"
- end)
+ return misc._value_iter(state, arg,
+ function(v)
+ return v:sub(1, 1) == "+"
+ end)
end,
self._members,
nil
-- @param self Channel object
function each_user(self)
return function(state, arg)
- return misc.value_iter(state, arg,
- function(v)
- return v:sub(1, 1) ~= "@" and
- v:sub(1, 1) ~= "+"
- end)
+ return misc._value_iter(state, arg,
+ function(v)
+ return v:sub(1, 1) ~= "@" and
+ v:sub(1, 1) ~= "+"
+ end)
end,
self._members,
nil
-- Iterator over all users in the channel
-- @param self Channel object
function each_member(self)
- return misc.value_iter, self._members, nil
+ return misc._value_iter, self._members, nil
end
-- }}}
-- }}}
-- }}}
-- setting modes {{{
--- ban() - ban a user from a channel {{{
+-- ban {{{
-- TODO: hmmm, this probably needs an appropriate mask, rather than a nick
+---
+-- Ban a user from a channel.
+-- @param self Channel object
+-- @param name User to ban
function ban(self, name)
irc.send("MODE", self.name, "+b", name)
end
-- }}}
--- unban() - remove a ban on a user {{{
+-- unban {{{
-- TODO: same here
+---
+-- Remove a ban on a user.
+-- @param self Channel object
+-- @param name User to unban
function unban(self, name)
irc.send("MODE", self.name, "-b", name)
end
-- }}}
--- voice() - give a user voice on a channel {{{
+-- voice {{{
+---
+-- Give a user voice on a channel.
+-- @param self Channel object
+-- @param name User to give voice to
function voice(self, name)
irc.send("MODE", self.name, "+v", name)
end
-- }}}
--- devoice() - remove voice from a user {{{
+-- devoice {{{
+---
+-- Remove voice from a user.
+-- @param self Channel object
+-- @param name User to remove voice from
function devoice(self, name)
irc.send("MODE", self.name, "-v", name)
end
-- }}}
--- op() - give a user ops on a channel {{{
+-- op {{{
+---
+-- Give a user ops on a channel.
+-- @param self Channel object
+-- @param name User to op
function op(self, name)
irc.send("MODE", self.name, "+o", name)
end
-- }}}
--- deop() - remove ops from a user {{{
+-- deop {{{
+---
+-- Remove ops from a user.
+-- @param self Channel object
+-- @param name User to remove ops from
function deop(self, name)
irc.send("MODE", self.name, "-o", name)
end
-- }}}
--- set_limit() - set a channel limit {{{
+-- set_limit {{{
+---
+-- Set a channel limit.
+-- @param self Channel object
+-- @param new_limit New value for the channel limit (optional; limit is unset
+-- if this argument isn't passed)
function set_limit(self, new_limit)
if new_limit then
irc.send("MODE", self.name, "+l", new_limit)
end
-- }}}
--- set_key() - set a channel password {{{
+-- set_key {{{
+---
+-- Set a channel password.
+-- @param self Channel object
+-- @param key New channel password (optional; password is unset if this
+-- argument isn't passed)
function set_key(self, key)
if key then
irc.send("MODE", self.name, "+k", key)
end
-- }}}
--- set_private() - set the private state of a channel {{{
+-- set_private {{{
+---
+-- Set the private state of a channel.
+-- @param self Channel object
+-- @param set True to set the channel as private, false to unset it
function set_private(self, set)
set_basic_mode(self, set, "p")
end
-- }}}
--- set_secret() - set the secret state of a channel {{{
+-- set_secret {{{
+---
+-- Set the secret state of a channel.
+-- @param self Channel object
+-- @param set True to set the channel as secret, false to unset it
function set_secret(self, set)
set_basic_mode(self, set, "s")
end
-- }}}
--- set_invite_only() - set whether joining the channel requires an invite {{{
+-- set_invite_only {{{
+---
+-- Set whether joining the channel requires an invite.
+-- @param self Channel object
+-- @param set True to set the channel invite only, false to unset it
function set_invite_only(self, set)
set_basic_mode(self, set, "i")
end
-- }}}
--- set_topic_lock() - if true, the topic can only be changed by an op {{{
+-- set_topic_lock {{{
+---
+-- If true, the topic can only be changed by an op.
+-- @param self Channel object
+-- @param set True to lock the topic, false to unlock it
function set_topic_lock(self, set)
set_basic_mode(self, set, "t")
end
-- }}}
--- set_no_outside_messages() - if true, users must be in the channel to send messages to it {{{
+-- set_no_outside_messages {{{
+---
+-- If true, users must be in the channel to send messages to it.
+-- @param self Channel object
+-- @param set True to require users to be in the channel to send messages to
+-- it, false to remove this restriction
function set_no_outside_messages(self, set)
set_basic_mode(self, set, "n")
end
-- }}}
--- set moderated() - set whether voice is required to speak {{{
+-- set moderated {{{
+---
+-- Set whether voice is required to speak.
+-- @param self Channel object
+-- @param set True to set the channel as moderated, false to unset it
function set_moderated(self, set)
set_basic_mode(self, set, "m")
end
-- }}}
-- accessors {{{
--- add_user() {{{
-function add_user(self, user, mode)
- mode = mode or ''
- self._members[user] = mode .. user
-end
--- }}}
-
--- remove_user() {{{
-function remove_user(self, user)
- self._members[user] = nil
-end
--- }}}
-
--- change_status() {{{
-function change_status(self, user, on, mode)
- if on then
- if mode == 'o' then
- self._members[user] = '@' .. user
- elseif mode == 'v' then
- self._members[user] = '+' .. user
- end
- else
- if (mode == 'o' and self._members[user]:sub(1, 1) == '@') or
- (mode == 'v' and self._members[user]:sub(1, 1) == '+') then
- self._members[user] = user
- end
- end
-end
--- }}}
-
--- contains() {{{
+-- contains {{{
+---
+-- Test if a user is in the channel.
+-- @param self Channel object
+-- @param nick Nick to search for
+-- @return True if the nick is in the channel, false otherwise
function contains(self, nick)
for member in self:each_member() do
local member_nick = member:gsub('@+', '')
return false
end
-- }}}
-
--- change_nick {{{
-function change_nick(self, old_nick, new_nick)
- for member in self:each_member() do
- local member_nick = member:gsub('@+', '')
- if member_nick == old_nick then
- local mode = self._members[old_nick]:sub(1, 1)
- if mode ~= '@' and mode ~= '+' then mode = "" end
- self._members[old_nick] = nil
- self._members[new_nick] = mode .. new_nick
- break
- end
- end
-end
--- }}}
-- }}}
-- }}}