cinch 2.2.8 → 2.3.0

data/docs/logging.md

@@ -49,6 +49,41 @@ This will set all loggers to the `:debug` level (which actually is the
 default already) and the first logger (which is the default STDOUT
 logger) to `:info`.
 
+# Log filtering
+
+Sometimes it is undesirable to log a message unchanged. For example
+when identifying to the network, passwords might be sent in plain
+text. To prevent such information from appearing in logs, {Cinch::LogFilter log filters}
+can be employed.
+
+Log filters take a log message as input and return a new message. This
+allows removing/masking out passwords or other undesired information.
+Additionally, messages can be dropped entirely by returning nil.
+
+It is possible to use more than one filter, in which case they will be
+called in order, each acting on the previous filter's output.
+
+Filters can be installed by adding them to {Cinch::LoggerList#filters}.
+
+An example (and very simple) password filter might look like this:
+
+    class PasswordFilter
+      def initialize(bot)
+        @bot = bot
+      end
+
+      def filter(message, event)
+        message.gsub(@bot.config.password, "*" * @bot.config.password.size)
+      end
+    end
+
+This filter will replace the password in all log messages (except for
+exceptions). It could further discriminate by looking at `event` and
+only modify outgoing IRC messages. It could also use the
+{Cinch::Message} class to parse the message and only operate on the
+actual message component, not channel names and similar. How fancy
+your filtering needs to be depends on you.
+
 # Writing your own logger
 
 This section will follow soon. For now just look at the code of

data/lib/cinch/channel.rb

@@ -43,6 +43,9 @@ module Cinch
     # @return [Hash{String => Object}]
     attr_reader :modes
     synced_attr_reader :modes
+
+    # @note Generally, you shouldn't initialize new instances of this
+    #   class. Use {ChannelList#find_ensured} instead.
     def initialize(name, bot)
       @bot    = bot
       @name   = name

data/lib/cinch/isupport.rb

@@ -75,7 +75,7 @@ module Cinch
       self["MAXTARGETS"]  = 1
       self["MAXCHANNELS"] = Float::INFINITY # deprecated
       self["CHANLIMIT"]   = {"#" => Float::INFINITY}
-      self["STATUSMSG"]   = ["@", "+"]
+      self["STATUSMSG"]   = []
       self["CASEMAPPING"] = :rfc1459
       self["ELIST"]       = []
       self["MONITOR"]     = 0

data/lib/cinch/log_filter.rb

@@ -0,0 +1,21 @@
+module Cinch
+  # LogFilter describes an interface for filtering log messages before
+  # they're printed.
+  #
+  # @abstract
+  # @since 2.3.0
+  class LogFilter
+    # filter is called for each log message, except for exceptions. It
+    # returns a new string, which is the one that should be printed, or
+    # further filtered by other filters. Returning nil will drop the
+    # message.
+    #
+    # @param [String] message The message that is to be logged
+    # @param [:debug, :incoming, :outgoing, :info, :warn, :exception,
+    #   :error, :fatal] event The kind of message
+    # @return [String, nil] The modified message, as it should be
+    #   logged, or nil if the message shouldn't be logged at all
+    def filter(message, event)
+    end
+  end
+end

data/lib/cinch/logger_list.rb

@@ -9,6 +9,17 @@ module Cinch
   # @attr_writer level
   # @since 2.0.0
   class LoggerList < Array
+    # A list of log filters that will be applied before emitting a log
+    # message.
+    #
+    # @return [Array<LogFilter>]
+    # @since 2.3.0
+    attr_accessor :filters
+    def initialize(*args)
+      @filters = []
+      super
+    end
+
     # (see Logger#level=)
     def level=(level)
       each {|l| l.level = level}
@@ -16,47 +27,64 @@ module Cinch
 
     # (see Logger#log)
     def log(messages, event = :debug, level = event)
-      each {|l| l.log(messages, event, level)}
+      do_log(messages, event, level)
     end
 
     # (see Logger#debug)
     def debug(message)
-      each {|l| l.debug(message)}
+      do_log(message, :debug)
     end
 
     # (see Logger#error)
     def error(message)
-      each {|l| l.error(message)}
+      do_log(message, :error)
     end
 
     # (see Logger#error)
     def fatal(message)
-      each {|l| l.fatal(message)}
+      do_log(message, :fatal)
     end
 
     # (see Logger#info)
     def info(message)
-      each {|l| l.info(message)}
+      do_log(message, :info)
     end
 
     # (see Logger#warn)
     def warn(message)
-      each {|l| l.warn(message)}
+      do_log(message, :warn)
     end
 
     # (see Logger#incoming)
     def incoming(message)
-      each {|l| l.incoming(message)}
+      do_log(message, :incoming, :log)
     end
 
     # (see Logger#outgoing)
     def outgoing(message)
-      each {|l| l.outgoing(message)}
+      do_log(message, :outgoing, :log)
     end
 
     # (see Logger#exception)
     def exception(e)
-      each {|l| l.exception(e)}
+      do_log(e, :exception, :error)
+    end
+
+    private
+    def do_log(messages, event, level = event)
+      messages = Array(messages)
+      if event != :exception
+        messages.map! { |m|
+          @filters.each do |f|
+            m = f.filter(m, event)
+            if m.nil?
+              break
+            end
+          end
+          m
+        }.compact
+      end
+      each {|l| l.log(messages, event, level)}
     end
   end
 end

data/lib/cinch/message.rb

@@ -66,12 +66,28 @@ module Cinch
     # @return [Target]
     attr_reader :target
 
+    # The STATUSMSG mode a channel message was sent to.
+    #
+    # Some IRC servers allow sending messages limited to people in a
+    # channel who have a certain mode. For example, by sending a
+    # message to `+#channel`, only people who are voiced, or have a
+    # higher mode (op) will receive the message.
+    #
+    # This attribute contains the mode character the message was sent
+    # to, or nil if it was a normal message. For the previous example,
+    # this attribute would be set to `"v"`, for voiced.
+    #
+    # @return [String, nil]
+    # @since 2.3.0
+    attr_reader :statusmsg_mode
+
     def initialize(msg, bot)
       @raw     = msg
       @bot     = bot
       @matches = {:ctcp => {}, :action => {}, :other => {}}
       @events  = []
       @time    = Time.now
+      @statusmsg_mode = nil
       parse if msg
     end
 
@@ -90,7 +106,7 @@ module Cinch
       @params  = parse_params(raw_params)
 
       @user    = parse_user
-      @channel = parse_channel
+      @channel, @statusmsg_mode = parse_channel
       @target  = @channel || @user
       @server  = parse_server
       @error   = parse_error
@@ -160,6 +176,11 @@ module Cinch
     # Replies to a message, automatically determining if it was a
     # channel or a private message.
     #
+    # If the message is a STATUSMSG, i.e. it was send to `+#channel`
+    # or `@#channel` instead of `#channel`, the reply will be sent as
+    # the same kind of STATUSMSG. See {#statusmsg_mode} for more
+    # information on STATUSMSG.
+    #
     # @param [String] text the message
     # @param [Boolean] prefix if prefix is true and the message was in
     #   a channel, the reply will be prefixed by the nickname of whoever
@@ -171,10 +192,10 @@ module Cinch
         text = text.split("\n").map {|l| "#{user.nick}: #{l}"}.join("\n")
       end
 
-      @target.send(text)
+      reply_target.send(text)
     end
 
-    # Like #reply, but using {Target#safe_send} instead
+    # Like {#reply}, but using {Target#safe_send} instead
     #
     # @param (see #reply)
     # @return (see #reply)
@@ -183,25 +204,27 @@ module Cinch
       if channel && prefix
         text = "#{@user.nick}: #{text}"
       end
-      @target.safe_send(text)
+      reply_target.safe_send(text)
     end
 
     # Reply to a message with an action.
     #
+    # For its behaviour with regard to STATUSMSG, see {#reply}.
+    #
     # @param [String] text the action message
     # @return [void]
     def action_reply(text)
       text = text.to_s
-      @target.action(text)
+      reply_target.action(text)
     end
 
-    # Like #action_reply, but using {Target#safe_action} instead
+    # Like {#action_reply}, but using {Target#safe_action} instead
     #
     # @param (see #action_reply)
     # @return (see #action_reply)
     def safe_action_reply(text)
       text = text.to_s
-      @target.safe_action(text)
+      reply_target.safe_action(text)
     end
 
     # Reply to a CTCP message
@@ -221,6 +244,13 @@ module Cinch
     end
 
     private
+    def reply_target
+      if @channel.nil? || @statusmsg_mode.nil?
+        return @target
+      end
+      prefix = @bot.irc.isupport["PREFIX"][@statusmsg_mode]
+      return Target.new(prefix + @channel.name, @bot)
+    end
     def regular_command?
       !numeric_reply? # a command can only be numeric or "regular"…
     end
@@ -262,15 +292,27 @@ module Cinch
         # `QUIT :#sometext` will be interpreted as a channel. The
         # alternative to the currently used heuristic would be to
         # hardcode a list of commands that provide a channel argument.
-        chantypes = @bot.irc.isupport["CHANTYPES"]
-        if chantypes.include?(@params.first[0])
-          @bot.channel_list.find_ensured(@params.first)
-        elsif numeric_reply? and @params.size > 1 and chantypes.include?(@params[1][0])
-          @bot.channel_list.find_ensured(@params[1])
+        ch, status = privmsg_channel_name(@params.first)
+        if ch.nil? && numeric_reply? && @params.size > 1
+          ch, status = privmsg_channel_name(@params[1])
+        end
+        if ch
+          return @bot.channel_list.find_ensured(ch), status
         end
       end
     end
 
+    def privmsg_channel_name(s)
+      chantypes = @bot.irc.isupport["CHANTYPES"]
+      statusmsg = @bot.irc.isupport["STATUSMSG"]
+      if statusmsg.include?(s[0]) && chantypes.include?(s[1])
+        status = @bot.irc.isupport["PREFIX"].invert[s[0]]
+        return s[1..-1], status
+      elsif chantypes.include?(s[0])
+        return s, nil
+      end
+    end
+
     def parse_server
       return unless @prefix
       return if @prefix.match(/[@!]/)

data/lib/cinch/plugin.rb

@@ -1,6 +1,5 @@
 require "cinch/helpers"
 
-# TODO more details in "message dropped" debug output
 module Cinch
   # This class represents the core of the plugin functionality of
   # Cinch. It provides both the methods for users to write their own
@@ -512,3 +511,5 @@ module Cinch
     end
   end
 end
+
+# TODO more details in "message dropped" debug output

data/lib/cinch/user.rb

@@ -185,7 +185,8 @@ module Cinch
     # @api private
     attr_writer :monitored
 
-
+    # @note Generally, you shouldn't initialize new instances of this
+    #   class. Use {UserList#find_ensured} instead.
     def initialize(*args)
       @data = {
         :user         => nil,
@@ -269,8 +270,6 @@ module Cinch
 
     # @param [Hash, nil] values A hash of values gathered from WHOIS,
     #   or `nil` if no data was returned
-    # @param [Boolean] not_found Has to be true if WHOIS resulted in
-    #   an unknown user
     # @return [void]
     # @api private
     # @since 1.0.1

data/lib/cinch/version.rb

@@ -1,4 +1,4 @@
 module Cinch
   # Version of the library
-  VERSION = '2.2.8'
+  VERSION = '2.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cinch
 version: !ruby/object:Gem::Version
-  version: 2.2.8
+  version: 2.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-23 00:00:00.000000000 Z
+date: 2015-10-26 00:00:00.000000000 Z
 dependencies: []
 description: A simple, friendly DSL for creating IRC bots
 email:
@@ -35,6 +35,7 @@ files:
 - lib/cinch/formatting.rb
 - lib/cinch/channel.rb
 - lib/cinch/timer.rb
+- lib/cinch/log_filter.rb
 - lib/cinch/sasl/diffie_hellman.rb
 - lib/cinch/sasl/plain.rb
 - lib/cinch/sasl/dh_blowfish.rb
@@ -44,7 +45,6 @@ files:
 - lib/cinch/cached_list.rb
 - lib/cinch/bot.rb
 - lib/cinch/isupport.rb
-- lib/cinch/#channel.rb#
 - lib/cinch/helpers.rb
 - lib/cinch/handler.rb
 - lib/cinch/handler_list.rb
@@ -141,3 +141,4 @@ signing_key:
 specification_version: 3
 summary: An IRC Bot Building Framework
 test_files: []
+has_rdoc: yard

data/lib/cinch/#channel.rb#

@@ -1,407 +0,0 @@
-# -*- coding: utf-8 -*-
-require "set"
-require "cinch/target"
-
-module Cinch
-  # @attr limit
-  # @attr secret
-  # @attr moderated
-  # @attr invite_only
-  # @attr key
-  #
-  # @version 2.0.0
-  class Channel < Target
-    include Syncable
-    include Helpers
-
-    def initialize(name, bot)
-      @bot    = bot
-      @name   = name
-      # TODO raise if not a channel
-    end
-
-    def users
-      sync_get(:users)
-    end
-
-    def topic
-      sync_get(:topic, lambda {@bot.irc.send "TOPIC #@name"})
-    end
-
-    def bans
-      sync_get(:bans, lambda {@bot.irc.send "MODE #@name +b"})
-    end
-
-    def owners
-      sync_get(:owners, lambda {
-                 if !@bot.irc.network.owner_list_mode
-                   sync_set(:owners, [])
-                   return
-                 end
-                 @bot.irc.send "MODE #@name +#{@bot.irc.network.owner_list_mode}"
-               })
-    end
-
-    def modes
-      sync_get(:modes, lambda {@bot.irc.send "MODE #@name"})
-    end
-
-    # @group Checks
-
-    # @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
-    def has_user?(user)
-      users.has_key?(User(user))
-    end
-
-    # @return [Boolean] true if `user` is opped in the channel
-    # @since 1.1.0
-    def opped?(user)
-      users[User(user)].include? "o"
-    end
-
-    # @return [Boolean] true if `user` is half-opped in the channel
-    # @since 1.1.0
-    def half_opped?(user)
-      users[User(user)].include? "h"
-    end
-
-    # @return [Boolean] true if `user` is voiced in the channel
-    # @since 1.1.0
-    def voiced?(user)
-      users[User(user)].include? "v"
-    end
-
-    # @endgroup
-
-    # @group User groups
-    # @return [Array<User>] All ops in the channel
-    # @since 2.0.0
-    def ops
-      users.select {|user, modes| modes.include?("o")}.keys
-    end
-
-    # @return [Array<User>] All half-ops in the channel
-    # @since 2.0.0
-    def half_ops
-      users.select {|user, modes| modes.include?("h")}.keys
-    end
-
-    # @return [Array<User>] All voiced users in the channel
-    # @since 2.0.0
-    def voiced
-      users.select {|user, modes| modes.include?("v")}.keys
-    end
-
-    # @return [Array<User>] All admins in the channel
-    # @since 2.0.0
-    def admins
-      users.select {|user, modes| modes.include?("a")}.keys
-    end
-    # @endgroup
-
-    # @return [Integer] The maximum number of allowed users in the
-    #   channel. 0 if unlimited.
-    def limit
-      modes["l"].to_i
-    end
-
-    def limit=(val)
-      if val == -1 or val.nil?
-        mode "-l"
-      else
-        mode "+l #{val}"
-      end
-    end
-
-    # @return [Boolean] true if the channel is secret (+s)
-    def secret?
-      modes["s"]
-    end
-    alias_method :secret, :secret?
-
-    def secret=(bool)
-      if bool
-        mode "+s"
-      else
-        mode "-s"
-      end
-    end
-
-    # @return [Boolean] true if the channel is moderated
-    def moderated?
-      modes["m"]
-    end
-    alias_method :moderated, :moderated?
-
-    def moderated=(bool)
-      if bool
-        mode "+m"
-      else
-        mode "-m"
-      end
-    end
-
-    # @return [Boolean] true if the channel is invite only (+i)
-    def invite_only?
-      modes["i"]
-    end
-    alias_method :invite_only, :invite_only?
-
-    def invite_only=(bool)
-      if bool
-        mode "+i"
-      else
-        mode "-i"
-      end
-    end
-
-    # @return [String, nil] The channel's key (aka password)
-    def key
-      modes["k"]
-    end
-
-    def key=(new_key)
-      if new_key.nil?
-        mode "-k #{key}"
-      else
-        mode "+k #{new_key}"
-      end
-    end
-
-    # @api private
-    # @return [void]
-    def sync_modes
-      sync_await(:users)
-      sync_unset(:users)
-
-      if @bot.irc.isupport["WHOX"]
-        @bot.irc.send "WHO #@name %acfhnru"
-      else
-        @bot.irc.send "WHO #@name"
-      end
-    end
-
-    # @group Channel Manipulation
-
-    # 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
-    def ban(target)
-      mask = Mask.from(target)
-
-      @bot.irc.send "MODE #@name +b #{mask}"
-      mask
-    end
-
-    # Unbans someone from the channel.
-    #
-    # @param [Mask, String, #mask] target the mask to unban
-    # @return [Mask] the mask used for unbanning
-    # @see #ban #ban for banning users
-    def unban(target)
-      mask = Mask.from(target)
-
-      @bot.irc.send "MODE #@name -b #{mask}"
-      mask
-    end
-
-    # Ops a user.
-    #
-    # @param [String, User] user the user to op
-    # @return [void]
-    def op(user)
-      @bot.irc.send "MODE #@name +o #{user}"
-    end
-
-    # Deops a user.
-    #
-    # @param [String, User] user the user to deop
-    # @return [void]
-    def deop(user)
-      @bot.irc.send "MODE #@name -o #{user}"
-    end
-
-    # Voices a user.
-    #
-    # @param [String, User] user the user to voice
-    # @return [void]
-    def voice(user)
-      @bot.irc.send "MODE #@name +v #{user}"
-    end
-
-    # Devoices a user.
-    #
-    # @param [String, User] user the user to devoice
-    # @return [void]
-    def devoice(user)
-      @bot.irc.send "MODE #@name -v #{user}"
-    end
-
-    # Invites a user to the channel.
-    #
-    # @param [String, User] user the user to invite
-    # @return [void]
-    def invite(user)
-      @bot.irc.send("INVITE #{user} #@name")
-    end
-
-    undef_method(:topic=)
-    # 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.
-    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
-
-    # 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]
-    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
-
-    # 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]
-    def remove(user, reason = nil)
-      @bot.irc.send("REMOVE #@name #{user} :#{reason}")
-    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"
-    def mode(s)
-      @bot.irc.send "MODE #@name #{s}"
-    end
-
-    # Causes the bot to part from the channel.
-    #
-    # @param [String] message the part message.
-    # @return [void]
-    def part(message = nil)
-      @bot.irc.send "PART #@name :#{message}"
-    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]
-    def join(key = nil)
-      if key.nil? and self.key != true
-        key = self.key
-      end
-      @bot.irc.send "JOIN #{[@name, key].compact.join(" ")}"
-    end
-
-    # @endgroup
-
-    # @api private
-    # @return [User] The added user
-    def add_user(user, modes = [])
-      # XXX
-      @users[user] = modes
-      user
-    end
-
-    # @api private
-    # @return [User, nil] The removed user
-    def remove_user(user)
-      # XXX
-      @users.delete(user)
-    end
-
-    # Removes all users
-    #
-    # @api private
-    # @return [void]
-    def clear_users
-      # XXX
-      @users.clear
-    end
-
-    # @note The aliases `msg` and `privmsg` are deprecated and will be
-    #   removed in a future version.
-    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
-    alias_method :msg, :send # deprecated
-    alias_method :privmsg, :send # deprecated
-    undef_method(:msg) # yardoc hack
-    undef_method(:privmsg) # yardoc hack
-
-    # @deprecated
-    def msg(*args)
-      Cinch::Utilities::Deprecation.print_deprecation("2.2.0", "Channel#msg", "Channel#send")
-      send(*args)
-    end
-
-    # @deprecated
-    def privmsg(*args)
-      Cinch::Utilities::Deprecation.print_deprecation("2.2.0", "Channel#privmsg", "Channel#send")
-      send(*args)
-    end
-
-    # @return [Fixnum]
-    def hash
-      @name.hash
-    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.
-    def to_s
-      @name
-    end
-    alias_method :to_str, :to_s # deprecated
-    undef_method(:to_str) # yardoc hack
-
-    def to_str
-      Cinch::Utilities::Deprecation.print_deprecation("2.2.0", "Channel#to_str", "Channel#to_s")
-      to_s
-    end
-
-    # @return [String]
-    def inspect
-      "#<Channel name=#{@name.inspect}>"
-    end
-  end
-end