irc_parser 0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2011 Emmanuel Oga
+
+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,105 @@
+# IRCParser
+
+A ruby 1.9.x parser for IRC messages which includes commands, errors and
+replies classese according to the IRC RFCs definitions.
+
+This library does not deal at all with networking.
+
+## Goals
+
+In every irc library I've seen people implement the various irc messages
+again and again.
+
+IRCParser tackles that boring task so the hard work in making the RFC
+compliant IRC messages can be shared across projects.
+
+## Anatomy of an IRC message
+
+All irc messages have the same structure:
+
+  [optional prefix] COMMAND_NAME [optional_param [optional_param2, ...]] [optional postfix]
+
+* The prefix always denotes a server or user name, and starts with ':'.
+* The params are completely optional. IRCParser gives all params
+  apropriate names reflecting those found on the RFCs.
+* The postfix is the last parameter. IRCParser sometimes aliases the
+  postfix to something more readable for some messages (e.g. 'body' for
+  PRIVMSG). The only kind of parameters which can embed spaces are the
+  postfixes.
+
+## Parsing Messages
+
+The parser can be run so it returns the raw components of an irc message
+([prefix, command, *params]), or an specific class for each kind of
+message constructed from those parts.
+
+The parser is quite strict so it will expect the IRC delimiters in all
+messages to parse (i.e. all messages must end with '\r\n').
+
+```ruby
+  require 'irc_parser'
+
+  # returns prefix, command, params. Notice final \r\n
+  IRCParser.parse_raw(":Angel PRIVMSG Wiz :Hello are you receiving this message?\r\n")
+
+  # => ["Angel", "PRIVMSG", ["Wiz", "Hello are you receiving this message ?"]]
+```
+
+To get a subclass of IRCParser::Message instead of an array of components:
+
+```ruby
+  require 'irc_parser/messages'
+  msg = IRCParser.parse(":Angel PRIVMSG Wiz :Hello are you receiving this message?\r\n")
+  # <IRCParser::Messages::Privmsg:0x00000001476370 @params=["Wiz", "Hello are you receiving this message?"], @prefix="Angel">
+
+  msg.identifier # => "PRIVMSG"
+  msg.to_sym     # => :priv_msg
+  msg.prefix     # => "Angel"
+  msg.params     # => ["Wiz", "Hello are you receiving this message?"]
+  msg.from       # => "Angel"
+  msg.target     # => "Wiz"
+  msg.body       # => "Hello are you receiving this message?"
+```
+
+## Generating Messages
+
+```ruby
+  msg = IRCParser::Messages::PrivMsg.new
+  msg.from   = "Wiz"
+  msg.target = "Angel"
+  msg.body   = "Hello World!"
+  msg.to_s   # => ":Wiz PRIVMSG Angel :Hello World!\r\n"
+```
+
+There is also a shortcut:
+
+```ruby
+  require 'irc_parser/messages'
+  msg = IRCParser.message(:privmsg) do |m|
+    msg.from   = "Wiz"
+    msg.target = "Angel"
+    msg.body   = "Hello World!"
+  end
+  msg.to_s # => ":Wiz PRIVMSG Angel :Hello World!\r\n"
+```
+
+## TODO
+
+* Documentation!
+* It would be nice to add support for parsing/generating extended mirc
+  messages.
+* Most severs/clients do not implement the messages exactly as defined
+  on the RFCs (sometimes http://www.mirc.net/raws/ was used as
+  reference). So, some messages may require adjustments to be usable
+  in the wild.
+* 1459 compliant, with some of the messages updated to the rfc 2812.
+  Fixes/updates are warmly welcome!
+
+## AUTHORS
+
+A lot of projects where reviewed while implementing this library.  I may
+or may not have stolen something from one of these, although off course
+I'm the only one to blame for the contents of this gem. If I forget
+about anyone please ping me so I can include you here.
+
+* Ragel parser and other portions where taken from irk (brodock/irk)

data/Rakefile

