ircsupport 0.1.0

data/.gitignore

@@ -0,0 +1,6 @@
+coverage/
+.yardoc/
+doc/
+pkg/
+Gemfile.lock
+.rbx/

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - ruby-head
+  - jruby-19mode
+  - jruby-head
+  - rbx-19mode

data/CHANGES.md

@@ -0,0 +1,3 @@
+0.1.0
+-----
+* Initial release

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Hinrik Örn Sigurðsson
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,134 @@
+IRCSupport
+==========
+
+[![Build Status](https://secure.travis-ci.org/hinrik/ircsupport.png?branch=master)](http://travis-ci.org/hinrik/ircsupport)
+
+IRCSupport provides everything you need to work with the IRC protocol and its
+widely-used extensions. It is meant to be a building block for higher-level
+libraries that use IRC (clients or servers). There are a bunch of IRC
+client/bot libraries for Ruby out there, and they all implement their own
+stuff for dealing with the IRC protocol. Why not keep it in one place?
+
+Features
+--------
+
+* __Complete:__ Includes support for all protocol standards used by modern
+  IRC clients and servers, including:
+ * RFC1459
+ * RFC2812 & RFC2813
+ * CTCP
+ * DCC (CHAT, SEND, ACCEPT, RESUME)
+ * RPL\_ISUPPORT (draft-brocklesby-irc-isupport-03)
+ * CAP capabilities extension (draft-mitchell-irc-capabilities-02)
+ * mIRC/ECMA-48/RGB color and formatting codes
+* __Tested:__ A heavy emphasis is placed on testing the code. It generally
+  has 100% test coverage.
+* __Flexible:__ The tools provided by IRCSupport are flexible and modular,
+  and should encourage reuse.
+
+Usage
+-----
+
+Here are some examples of using IRCSupport:
+
+```ruby
+require 'ircsupport'
+
+line = ':foo!bar@baz.com PRIVMSG #the_room :Greetings, everyone!'
+irc_parser = IRCSupport::Parser.new
+msg = irc_parser.parse(line)
+
+msg.channel
+# => '#the_room'
+
+msg.sender
+# => 'foo!bar@baz'
+
+msg.is_action?
+# => false
+
+msg.type
+# => 'private_msg'
+
+IRCSupport::Validations.valid_nick_name?("Foo{}Bar[]")
+# => true
+
+IRCSupport::Validations.valid_nick_name?("123FooBar")
+# => false
+
+IRCSupport::Numerics.numeric_to_name('005')
+# => 'RPL_ISUPPORT'
+
+# any module can also be mixed into your class
+include IRCSupport::Numerics
+numeric_to_name('001')
+# => 'RPL_WELCOME'
+```
+
+Components
+----------
+
+### `IRCSupport::Parser`
+
+This class is a complete parser for the IRC protocol. It can provide you with
+rich objects which encapsulate all the information of a message in handy
+methods.
+
+### `IRCSupport::Case`
+
+A module that provides functions that conversion between various IRC
+casemappings.
+
+### `IRCSupport::Encoding`
+
+A module that provides functions to encode or decode IRC messages.
+
+### `IRCSupport::Formatting`
+
+A module that provides functions for detecting, stripping, and constructing
+strings with IRC color and formatting codes.
+
+### `IRCSupport::Masks`
+
+A module that provides functions to deal with IRC masks.
+
+### `IRCSupport::Modes`
+
+A module that provides functions to work with mode strings.
+
+### `IRCSupport::Numerics`
+
+A module that provides functions to look up the names of IRC numerics and
+vice versa.
+
+### `IRCSupport::Validations`
+
+A module that provides functions to validate various IRC strings.
+
+Supported platforms
+-------------------
+
+IRCSupport works on any Ruby 1.9-compatible VM. As of this writing, Rubinius'
+and JRuby's encoding support is not complete, so some of the functions in
+`IRCSupport::Encoding` will not work on those platforms.
+
+Contributing
+------------
+
+* Fork this repository on github
+* Make your changes and send me a pull request
+* If I like them I'll merge them
+* If I've accepted a patch, feel free to ask for commit access
+
+Kudos
+-----
+Those go to the authors of the [`IRC::Utils`](https://metacpan.org/module/IRC::Utils)
+Perl module, on which much of this library's functionality is based. Same for
+the authors of [`cinch`](https://github.com/cinchrb/cinch), from which a few
+functions were borrowed.
+
+License
+-------
+
+Copyright (c) 2012 Hinrik Örn Sigurðsson. Distributed under the MIT License.
+See LICENSE.txt for further details.

data/Rakefile

@@ -0,0 +1,16 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'yard'
+
+task :default => :test
+
+Rake::TestTask.new(:test) do |task|
+  task.libs << "test"
+  task.test_files = FileList['test/test_coverage.rb', 'test/*_test.rb']
+  task.verbose = true
+end
+
+YARD::Rake::YardocTask.new do |task|
+  task.files = ['lib/**/*.rb', '-', 'CHANGES.md', 'LICENSE.txt']
+  task.options = ['--no-private', '--markup=markdown']
+end

data/ircsupport.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+$:.push File.expand_path("../lib", __FILE__)
+require 'ircsupport/version'
+
+Gem::Specification.new do |gem|
+  gem.name        = "ircsupport"
+  gem.version     = IRCSupport::VERSION
+  gem.authors     = ["Hinrik Örn Sigurðsson"]
+  gem.email       = ["hinrik.sig@gmail.com"]
+  gem.homepage    = "https://github.com/hinrik/ircsupport"
+  gem.summary     = "An IRC protocol library"
+  gem.description = "IRCSupport provides tools for dealing with the IRC protocol."
+  gem.licenses    = ['MIT']
+
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- test/*`.split("\n")
+  gem.require_path  = "lib"
+  gem.has_rdoc      = "yard"
+  gem.required_ruby_version = '>= 1.9.1'
+
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "simplecov"
+  gem.add_development_dependency "yard", ">= 0.7.5"
+  gem.add_development_dependency "minitest", ">= 2.11.4"
+  gem.add_development_dependency "turn"
+end

data/lib/ircsupport.rb

@@ -0,0 +1,10 @@
+require 'ircsupport/version'
+require 'ircsupport/case'
+require 'ircsupport/encoding'
+require 'ircsupport/formatting'
+require 'ircsupport/masks'
+require 'ircsupport/message'
+require 'ircsupport/modes'
+require 'ircsupport/numerics'
+require 'ircsupport/parser'
+require 'ircsupport/validations'

data/lib/ircsupport/case.rb

@@ -0,0 +1,84 @@
+module IRCSupport
+  module Case
+    # @private
+    @@ascii_map = ['a-z', 'A-Z']
+    # @private
+    @@rfc1459_map = ['a-z{}^|', 'A-Z[]~\\']
+    # @private
+    @@strict_rfc1459_map = ['a-z{}|', 'A-Z[]\\']
+
+    # @param [String] irc_string An IRC string (nickname, channel, etc).
+    # @param [Symbol] casemapping An IRC casemapping.
+    # Like {#irc_upcase}, but modifies the string in place.
+    # @return [String] An upper case version of the IRC string according to
+    #   the casemapping.
+    def irc_upcase!(irc_string, casemapping = :rfc1459)
+      case casemapping
+      when :ascii
+        irc_string.tr!(*@@ascii_map)
+      when :rfc1459
+        irc_string.tr!(*@@rfc1459_map)
+      when :'strict-rfc1459'
+        # the backslash must be last, otherwise it causes issues
+        irc_string.tr!(*@@strict_rfc1459_map)
+      else
+        raise ArgumentError, "Unsupported casemapping #{casemapping}"
+      end
+
+      return irc_string
+    end
+
+    # @param [String] irc_string An IRC string (nickname, channel, etc)
+    # @param [Symbol] casemapping An IRC casemapping
+    # @return [String] An upper case version of the IRC string according to
+    #   the casemapping.
+    def irc_upcase(irc_string, casemapping = :rfc1459)
+      result = irc_string.dup
+      irc_upcase!(result, casemapping)
+      return result
+    end
+
+    # @param [String] irc_string An IRC string (nickname, channel, etc)
+    # @param [Symbol] casemapping An IRC casemapping
+    # Like {#irc_downcase}, but modifies the string in place.
+    # @return [String] A lower case version of the IRC string according to
+    #   the casemapping
+    def irc_downcase!(irc_string, casemapping = :rfc1459)
+      case casemapping
+      when :ascii
+        irc_string.tr!(*@@ascii_map.reverse)
+      when :rfc1459
+        irc_string.tr!(*@@rfc1459_map.reverse)
+      when :'strict-rfc1459'
+        # the backslash must be last, otherwise it causes issues
+        irc_string.tr!(*@@strict_rfc1459_map.reverse)
+      else
+        raise ArgumentError, "Unsupported casemapping #{casemapping}"
+      end
+
+      return irc_string
+    end
+
+    # @param [String] irc_string An IRC string (nickname, channel, etc).
+    # @param [Symbol] casemapping An IRC casemapping.
+    # @return [String] A lower case version of the IRC string according to
+    #   the casemapping
+    def irc_downcase(irc_string, casemapping = :rfc1459)
+      result = irc_string.dup
+      irc_downcase!(result, casemapping)
+      return result
+    end
+
+    # @param [String] first The first IRC string to compare.
+    # @param [String] second The second IRC string to compare.
+    # @param [Symbol] casemapping The IRC casemappig to use for the comparison.
+    # @return [Boolean] Will be `true` if the strings only differ in case or
+    #   not all, but `false` otherwise.
+    def irc_eql?(first, second, casemapping = :rfc1459)
+      return irc_upcase(first, casemapping) == irc_upcase(second, casemapping)
+    end
+
+    module_function :irc_upcase, :irc_upcase!, :irc_downcase,
+                    :irc_downcase!, :irc_eql?
+  end
+end

data/lib/ircsupport/encoding.rb

@@ -0,0 +1,74 @@
+module IRCSupport
+  module Encoding
+    # @param [String] string The IRC string you want to decode.
+    # @param [Symbol] encoding The source encoding.
+    # @return [String] A UTF-8 Ruby string.
+    def decode_irc(string, encoding = :irc)
+      string = string.dup
+      decode_irc!(string, encoding)
+    end
+
+    # @param [String] string The string you want to encode.
+    # @param [Symbol] encoding The target encoding.
+    # @return [String] A string encoded in the encoding you specified.
+    def encode_irc(string, encoding = :irc)
+      string = string.dup
+      encode_irc!(string, encoding)
+    end
+
+    # @param [String] string The IRC string you want to decode.
+    # @param [Symbol] encoding The source encoding.
+    # Like {#decode_irc}, but modifies the string in place.
+    # @return [String] A UTF-8 Ruby string.
+    def decode_irc!(string, encoding = :irc)
+      if encoding == :irc
+        # If incoming text is valid UTF-8, it will be interpreted as
+        # such. If it fails validation, a CP1252 -> UTF-8 conversion
+        # is performed. This allows you to see non-ASCII from mIRC
+        # users (non-UTF-8) and other users sending you UTF-8.
+        #
+        # (from http://xchat.org/encoding/#hybrid)
+        string.force_encoding("UTF-8")
+        if !string.valid_encoding?
+          string.force_encoding("CP1252").encode!("UTF-8", {:invalid => :replace, :undef => :replace})
+        end
+      else
+        string.force_encoding(encoding).encode!({:invalid => :replace, :undef => :replace})
+        string = string.chars.select { |c| c.valid_encoding? }.join
+      end
+
+      return string
+    end
+
+    # @param [String] string The string you want to encode.
+    # @param [Symbol] encoding The target encoding.
+    # Like {#encode_irc}, but modifies the string in place.
+    # @return [String] A string encoded in the encoding you specified.
+    def encode_irc!(string, encoding = :irc)
+      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")
+      end
+
+      return string
+    end
+
+    module_function :decode_irc, :decode_irc!, :encode_irc, :encode_irc!
+  end
+end

data/lib/ircsupport/formatting.rb

@@ -0,0 +1,149 @@
+module IRCSupport
+  module Formatting
+    # @private
+    @@color        = /[\x03\x04\x1b]/
+    # @private
+    @@formatting   = /[\x02\x06\x11\x16\x1d\x1f]/
+    # @private
+    @@mirc_color   = / \x03 (?: ,\d{1,2} | \d{1,2} (?: ,\d{1,2})? )? /x
+    # @private
+    @@rgb_color    = /\x04[0-9a-fA-F]{0,6}/
+    # @private
+    @@ecma48_color = /\x1b\[.*?[\x00-\x1f\x40-\x7e]/
+    # @private
+    @@normal       = /\x0f/
+
+    # @private
+    @@attributes = {
+      reset:      15.chr,
+      bold:       2.chr,
+      underline:  31.chr,
+      underlined: 31.chr,
+      inverse:    22.chr,
+      reverse:    22.chr,
+      reversed:   22.chr,
+      italic:     29.chr,
+      fixed:      17.chr,
+      blink:      6.chr,
+    }
+
+    # @private
+    @@colors = {
+      white:  "00",
+      black:  "01",
+      blue:   "02",
+      green:  "03",
+      red:    "04",
+      brown:  "05",
+      purple: "06",
+      orange: "07",
+      yellow: "08",
+      lime:   "09",
+      teal:   "10",
+      aqua:   "11",
+      royal:  "12",
+      pink:   "13",
+      grey:   "14",
+      silver: "15",
+    }
+
+    # @param [String] string The string you want to check.
+    # @return [Boolean] Will be true if the string contains IRC color codes.
+    def has_color?(string)
+      return true if string =~ @@color
+      return false
+    end
+
+    # @param [String] string The string you want to check.
+    # @return [Boolean] Will be true if the string contains IRC formatting codes.
+    def has_formatting?(string)
+      return true if string =~ @@formatting
+      return false
+    end
+
+    # @param [String] string The string you want to strip.
+    # Like {#strip_color}, but modifies the string in place.
+    # @return [String] A string stripped of all IRC color codes.
+    def strip_color!(string)
+      [@@mirc_color, @@rgb_color, @@ecma48_color].each do |pattern|
+        string.gsub!(pattern, '')
+      end
+      # strip cancellation codes too if there are no formatting codes
+      string.gsub!(@@normal) if !has_color?(string)
+      return string
+    end
+
+    # @param [String] string The string you want to strip.
+    # @return [String] A string stripped of all IRC color codes.
+    def strip_color(string)
+      string = string.dup
+      return strip_color!(string)
+    end
+
+    # @param [String] string The string you want to strip.
+    # Like {#strip_formatting}, but modifies the string in place.
+    # @return [String] A string stripped of all IRC formatting codes.
+    def strip_formatting!(string)
+      string.gsub!(@@formatting, '')
+      # strip cancellation codes too if there are no color codes
+      string.gsub!(@@normal) if !has_color?(string)
+      return string
+    end
+
+    # @param [String] string The string you want to strip.
+    # @return [String] A string stripped of all IRC formatting codes.
+    def strip_formatting(string)
+      string = string.dup
+      return strip_formatting!(string)
+    end
+
+    # @param [*Array] settings A list of color and formatting attributes you
+    #   want to apply.
+    # Like {#irc_format}, but modifies the string in place.
+    # @param [String] string A string you want to format.
+    # @return [String] A formatted string.
+    def irc_format!(*settings, string)
+      string = string.dup
+
+      attributes = settings.select {|k| @@attributes.has_key?(k)}.map {|k| @@attributes[k]}
+      colors = settings.select {|k| @@colors.has_key?(k)}.map {|k| @@colors[k]}
+      if colors.size > 2
+        raise ArgumentError, "At most two colors (foreground and background) might be specified"
+      end
+
+      attribute_string = attributes.join
+      color_string = if colors.empty?
+                       ""
+                     else
+                       "\x03#{colors.join(",")}"
+                     end
+
+      prepend = attribute_string + color_string
+      append = @@attributes[:reset]
+
+      # attributes act as toggles, so e.g. underline+underline = no
+      # underline. We thus have to delete all duplicate attributes
+      # from nested strings.
+      string.delete!(attribute_string)
+
+      # Replace the reset code of nested strings to continue the
+      # formattings of the outer string.
+      string.gsub!(/#{@@attributes[:reset]}/, @@attributes[:reset] + prepend)
+      string.insert(0, prepend)
+      string << append
+      return string
+    end
+
+    # @param [*Array] settings A list of color and formatting attributes you
+    #   want to apply.
+    # @param [String] string A string you want to format.
+    # @return [String] A formatted string.
+    def irc_format(*settings, string)
+      string = string.dup
+      return irc_format!(*settings, string)
+    end
+
+    module_function :has_color?, :has_formatting?, :strip_color, :strip_color!,
+                    :strip_formatting, :strip_formatting!, :irc_format
+  end
+end