cinch 2.1.0 → 2.2.0

data/README.md

@@ -12,10 +12,8 @@ profits flourish.
 Cinch will do all of the hard work for you, so you can spend time creating cool
 plugins and extensions to wow your internet peers.
 
-If you'd like to test your own Cinch experiments you can do so in the
-\#cinch-bots IRC channel on
-[irc.freenode.org](irc://irc.freenode.org/cinch-bots). For general
-support, join [#cinch](irc://irc.freenode.org/cinch).
+For general support, join [#cinch](irc://irc.freenode.org/cinch) – but
+please don't bring any bots.
 
 Installation
 ------------
@@ -156,11 +154,6 @@ on :message, /hello/ do |m|
 end
 ```
 
-Authors
--------
-
-* [Dominik Honnef](http://dominik.honnef.co)
-
 Contribute
 ----------
 
@@ -175,11 +168,3 @@ of supporting Ruby versions below 1.9.1.
 Fork the project, implement your awesome feature in its own branch, and send
 a pull request to one of the Cinch collaborators. We'll be more than happy
 to check it out.
-
-### Contributors
-- darix <darix [at] nordisch.org> (wrote the message splitting algorithm)
-- robgleeson (thanks for testing, contributing a lot of ideas,
-  discussing design decisions etc)
-- Emil Loer (http://github.com/thedjinn) for improving the handling of
-  unexpected disconnects and reconnects.
-- Check the list of authors for smaller contributions

data/docs/bot_options.md

@@ -430,5 +430,5 @@ Default value
 : `10`
 
 Description
-: Give up connecting after his amount of seconds.
+: Give up connecting after this amount of seconds.
 

data/docs/changes.md

@@ -1,6 +1,54 @@
 # @title What has changed?
 # @markup kramdown
 
+# What has changed in 2.2?
+
+## Getting rid of CP1252 in favour of UTF-8
+
+In versions before 2.2, when using the `irc` encoding (the default),
+Cinch would use CP1252 for outgoing messages, only falling back to
+UTF-8 if a message wouldn't fit into CP1252. This is a so called
+hybrid encoding, which is used by X-Chat and the like.
+
+This encoding, however, is based on the state of 10 years ago, where
+the most popular IRC clients, such as mIRC, weren't capable of
+handling UTF-8. Nowadays, there are more clients that support UTF-8
+than there are clients that can deal with this hybrid encoding, or
+CP1252 itself. That's why, from now on, we will always use UTF-8.
+
+If you depend on outgoing messages being encoded in CP1252, please see
+{file:docs/encodings.md} on how to change the encoding.
+
+## API improvements
+
+### New methods
+
+- {Cinch::Channel#remove} has been added to support the non-standard
+REMOVE command, a friendlier alternative to kicking people.
+
+- {Cinch::Helpers.sanitize} and {Cinch::Formatting.unformat} have been
+  added to help with removing unprintable characters and mIRC
+  formatting codes from strings.
+
+### Deprecated methods
+
+In order to reduce the amount of aliases, the following ones have been
+deprecated and will be removed in a future release:
+
+- {Cinch::Channel#msg}
+- {Cinch::Channel#privmsg}
+- {Cinch::Target#msg}
+- {Cinch::Target#privmsg}
+- {Cinch::Target#safe_msg}
+- {Cinch::Target#safe_privmsg}
+- {Cinch::User#whois}
+- {Cinch::Helpers#Color}
+
+Additionally, the following method is deprecated and will be removed
+in the future:
+
+- {Cinch::Channel#to_str}
+
 # What has changed in 2.1?
 1. Color stripping
 1. Per group hooks
@@ -11,12 +59,13 @@
 
 ## Color stripping
 
-The new method {Cinch::Utilities::String.strip_colors} allows removal
-of mIRC color codes from messages.
+The new method <del>`Cinch::Utilities::String.strip_colors`</del>
+{Cinch::Formatting.unformat} allows removal of mIRC color codes from
+messages.
 
 Additionally, a new match option called `strip_colors` makes it
 possible to automatically and temporarily strip color codes before
-attemping to match a message.
+attempting to match a message.
 
 ## Per group hooks
 

data/docs/common_tasks.md

@@ -4,7 +4,7 @@
 # Checking if a user is online
 
 Cinch by itself tries to keep track of the online state of users.
-Whenever it sees someone speak, change his nick or be in a channel the
+Whenever it sees someone speak, change their nick or be in a channel the
 bot is also in, it'll set the user to being online. And when a user
 quits, gets killed or cannot be whoised/contacted, its state will be
 set to offline.

data/examples/basic/autovoice.rb

@@ -5,6 +5,8 @@ require 'cinch'
 #
 # Enable with !autovoice on
 # Disable with !autovoice off
+#
+# It starts out disabled.
 
 bot = Cinch::Bot.new do
   configure do |c|
@@ -12,8 +14,6 @@ bot = Cinch::Bot.new do
     c.server          = "irc.freenode.org"
     c.verbose         = true
     c.channels        = ["#cinch-bots"]
-
-    @autovoice        = true
   end
 
   on :join do |m|

data/examples/basic/google.rb

@@ -15,7 +15,7 @@ bot = Cinch::Bot.new do
     # or "No results found" otherwise
     def google(query)
       url = "http://www.google.com/search?q=#{CGI.escape(query)}"
-      res = Nokogiri::HTML(open(url)).at("h3.r")
+      res = Nokogiri.parse(open(url).read).at("h3.r")
 
       title = res.text
       link = res.at('a')[:href]

data/examples/basic/join_part.rb

@@ -1,18 +1,18 @@
 require 'cinch'
 
+# Who should be able to access these plugins
+$admin = "injekt"
+
 bot = Cinch::Bot.new do
   configure do |c|
     c.server   = "irc.freenode.org"
     c.nick     = "CinchBot"
     c.channels = ["#cinch-bots"]
-
-    # Who should be able to access these plugins
-    @admin = "injekt"
   end
 
   helpers do
     def is_admin?(user)
-      true if user.nick == @admin
+      true if user.nick == $admin
     end
   end
 

data/examples/basic/memo.rb

@@ -8,29 +8,29 @@ class Memo < Struct.new(:nick, :channel, :text, :time)
   end
 end
 
+$memos = {}
+
 bot = Cinch::Bot.new do
   configure do |c|
     c.server = "irc.freenode.org"
     c.channels = ["#cinch-bots"]
-
-    @memos = {}
   end
 
   on :message do |m|
-    if @memos.has_key?(m.user.nick)
-      m.user.send @memos.delete(m.user.nick).to_s
+    if $memos.has_key?(m.user.nick)
+      m.user.send $memos.delete(m.user.nick).to_s
     end
   end
 
   on :message, /^!memo (.+?) (.+)/ do |m, nick, message|
-    if @memos.key?(nick)
+    if $memos.key?(nick)
       m.reply "There's already a memo for #{nick}. You can only store one right now"
     elsif nick == m.user.nick
       m.reply "You can't leave memos for yourself.."
     elsif nick == bot.nick
       m.reply "You can't leave memos for me.."
     else
-      @memos[nick] = Memo.new(m.user.nick, m.channel, message, Time.now)
+      $memos[nick] = Memo.new(m.user.nick, m.channel, message, Time.now)
       m.reply "Added memo for #{nick}"
     end
   end

data/examples/basic/seen.rb

@@ -6,17 +6,17 @@ class Seen < Struct.new(:who, :where, :what, :time)
   end
 end
 
+$users = {}
+
 bot = Cinch::Bot.new do
   configure do |c|
     c.server   = 'irc.freenode.org'
     c.channels = ["#cinch-bots"]
-
-    @users = {}
   end
 
   # Only log channel messages
   on :channel do |m|
-    @users[m.user.nick] = Seen.new(m.user.nick, m.channel, m.message, Time.new)
+    $users[m.user.nick] = Seen.new(m.user.nick, m.channel, m.message, Time.new)
   end
 
   on :channel, /^!seen (.+)/ do |m, nick|
@@ -24,8 +24,8 @@ bot = Cinch::Bot.new do
       m.reply "That's me!"
     elsif nick == m.user.nick
       m.reply "That's you!"
-    elsif @users.key?(nick)
-      m.reply @users[nick].to_s
+    elsif $users.key?(nick)
+      m.reply $users[nick].to_s
     else
       m.reply "I haven't seen #{nick}"
     end

data/examples/plugins/google.rb

@@ -9,7 +9,7 @@ class Google
 
   def search(query)
     url = "http://www.google.com/search?q=#{CGI.escape(query)}"
-    res = Nokogiri::HTML(open(url)).at("h3.r")
+    res = Nokogiri.parse(open(url).read).at("h3.r")
 
     title = res.text
     link = res.at('a')[:href]

data/examples/plugins/last_nick.rb

@@ -5,8 +5,8 @@ class Nickchange
   listen_to :nick
 
   def listen(m)
-    # This will send a PM to the user who changed his nick and inform
-    # him of his old nick.
+    # This will send a PM to the user who changed their nick and inform
+    # them of their old nick.
     m.reply "Your old nick was: #{m.user.last_nick}" ,true
   end
 end

data/lib/cinch.rb

@@ -1,6 +1,5 @@
 require 'cinch/version'
 require 'cinch/utilities/kernel'
-require 'cinch/utilities/string'
 require 'cinch/utilities/deprecation'
 require 'cinch/utilities/encoding'
 require 'cinch/bot'

data/lib/cinch/channel.rb

@@ -332,6 +332,21 @@ module Cinch
       @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=}.
     #
@@ -388,17 +403,34 @@ module Cinch
       @users.clear
     end
 
-    def msg(text, notice = false)
+    # @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.gsub!(/[\x02\x1F\x16\x0F]|\x03\d{2}(,\d{2})?/, "")
+        text = Cinch::Formatting.unformat(text)
       end
       super(text, notice)
     end
-    alias_method :send, :msg
-    alias_method :privmsg, :msg
+    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
@@ -406,10 +438,19 @@ module Cinch
     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
+    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

data/lib/cinch/formatting.rb

@@ -1,6 +1,6 @@
 module Cinch
-  # This module can be used for adding colors and formatting to
-  # messages.
+  # This module can be used for adding and removing colors and
+  # formatting to/from messages.
   #
   # The format codes used are those defined by mIRC, which are also
   # the ones supported by most clients.
@@ -74,7 +74,7 @@ module Cinch
     #   When supplying two colors, the first will be used for the
     #   foreground and the second for the background.
     # @param [String] string The string to format.
-    # @return [String] The formatted string
+    # @return [String] the formatted string
     # @since 2.0.0
     # @raise [ArgumentError] When passing more than two colors as arguments.
     # @see Helpers#Format Helpers#Format for easier access to this method.
@@ -110,5 +110,16 @@ module Cinch
       string.gsub!(/#{Attributes[:reset]}/, Attributes[:reset] + prepend)
       return prepend + string + append
     end
+
+    # Deletes all mIRC formatting codes from the string. This strips
+    # formatting for bold, underline and so on, as well as color
+    # codes. This does include removing the numeric arguments.
+    #
+    # @param [String] string The string to filter
+    # @return [String] The filtered string
+    # @since 2.2.0
+    def self.unformat(string)
+      string.gsub(/[\x02\x0f\x16\x1f\x12]|\x03(\d{1,2}(,\d{1,2})?)?/, '')
+    end
   end
 end

data/lib/cinch/helpers.rb

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 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
@@ -182,7 +183,48 @@ module Cinch
     def Format(*settings, string)
       Formatting.format(*settings, string)
     end
-    alias_method :Color, :Format
+    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\x10-\x1f\x7f]/, '')
+    end
+
+    # (see Formatting.unformat)
+    def Unformat(string)
+      Formatting.unformat(string)
+    end
 
     # @endgroup
   end

data/lib/cinch/irc.rb

@@ -632,7 +632,7 @@ module Cinch
     def on_313(msg, events)
       # RPL_WHOISOPERATOR
       user = User(msg.params[1])
-      @whois_updates[user].merge!({:oper? => true})
+      update_whois(user, {:oper? => true})
     end
 
     def on_317(msg, events)
@@ -648,21 +648,21 @@ module Cinch
       # RPL_ENDOFWHOIS
       user = User(msg.params[1])
 
-      if @whois_updates[user]
-        if @whois_updates[user].empty? && !user.attr(:unknown?, true, true)
-          user.end_of_whois(nil)
-        else
-          user.end_of_whois(@whois_updates[user])
-        end
-        @whois_updates.delete user
+      if @whois_updates[user].nil? ||
+         (@whois_updates[user].empty? && !user.attr(:unknown?, true, true))
+        user.end_of_whois(nil)
+        return
       end
+
+      user.end_of_whois(@whois_updates[user])
+      @whois_updates.delete user
     end
 
     def on_319(msg, events)
       # RPL_WHOISCHANNELS
       user     = User(msg.params[1])
       channels = msg.params[2].scan(/[#{@isupport["CHANTYPES"].join}][^ ]+/o).map {|c| Channel(c) }
-      @whois_updates[user].merge!({:channels => channels})
+      update_whois(user, {:channels => channels})
     end
 
     def on_324(msg, events)
@@ -685,8 +685,7 @@ module Cinch
       # RPL_WHOISACCOUNT
       user     = User(msg.params[1])
       authname = msg.params[2]
-
-      @whois_updates[user].merge!({:authname => authname})
+      update_user(user, {:authname => authname})
     end
 
     def on_331(msg, events)
@@ -851,7 +850,7 @@ module Cinch
 
     def on_671(msg, events)
       user = User(msg.params[1])
-      @whois_updates[user].merge!({:secure? => true})
+      update_whois(user, {:secure? => true})
     end
 
     # @since 2.0.0

data/lib/cinch/message.rb

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 require "time"
-require "cinch/utilities/string"
+require "cinch/formatting"
 
 module Cinch
   # This class serves two purposes. For one, it simply
@@ -149,7 +149,7 @@ module Cinch
       end
 
       if strip_colors
-        text = Cinch::Utilities::String.strip_colors(text)
+        text = Cinch::Formatting.unformat(text)
       end
 
       @matches[type][regexp] ||= text.match(regexp)
@@ -226,7 +226,6 @@ module Cinch
     end
 
     def parse_params(raw_params)
-      raw_params = raw_params.strip
       params     = []
       if match = raw_params.match(/(?:^:| :)(.*)$/)
         params = match.pre_match.split(" ")
@@ -250,12 +249,19 @@ module Cinch
 
     def parse_channel
       # has to be called after parse_params
+      return nil if @params.empty?
+
       case @command
       when "INVITE", Constants::RPL_CHANNELMODEIS.to_s, Constants::RPL_BANLIST.to_s
         @bot.channel_list.find_ensured(@params[1])
       when Constants::RPL_NAMEREPLY.to_s
         @bot.channel_list.find_ensured(@params[2])
       else
+        # Note that this will also find channels for messages that
+        # don't actually include a channel parameter. For example
+        # `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)

data/lib/cinch/mode_parser.rb

@@ -1,3 +1,5 @@
+require "cinch/exceptions"
+
 module Cinch
   # @api private
   # @since 1.1.0
@@ -8,11 +10,11 @@ module Cinch
     #   A mapping describing which modes require parameters
     def self.parse_modes(modes, params, param_modes = {})
       if modes.size == 0
-        raise InvalidModeString, 'Empty mode string'
+        raise Exceptions::InvalidModeString, 'Empty mode string'
       end
 
       if modes[0] !~ /[+-]/
-        raise InvalidModeString, "Malformed modes string: %s" % modes
+        raise Exceptions::InvalidModeString, "Malformed modes string: %s" % modes
       end
 
       changes = []
@@ -23,7 +25,7 @@ module Cinch
       modes.each_char do |ch|
         if ch =~ /[+-]/
           if count == 0
-            raise InvalidModeString, 'Empty mode sequence: %s' % modes
+            raise Exceptions::InvalidModeString, 'Empty mode sequence: %s' % modes
           end
 
           direction = case ch
@@ -39,7 +41,7 @@ module Cinch
             if params.size > 0
               param = params.shift
             else
-              raise InvalidModeString, 'Not enough parameters: %s' % ch.inspect
+              raise Exceptions::InvalidModeString, 'Not enough parameters: %s' % ch.inspect
             end
           end
           changes << [direction, ch, param]
@@ -48,11 +50,11 @@ module Cinch
       end
 
       if params.size > 0
-        raise InvalidModeString, 'Too many parameters: %s %s' % [modes, params].inspect
+        raise Exceptions::InvalidModeString, 'Too many parameters: %s %s' % [modes, params]
       end
 
       if count == 0
-        raise InvalidModeString, 'Empty mode sequence: %r' % modes
+        raise Exceptions::InvalidModeString, 'Empty mode sequence: %s' % modes
       end
 
       return changes

data/lib/cinch/target.rb

@@ -27,7 +27,11 @@ module Cinch
     # @param [Boolean] notice Use NOTICE instead of PRIVMSG?
     # @return [void]
     # @see #safe_msg
-    def msg(text, notice = false)
+    # @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, put splitting into own
+      # method
       text = text.to_s
       split_start = @bot.config.message_split_start || ""
       split_end   = @bot.config.message_split_end   || ""
@@ -58,25 +62,55 @@ module Cinch
         end
       end
     end
-    alias_method :send, :msg
-    alias_method :privmsg, :msg
+    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", "Target#msg", "Target#send")
+      send(*args)
+    end
+
+    # @deprecated
+    def privmsg(*args)
+      Cinch::Utilities::Deprecation.print_deprecation("2.2.0", "Target#privmsg", "Target#send")
+      send(*args)
+    end
 
-    # Like {#msg}, but remove any non-printable characters from
+    # Like {#send}, but remove any non-printable characters from
     # `text`. The purpose of this method is to send text of untrusted
     # sources, like other users or feeds.
     #
     # Note: this will **break** any mIRC color codes embedded in the
-    # string.
+    # string. For more fine-grained control, use
+    # {Helpers#Sanitize} and
+    # {Formatting.unformat} directly.
     #
-    # @return (see #msg)
-    # @param (see #msg)
-    # @see #msg
-    # @todo Handle mIRC color codes more gracefully.
-    def safe_msg(text, notice = false)
-      msg(Cinch::Utilities::String.filter_string(text), notice)
+    # @return (see #send)
+    # @param (see #send)
+    # @see #send
+    def safe_send(text, notice = false)
+      send(Cinch::Helpers.sanitize(text), notice)
+    end
+    alias_method :safe_msg, :safe_send # deprecated
+    alias_method :safe_privmsg, :safe_msg # deprecated
+    undef_method(:safe_msg) # yardoc hack
+    undef_method(:safe_privmsg) # yardoc hack
+
+    # @deprecated
+    def safe_msg(*args)
+      Cinch::Utilities::Deprecation.print_deprecation("2.2.0", "Target#safe_msg", "Target#safe_send")
+      send(*args)
     end
-    alias_method :safe_privmsg, :safe_msg
-    alias_method :safe_send, :safe_msg
+
+    # @deprecated
+    def safe_privmsg(*args)
+      Cinch::Utilities::Deprecation.print_deprecation("2.2.0", "Target#safe_privmsg", "Target#safe_send")
+      send(*args)
+    end
+
 
     # Like {#safe_msg} but for notices.
     #
@@ -84,7 +118,6 @@ module Cinch
     # @param (see #safe_msg)
     # @see #safe_notice
     # @see #notice
-    # @todo (see #safe_msg)
     def safe_notice(text)
       safe_msg(text, true)
     end
@@ -103,14 +136,15 @@ module Cinch
     # untrusted sources, like other users or feeds.
     #
     # Note: this will **break** any mIRC color codes embedded in the
-    # string.
+    # string. For more fine-grained control, use
+    # {Helpers#Sanitize} and
+    # {Formatting.unformat} directly.
     #
     # @param (see #action)
     # @return (see #action)
     # @see #action
-    # @todo Handle mIRC color codes more gracefully.
     def safe_action(text)
-      action(Cinch::Utilities::String.filter_string(text))
+      action(Cinch::Helpers.Sanitize(text))
     end
 
     # Send a CTCP to the target.

data/lib/cinch/user.rb

@@ -239,7 +239,9 @@ module Cinch
     # received, the object will be set back to synced.
     #
     # @return [void]
-    def whois
+    # @note The alias `whois` is deprecated and will be removed in a
+    #   future version.
+    def refresh
       return if @in_whois
       @data.keys.each do |attr|
         unsync attr
@@ -252,7 +254,14 @@ module Cinch
         @bot.irc.send "WHOIS #@name #@name"
       end
     end
-    alias_method :refresh, :whois
+    alias_method :whois, :refresh # deprecated
+    undef_method(:whois) # yardoc hack
+
+    # @deprecated
+    def whois
+      Cinch::Utilities::Deprecation.print_deprecation("2.2.0", "User#whois", "User#refresh")
+      refresh
+    end
 
     # @param [Hash, nil] values A hash of values gathered from WHOIS,
     #   or `nil` if no data was returned
@@ -463,7 +472,7 @@ module Cinch
       @last_nick, @name = @name, new_nick
       # Unsync authname because some networks tie authentication to
       # the nick, so the user might not be authenticated anymore after
-      # changing his nick
+      # changing their nick
       unsync(:authname)
       @bot.user_list.update_nick(self)
     end

data/lib/cinch/user_list.rb

@@ -7,12 +7,12 @@ module Cinch
   class UserList < CachedList
     # Finds or creates a user.
     # @overload find_ensured(nick)
-    #   Finds or creates a user based on his nick.
+    #   Finds or creates a user based on their nick.
     #
     #   @param [String] nick The user's nickname
     #   @return [User]
     # @overload find_ensured(user, nick, host)
-    #   Finds or creates a user based on his nick but already
+    #   Finds or creates a user based on their nick but already
     #   setting user and host.
     #
     #   @param [String] user The username

data/lib/cinch/utilities/deprecation.rb

@@ -1,10 +1,14 @@
 module Cinch
-  # @since 2.0.0
-  # @api private
   module Utilities
+    # @since 2.0.0
+    # @api private
     module Deprecation
-      def self.print_deprecation(version, method)
-        $stderr.puts "Deprecation warning: Beginning with version #{version}, #{method} should not be used anymore."
+      def self.print_deprecation(version, method, instead = nil)
+        s = "Deprecation warning: Beginning with version #{version}, #{method} should not be used anymore."
+        if instead != nil
+          s << " Use ${instead} instead."
+        end
+        $stderr.puts s
         $stderr.puts caller
       end
     end

data/lib/cinch/utilities/encoding.rb

@@ -1,7 +1,7 @@
 module Cinch
-  # @since 2.0.0
-  # @api private
   module Utilities
+    # @since 2.0.0
+    # @api private
     module Encoding
       def self.encode_incoming(string, encoding)
         string = string.dup
@@ -27,27 +27,10 @@ module Cinch
       def self.encode_outgoing(string, encoding)
         string = string.dup
         if encoding == :irc
-          # If your text contains only characters that fit inside the CP1252
-          # code page (aka Windows Latin-1), the entire line will be sent
-          # that way. mIRC users should see it correctly. XChat users who
-          # are using UTF-8 will also see it correctly, because it will fail
-          # UTF-8 validation and will be assumed to be CP1252, even by older
-          # XChat versions.
-          #
-          # If the text doesn't fit inside the CP1252 code page, (for example if you
-          # type Eastern European characters, or Russian) it will be sent as UTF-8. Only
-          # UTF-8 capable clients will be able to see these characters correctly
-          #
-          # (from http://xchat.org/encoding/#hybrid)
-          begin
-            string.encode!("CP1252")
-          rescue ::Encoding::UndefinedConversionError
-          end
-        else
-          string.encode!(encoding, {:invalid => :replace, :undef => :replace}).force_encoding("ASCII-8BIT")
+          encoding = "UTF-8"
         end
 
-        return string
+        return string.encode!(encoding, {:invalid => :replace, :undef => :replace}).force_encoding("ASCII-8BIT")
       end
     end
   end

data/lib/cinch/utilities/kernel.rb

@@ -1,7 +1,7 @@
 module Cinch
-  # @since 2.0.0
-  # @api private
   module Utilities
+    # @since 2.0.0
+    # @api private
     module Kernel
       # @return [Object]
       def self.string_to_const(s)

data/lib/cinch/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cinch
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-27 00:00:00.000000000 Z
+date: 2014-12-31 00:00:00.000000000 Z
 dependencies: []
 description: A simple, friendly DSL for creating IRC bots
 email:
@@ -69,7 +69,6 @@ files:
 - lib/cinch/version.rb
 - lib/cinch/utilities/deprecation.rb
 - lib/cinch/utilities/kernel.rb
-- lib/cinch/utilities/string.rb
 - lib/cinch/utilities/encoding.rb
 - lib/cinch/constants.rb
 - lib/cinch/mode_parser.rb

data/lib/cinch/utilities/string.rb

@@ -1,17 +0,0 @@
-module Cinch
-  # @since 2.0.0
-  # @api private
-  module Utilities
-    module String
-      # @return [String]
-      # @todo Handle mIRC color codes more gracefully.
-      def self.filter_string(string)
-        string.gsub(/[\x00-\x1f]/, '')
-      end
-
-      def self.strip_colors(string)
-        string.gsub(/[\x02\x0f\x16\x1f\x12]|\x03(\d{1,2}(,\d{1,2})?)?/, '')
-      end
-    end
-  end
-end