@@ -0,0 +1,155 @@
+require 'rubygems'
+require 'rake'
+require 'date'
+
+#############################################################################
+#
+# Helper functions
+#
+#############################################################################
+
+def name
+  @name ||= Dir['*.gemspec'].first.split('.').first
+end
+
+def version
+  line = File.read("lib/#{name}.rb")[/^\s*VERSION\s*=\s*.*/]
+  line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
+end
+
+def date
+  Date.today.to_s
+end
+
+def rubyforge_project
+  name
+end
+
+def gemspec_file
+  "#{name}.gemspec"
+end
+
+def gem_file
+  "#{name}-#{version}.gem"
+end
+
+def replace_header(head, header_name)
+  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{send(header_name)}'"}
+end
+
+#############################################################################
+#
+# Standard tasks
+#
+#############################################################################
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.ruby_opts = '-Ilib/ -Ispec/'
+  spec.pattern = 'spec/**/*_spec.rb'
+end
+
+begin
+  require 'simplecov'
+rescue LoadError
+  puts "simplecov gem is not available. Install it to get coverage reports"
+else
+  RSpec::Core::RakeTask.new(:simplecov) do |spec|
+    spec.ruby_opts = '-I. -Ilib/ -Ispec/ -rspec/support/simplecov'
+    spec.pattern = 'spec/**/*_spec.rb'
+  end
+end
+
+task :default => :spec
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -I ./lib/ -rubygems -r ./lib/#{name}.rb"
+end
+
+#############################################################################
+#
+# Custom tasks (add your own tasks here)
+#
+#############################################################################
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new do |yard|
+  end
+rescue LoadError
+  desc "generate documentation"
+  task :yard do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end
+
+desc "compile the ragel parser"
+task :ragel do
+  system("ragel -F1 -R lib/irc_parser/parser.rl")
+end
+
+#############################################################################
+#
+# Packaging tasks
+#
+#############################################################################
+
+task :release => [:ragel, :build] do
+  unless `git branch` =~ /^\* master$/
+    puts "You must be on the master branch to release!"
+    exit!
+  end
+  sh "git commit --allow-empty -a -m 'Release #{version}'"
+  sh "git tag v#{version}"
+  sh "git push origin master"
+  sh "git push --tags"
+  sh "gem push pkg/#{name}-#{version}.gem"
+end
+
+task :build => :gemspec do
+  sh "mkdir -p pkg"
+  sh "gem build #{gemspec_file}"
+  sh "mv #{gem_file} pkg"
+end
+
+task :gemspec => :validate do
+  # read spec file and split out manifest section
+  spec = File.read(gemspec_file)
+  head, manifest, tail = spec.split("  # = MANIFEST =\n")
+
+  # replace name version and date
+  replace_header(head, :name)
+  replace_header(head, :version)
+  replace_header(head, :date)
+  #comment this out if your rubyforge_project has a different name
+  replace_header(head, :rubyforge_project)
+
+  # determine file list from git ls-files
+  files = `git ls-files`.
+    split("\n").
+    sort.
+    reject { |file| file =~ /^\./ }.
+    reject { |file| file =~ /^(rdoc|pkg)/ }.
+    map { |file| "    #{file}" }.
+    join("\n")
+
+  # piece file back together and write
+  manifest = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = [head, manifest, tail].join("  # = MANIFEST =\n")
+  File.open(gemspec_file, 'w') { |io| io.write(spec) }
+  puts "Updated #{gemspec_file}"
+end
+
+task :validate do
+  libfiles = Dir['lib/*'] - ["lib/#{name}.rb", "lib/#{name}"]
+  unless libfiles.empty?
+    puts "Directory `lib` should only contain a `#{name}.rb` file and `#{name}` dir."
+    exit!
+  end
+  unless Dir['VERSION*'].empty?
+    puts "A `VERSION` file at root level violates Gem best practices."
+    exit!
+  end
+end

data/extra/benchmark.rb

