ircinch 2.4.0

data/lib/cinch/helpers.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Cinch
+  # The Helpers module contains a number of methods whose purpose is
+  # to make writing plugins easier by hiding parts of the API. The
+  # {#Channel} helper, for example, provides an easier way for turning
+  # a String object into a {Channel} object than directly using
+  # {ChannelList}: Compare `Channel("#some_channel")` with
+  # `bot.channel_list.find_ensured("#some_channel")`.
+  #
+  # The Helpers module automatically gets included in all plugins.
+  module Helpers
+    # @group Type casts
+
+    # Helper method for turning a String into a {Target} object.
+    #
+    # @param [String] target a target name
+    # @return [Target] a {Target} object
+    # @example
+    #   on :message, /^message (.+)$/ do |m, target|
+    #     Target(target).send "hi!"
+    #   end
+    # @since 2.0.0
+    def Target(target)
+      return target if target.is_a?(Target)
+      Target.new(target, bot)
+    end
+
+    # Helper method for turning a String into a {Channel} object.
+    #
+    # @param [String] channel a channel name
+    # @return [Channel] a {Channel} object
+    # @example
+    #   on :message, /^please join (#.+)$/ do |m, target|
+    #     Channel(target).join
+    #   end
+    # @since 1.0.0
+    def Channel(channel)
+      return channel if channel.is_a?(Channel)
+      bot.channel_list.find_ensured(channel)
+    end
+
+    # Helper method for turning a String into an {User} object.
+    #
+    # @param [String] user a user's nickname
+    # @return [User] an {User} object
+    # @example
+    #   on :message, /^tell me everything about (.+)$/ do |m, target|
+    #     user = User(target)
+    #     m.reply "%s is named %s and connects from %s" % [user.nick, user.name, user.host]
+    #   end
+    # @since 1.0.0
+    def User(user)
+      return user if user.is_a?(User)
+      if user == bot.nick
+        bot
+      else
+        bot.user_list.find_ensured(user)
+      end
+    end
+
+    # @example Used as a class method in a plugin
+    #   timer 5, method: :some_method
+    #   def some_method
+    #     Channel("#cinch-bots").send(Time.now.to_s)
+    #   end
+    #
+    # @example Used as an instance method in a plugin
+    #   match "start timer"
+    #   def execute(m)
+    #     Timer(5) { puts "timer fired" }
+    #   end
+    #
+    # @example Used as an instance method in a traditional `on` handler
+    #   on :message, "start timer" do
+    #     Timer(5) { puts "timer fired" }
+    #   end
+    #
+    # @param [Numeric] interval Interval in seconds
+    # @param [Proc] block A proc to execute
+    # @option options [Symbol] :method (:timer) Method to call (only
+    #   if no proc is provided)
+    # @option options [Boolean] :threaded (true) Call method in a
+    #   thread?
+    # @option options [Integer] :shots (Float::INFINITY) How often
+    #   should the timer fire?
+    # @option options [Boolean] :start_automatically (true) If true,
+    #   the timer will automatically start after the bot finished
+    #   connecting.
+    # @option options [Boolean] :stop_automaticall (true) If true, the
+    #   timer will automatically stop when the bot disconnects.
+    # @return [Timer]
+    # @since 2.0.0
+    def Timer(interval, options = {}, &block)
+      options = {method: :timer, threaded: true, interval: interval}.merge(options)
+      block ||= method(options[:method])
+      timer = Cinch::Timer.new(bot, options, &block)
+      timer.start
+
+      if respond_to?(:timers)
+        timers << timer
+      end
+
+      timer
+    end
+
+    # @endgroup
+
+    # @group Logging
+
+    # Use this method to automatically log exceptions to the loggers.
+    #
+    # @example
+    #   def my_method
+    #     rescue_exception do
+    #       something_that_might_raise()
+    #     end
+    #   end
+    #
+    # @return [void]
+    # @since 2.0.0
+    def rescue_exception
+      yield
+    rescue => e
+      bot.loggers.exception(e)
+    end
+
+    # (see Logger#log)
+    def log(messages, event = :debug, level = event)
+      if is_a?(Cinch::Plugin)
+        messages = Array(messages).map { |m|
+          "[#{self.class}] " + m
+        }
+      end
+      @bot.loggers.log(messages, event, level)
+    end
+
+    # (see Logger#debug)
+    def debug(message)
+      log(message, :debug)
+    end
+
+    # (see Logger#error)
+    def error(message)
+      log(message, :error)
+    end
+
+    # (see Logger#fatal)
+    def fatal(message)
+      log(message, :fatal)
+    end
+
+    # (see Logger#info)
+    def info(message)
+      log(message, :info)
+    end
+
+    # (see Logger#warn)
+    def warn(message)
+      log(message, :warn)
+    end
+
+    # (see Logger#incoming)
+    def incoming(message)
+      log(message, :incoming, :log)
+    end
+
+    # (see Logger#outgoing)
+    def outgoing(message)
+      log(message, :outgoing, :log)
+    end
+
+    # (see Logger#exception)
+    def exception(e)
+      log(e.message, :exception, :error)
+    end
+    # @endgroup
+
+    # @group Formatting
+
+    # (see Formatting.format)
+    def Format(*settings, string)
+      Formatting.format(*settings, string)
+    end
+    alias_method :Color, :Format # deprecated
+    undef_method(:Color) # yardoc hack
+
+    def Color(*args)
+      Cinch::Utilities::Deprecation.print_deprecation("2.2.0", "Helpers.Color", "Helpers.Format")
+      Format(*args)
+    end
+
+    # (see .sanitize)
+    def Sanitize(string)
+      Cinch::Helpers.sanitize(string)
+    end
+
+    # Deletes all characters in the ranges 0–8, 10–31 as well as the
+    # character 127, that is all non-printable characters and
+    # newlines.
+    #
+    # This method is useful for filtering text from external sources
+    # before sending it to IRC.
+    #
+    # Note that this method does not gracefully handle mIRC color
+    # codes, because it will leave the numeric arguments behind. If
+    # your text comes from IRC, you may want to filter it through
+    # {#Unformat} first. If you want to send sanitized input that
+    # includes your own formatting, first use this method, then add
+    # your formatting.
+    #
+    # There exist methods for sending messages that automatically
+    # call this method, namely {Target#safe_msg},
+    # {Target#safe_notice}, and {Target#safe_action}.
+    #
+    # @param [String] string The string to filter
+    # @return [String] The filtered string
+    # @since 2.2.0
+    def self.sanitize(string)
+      string.gsub(/[\x00-\x08\x0a-\x1f\x7f]/, "")
+    end
+
+    # (see Formatting.unformat)
+    def Unformat(string)
+      Formatting.unformat(string)
+    end
+
+    # @endgroup
+  end
+end