@@ -0,0 +1,41 @@
+require 'irc_parser'
+require 'benchmark'
+
+MSG1 = "200 Wiz Link 1.10 destination.com next_server.net\r\n"
+MSG2 = "PRIVMSG #*.edu :NSFNet is undergoing work, expect interruptions\r\n"
+
+IRCMessage = IRCParser.message(:priv_msg) do |msg|
+  msg.prefix= "Angel"
+  msg.target= "Wiz"
+  msg.body= "Hello are you receiving this message ?"
+end.to_s
+
+$BEFORE_BENCHMARK = `ps -Orss -p #{$$}`.split[7].to_i
+
+Benchmark.bmbm do |rep|
+  rep.report("parsing / generation") do
+    10_000.times do
+      IRCParser.parse(MSG1).to_s
+      IRCParser.parse(MSG2).to_s
+    end
+    10_000.times do
+      IRCParser.message(:priv_msg) do |msg|
+        msg.prefix= "Angel"
+        msg.target= "Wiz"
+        msg.body= "Hello are you receiving this message ?"
+      end.to_s
+    end
+  end
+
+  rep.report("generation") do
+    20_000.times do
+      IRCMessage.to_s
+    end
+  end
+end
+
+at_exit do
+  $AFTER_BENCHMARK = `ps -Orss -p #{$$}`.split[7].to_i
+
+  puts "Used: " << ($AFTER_BENCHMARK - $BEFORE_BENCHMARK).to_s << " Kilobytes."
+end

data/irc_parser.gemspec

@@ -0,0 +1,98 @@
+Gem::Specification.new do |s|
+  s.specification_version = 2 if s.respond_to? :specification_version=
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.rubygems_version = '1.3.5'
+
+  s.name              = 'irc_parser'
+  s.version           = '0.1.0'
+  s.date              = '2011-08-08'
+  s.rubyforge_project = 'irc_parser'
+
+  s.summary     = "Parses and generates IRC protocol messages."
+  s.description = "A ruby 1.9.x library to parse and generate IRC messages according to the IRC definition"
+
+  s.authors  = ["Emmanuel Oga"]
+  s.email    = 'EmmanuelOga@gmail.com'
+  s.homepage = 'http://github.com/EmmanuelOga/irc_parser'
+
+  s.require_paths = %w[lib]
+
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.extra_rdoc_files = %w[README.md LICENSE]
+
+  s.add_development_dependency('rspec', ["~> 2.0.0"])
+
+  # = MANIFEST =
+  s.files = %w[
+    LICENSE
+    README.md
+    Rakefile
+    extra/benchmark.rb
+    irc_parser.gemspec
+    lib/irc_parser.rb
+    lib/irc_parser/factory.erb
+    lib/irc_parser/helper.rb
+    lib/irc_parser/messages.rb
+    lib/irc_parser/messages/commands.rb
+    lib/irc_parser/messages/errors.rb
+    lib/irc_parser/messages/replies.rb
+    lib/irc_parser/parser.rb
+    lib/irc_parser/parser.rl
+    spec/fixtures/from_weechat.rb
+    spec/fixtures/inbound.log
+    spec/irc_parser/helper_spec.rb
+    spec/irc_parser/irc_parser_spec.rb
+    spec/irc_parser/messages_spec.rb
+    spec/irc_parser/parser_spec.rb
+    spec/irc_parser/rfc1459/4_1_connection_registration/4_1_1_password_message_spec.rb
+    spec/irc_parser/rfc1459/4_1_connection_registration/4_1_2_nick_message_spec.rb
+    spec/irc_parser/rfc1459/4_1_connection_registration/4_1_3_user_message_spec.rb
+    spec/irc_parser/rfc1459/4_1_connection_registration/4_1_4_server_message_spec.rb
+    spec/irc_parser/rfc1459/4_1_connection_registration/4_1_5_oper_spec.rb
+    spec/irc_parser/rfc1459/4_1_connection_registration/4_1_6_quit_spec.rb
+    spec/irc_parser/rfc1459/4_1_connection_registration/4_1_7_server_quit_message_spec.rb
+    spec/irc_parser/rfc1459/4_2_channel_operations/4_2_1_join_message_spec.rb
+    spec/irc_parser/rfc1459/4_2_channel_operations/4_2_2_part_message_spec.rb
+    spec/irc_parser/rfc1459/4_2_channel_operations/4_2_3_1_channel_modes_spec.rb
+    spec/irc_parser/rfc1459/4_2_channel_operations/4_2_3_2_user_modes_spec.rb
+    spec/irc_parser/rfc1459/4_2_channel_operations/4_2_4_topic_message_spec.rb
+    spec/irc_parser/rfc1459/4_2_channel_operations/4_2_5_names_message_spec.rb
+    spec/irc_parser/rfc1459/4_2_channel_operations/4_2_6_list_message_spec.rb
+    spec/irc_parser/rfc1459/4_2_channel_operations/4_2_7_invite_message_spec.rb
+    spec/irc_parser/rfc1459/4_2_channel_operations/4_2_8_kick_command_spec.rb
+    spec/irc_parser/rfc1459/4_3_server_queries_and_commands/4_3_1_version_message_spec.rb
+    spec/irc_parser/rfc1459/4_3_server_queries_and_commands/4_3_2_stats_message_spec.rb
+    spec/irc_parser/rfc1459/4_3_server_queries_and_commands/4_3_3_links_message_spec.rb
+    spec/irc_parser/rfc1459/4_3_server_queries_and_commands/4_3_4_time_message_spec.rb
+    spec/irc_parser/rfc1459/4_3_server_queries_and_commands/4_3_5_connect_message_spec.rb
+    spec/irc_parser/rfc1459/4_3_server_queries_and_commands/4_3_6_trace_message_spec.rb
+    spec/irc_parser/rfc1459/4_3_server_queries_and_commands/4_3_7_admin_command_spec.rb
+    spec/irc_parser/rfc1459/4_3_server_queries_and_commands/4_3_8_info_command_spec.rb
+    spec/irc_parser/rfc1459/4_4_sending_messages/4_4_1_private_messages_spec.rb
+    spec/irc_parser/rfc1459/4_4_sending_messages/4_4_2_notice_spec.rb
+    spec/irc_parser/rfc1459/4_5_user_based_queries/4_5_1_who_query_spec.rb
+    spec/irc_parser/rfc1459/4_5_user_based_queries/4_5_2_whois_query_spec.rb
+    spec/irc_parser/rfc1459/4_5_user_based_queries/4_5_3_whowas_spec.rb
+    spec/irc_parser/rfc1459/4_6_miscellaneous_messages/4_6_1_kill_message_spec.rb
+    spec/irc_parser/rfc1459/4_6_miscellaneous_messages/4_6_2_ping_message_spec.rb
+    spec/irc_parser/rfc1459/4_6_miscellaneous_messages/4_6_3_pong_message_spec.rb
+    spec/irc_parser/rfc1459/4_6_miscellaneous_messages/4_6_4_error_spec.rb
+    spec/irc_parser/rfc1459/5_0_optionals/5_1_0_away_spec.rb
+    spec/irc_parser/rfc1459/5_0_optionals/5_2_0_rehash_message_spec.rb
+    spec/irc_parser/rfc1459/5_0_optionals/5_3_0_restart_message_spec.rb
+    spec/irc_parser/rfc1459/5_0_optionals/5_4_0_summon_message_spec.rb
+    spec/irc_parser/rfc1459/5_0_optionals/5_5_0_users_spec.rb
+    spec/irc_parser/rfc1459/5_0_optionals/5_6_0_operwall_message_spec.rb
+    spec/irc_parser/rfc1459/5_0_optionals/5_7_0_userhost_message_spec.rb
+    spec/irc_parser/rfc1459/5_0_optionals/5_8_0_ison_message_spec.rb
+    spec/irc_parser/rfc1459/6_0_replies/6_1_error_parsing_spec.rb
+    spec/irc_parser/rfc1459/6_0_replies/6_2_command_responses_generation_spec.rb
+    spec/irc_parser/rfc2812/5_1_command_responses/5_1_command_responses_spec.rb
+    spec/spec_helper.rb
+    spec/support/messages_helper.rb
+    spec/support/simplecov.rb
+  ]
+  # = MANIFEST =
+
+  s.test_files = s.files.select { |path| path =~ /^spec\/.+/ }
+end

data/lib/irc_parser.rb

@@ -0,0 +1,25 @@
+module IRCParser
+  VERSION = "0.1.0"
+
+  autoload :Helper, 'irc_parser/helper'
+  autoload :Params, 'irc_parser/params'
+  autoload :Messages, 'irc_parser/messages'
+
+  require 'irc_parser/parser'
+
+  def message(identifier, prefix = nil, params = nil)
+    klass = Messages::ALL[identifier]
+    raise IRCParser::Parser::Error, "Message not recognized: #{message.inspect}" unless klass
+    obj = klass.new(prefix, params)
+    yield obj if block_given?
+    obj
+  end
+
+  def message_class(identifier)
+    klass = Messages::ALL[identifier]
+    raise ArgumentError.new("no message with identifier #{identifier.inspect}") unless klass
+    klass
+  end
+
+  extend self
+end