data/lib/cinch/i_support.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Cinch
+  # This class exposes parsed ISUPPORT information of the IRC network.
+  class ISupport < Hash
+    @@mappings = {
+      %w[PREFIX] => lambda { |v|
+        modes, prefixes = v.match(/^\((.+)\)(.+)$/)[1..2]
+        h = {}
+        modes.chars.each_with_index do |c, i|
+          h[c] = prefixes[i]
+        end
+        h
+      },
+
+      %w[CHANTYPES] => lambda { |v| v.chars },
+      %w[CHANMODES] => lambda { |v|
+        h = {}
+        h["A"], h["B"], h["C"], h["D"] = v.split(",").map { |l| l.chars }
+        h
+      },
+
+      %w[MODES MAXCHANNELS NICKLEN MAXBANS TOPICLEN
+        KICKLEN CHANNELLEN CHIDLEN SILENCE AWAYLEN
+        MAXTARGETS WATCH MONITOR] => lambda { |v| v.to_i },
+
+      %w[CHANLIMIT MAXLIST IDCHAN] => lambda { |v|
+        h = {}
+        v.split(",").each do |pair|
+          args, num = pair.split(":")
+          args.chars.each do |arg|
+            h[arg] = num.to_i
+          end
+        end
+        h
+      },
+
+      %w[TARGMAX] => lambda { |v|
+        h = {}
+        v.split(",").each do |pair|
+          name, value = pair.split(":")
+          h[name] = value.to_i
+        end
+        h
+      },
+
+      %w[NETWORK] => lambda { |v| v },
+      %w[STATUSMSG] => lambda { |v| v.chars },
+      %w[CASEMAPPING] => lambda { |v| v.to_sym },
+      %w[ELIST] => lambda { |v| v.chars }
+      # TODO STD
+    }
+
+    def initialize(*args)
+      super
+      # by setting most numeric values to "Infinity", we let the
+      # server truncate messages and lists while at the same time
+      # allowing the use of strictness=:strict for servers that don't
+      # support ISUPPORT (hopefully none, anyway)
+
+      self["PREFIX"] = {"o" => "@", "v" => "+"}
+      self["CHANTYPES"] = ["#"]
+      self["CHANMODES"] = {
+        "A" => ["b"],
+        "B" => ["k"],
+        "C" => ["l"],
+        "D" => %w[i m n p s t r]
+      }
+      self["MODES"] = 1
+      self["NICKLEN"] = Float::INFINITY
+      self["MAXBANS"] = Float::INFINITY
+      self["TOPICLEN"] = Float::INFINITY
+      self["KICKLEN"] = Float::INFINITY
+      self["CHANNELLEN"] = Float::INFINITY
+      self["CHIDLEN"] = 5
+      self["AWAYLEN"] = Float::INFINITY
+      self["MAXTARGETS"] = 1
+      self["MAXCHANNELS"] = Float::INFINITY # deprecated
+      self["CHANLIMIT"] = {"#" => Float::INFINITY}
+      self["STATUSMSG"] = []
+      self["CASEMAPPING"] = :rfc1459
+      self["ELIST"] = []
+      self["MONITOR"] = 0
+    end
+
+    # @api private
+    # @return [void]
+    def parse(*options)
+      options.each do |option|
+        name, value = option.split("=")
+        if value
+          proc = @@mappings.find { |key, _| key.include?(name) }
+          self[name] = (proc && proc[1].call(value)) || value
+        else
+          self[name] = true
+        end
+      end
+    end
+  end
+end