jabbot 0.1.2 → 0.2.0

data/LICENSE

@@ -0,0 +1,21 @@
+(The MIT License)
+
+Copyright (c) 2009-2010 Jan-Erik Rediger (badboy\_)
+
+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,157 @@
+# Jabbot
+
+Official URL: http://github.com/badboy/jabbot/tree/master
+Jan-Erik Rediger (badboy\_) (http://badboy.pytalhost.de)
+
+## Description
+
+Jabbot is a Ruby micro-framework for creating Jabber/MUC bots,
+heavily inspired by Sinatra and Twibot.
+
+I modified the code of Twibot to fit my needs.
+The original Twibot code is located at:
+http://github.com/cjohansen/twibot/tree/master
+
+A big thank you to Christian Johansen, who wrote the code for Twibot.
+Jabbot is heavily based on his code.
+
+## Usage
+
+### Simple example
+
+    # Receive messages, and post them publicly
+    message do |message, params|
+      post message.text
+    end
+
+    # Respond to query if they come from the right crowd
+    # post "message" => "user" is just some syntax sugar
+    # post "message", "user" will work to
+    query :from => [:cjno, :irbno] do |message, params|
+      post "#{message.user} I agree" => message.user
+    end
+
+    # Log every single line
+    # (you can use "message :all" too ;)
+    message do |message, params|
+      MyApp.log_message(message)
+    end
+
+### Running the bot
+
+To run the bot, simply do:
+
+    ruby bot.rb
+
+Jabbot uses the [at\_exit hook](http://ruby-doc.org/core/classes/Kernel.html#M005932) to start.
+
+### Configuration
+
+Jabbot looks for a configuration file in ./config/bot.yml. It should contain
+atleast:
+
+    login: jabber_login
+    password: jabber_password
+    channel: channel_to_join
+    server: server_to_connect_to
+    nick: mybot
+
+You can also configure with Ruby:
+
+    configure do |conf|
+      conf.login = "my_account"
+      conf.nick = "mybot"
+    do
+
+If you don't specify login and/or password in any of these ways, Jabbot will fail
+Nick is automatically set to "jabbot" unless something different is defined
+If you want you can set the Jabber Resource:
+
+    configure do |conf|
+      conf.resource ="mybot_resource"
+
+    end
+
+Default is "jabbot".
+
+### "Routes"
+
+Like Sinatra, and other web app frameworks, Jabbot supports "routes":
+patterns to match incoming tweets and messages:
+
+    message "time :country :city" do |message, params|
+      time = MyTimeService.lookup(params[:country], params[:city])
+      post "Time is #{time} in #{params[:city]}, #{params[:country]}"
+    end
+
+You can have several "message" blocks (or "join", "leave", "query" or "subject").
+Every matching block will be called.
+
+Jabbot also supports regular expressions as routes:
+
+    message /^time ([^\s]*) ([^\s]*)/ do |message, params|
+      # params is an array of matches when using regexp routes
+      time = MyTimeService.lookup(params[0], params[1])
+      post "Time is #{time} in #{params[:city]}, #{params[:country]}"
+    end
+
+## Requirements
+
+xmpp4r. You'll need atleast 0.4.
+You can get it via rubygems:
+
+    gem install xmpp4r
+
+or get it from: http://home.gna.org/xmpp4r/
+
+## Installation
+
+Jabbot is available via gem:
+
+    gem install jabbot
+
+## Is it Ruby 1.9?
+
+All tests passes on Ruby 1.9.
+Seems like it works :)
+
+## Samples
+
+There are two examples in the [samples][] directory:
+
+* [jabbot_example.rb][] is a working sample without real functionality.
+* [black.rb][] is the code I use for my own bot (without the config of course).
+
+## Contributors
+
+* Christian Johansen (cjohansen) (author of Twibot) - http://www.cjohansen.no
+
+## License
+
+The code is released under the MIT license. See [LICENSE][].
+
+## Contribute
+
+If you'd like to hack on jabbot, start by forking my repo on GitHub:
+
+http://github.com/badboy/jabbot
+
+jabbot needs xmpp4r, so just install it:
+
+    gem install xmpp4r
+
+Then:
+
+1. Clone down your fork
+2. Create a thoughtfully named topic branch to contain your change
+3. Hack away
+4. Add tests and make sure everything still passes by running `rake`
+5. If you are adding new functionality, document it in the README
+6. Do not change the version number, I will do that on my end
+7. If necessary, rebase your commits into logical chunks, without errors
+8. Push the branch up to GitHub
+9. Send me (badboy) a pull request for your branch
+
+[LICENSE]: http://github.com/badboy/jabbot/blob/master/LICENSE
+[jabbot_example.rb]: http://github.com/badboy/jabbot/blob/master/samples/jabbot_example.rb
+[black.rb]: http://github.com/badboy/jabbot/blob/master/samples/black.rb

data/Rakefile

@@ -1,24 +1,11 @@
-require 'rubygems'
-require 'rake'
-
 begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "jabbot"
-    gem.summary = %Q{Simple framework for creating Jabber/MUC bots, inspired by Sinatra and Twibot}
-    gem.email = "badboy@archlinux.us"
-    gem.homepage = "http://github.com/badboy/jabbot"
-    gem.authors = ["BadBoy_"]
-    gem.add_dependency('xmpp4r', '>=0.4')
-    gem.add_development_dependency('thoughtbot-shoulda', '>=2.10.1')
-    gem.add_development_dependency('jeweler', '>=0.10.2')
-
-    gem.rubyforge_project = 'jabbot'
-  end
+  require 'mg'
 rescue LoadError
-  puts "Jeweler not available. Install it with: sudo gem install jeweler"
+  abort "Please `gem install mg`"
 end
 
+MG.new("jabbot.gemspec")
+
 require 'rake/testtask'
 Rake::TestTask.new(:test) do |test|
   test.libs << 'lib' << 'test'
@@ -27,19 +14,3 @@ Rake::TestTask.new(:test) do |test|
 end
 
 task :default => :test
-
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  if File.exist?('VERSION.yml')
-    config = YAML.load(File.read('VERSION.yml'))
-    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
-  else
-    version = ""
-  end
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "jabbot #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-

data/lib/jabbot.rb

@@ -6,47 +6,14 @@ require 'xmpp4r/version/helper/simpleresponder'
 require 'yaml'
 require File.join(File.dirname(__FILE__), 'hash')
 
-module Jabbot
-
-  # :stopdoc:
-  VERSION = '0.1.2'
-  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
-  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
-  # :startdoc:
-
-  # Returns the version string for the library.
-  #
-  def self.version
-    VERSION
-  end
-
-  # Returns the library path for the module. If any arguments are given,
-  # they will be joined to the end of the libray path using
-  # <tt>File.join</tt>.
-  #
-  def self.libpath( *args )
-    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
-  end
-
-  # Returns the lpath for the module. If any arguments are given,
-  # they will be joined to the end of the path using
-  # <tt>File.join</tt>.
-  #
-  def self.path( *args )
-    args.empty? ? PATH : ::File.join(PATH, args.flatten)
-  end
-
-  # Utility method used to require all files ending in .rb that lie in the
-  # directory below this file that has the same name as the filename passed
-  # in. Optionally, a specific _directory_ name can be passed in such that
-  # the _filename_ does not have to be equivalent to the directory.
-  #
-  def self.require_all_libs_relative_to( fname, dir = nil )
-    dir ||= File.basename(fname, '.*')
-    search_me = File.expand_path(File.join(File.dirname(fname), dir, '**', '*.rb'))
-    Dir.glob(search_me).sort.each {|rb| require rb }
-  end
+require 'jabbot/bot.rb'
+require 'jabbot/config.rb'
+require 'jabbot/handlers.rb'
+require 'jabbot/macros.rb'
+require 'jabbot/message.rb'
+require 'jabbot/version.rb'
 
+module Jabbot
   @@app_file = lambda do
     ignore = [
       /lib\/twibot.*\.rb/, # Library
@@ -79,6 +46,5 @@ module Jabbot
 end  # module Jabbot
 
 Thread.abort_on_exception = true
-Jabbot.require_all_libs_relative_to(__FILE__)
 
 # EOF

data/lib/jabbot/bot.rb

@@ -9,7 +9,7 @@ module Jabbot
   class Bot
     include Jabbot::Handlers
     attr_reader :client
-    attr_reader :user
+    attr_reader :users
 
     Message = Struct.new(:user, :text, :time) do
       def to_s
@@ -22,16 +22,26 @@ module Jabbot
       @config = options || Jabbot::Config.default << Jabbot::FileConfig.new
       @log = nil
       @abort = false
-      @user = []
+      @users = []
 
     rescue Exception => krash
       raise SystemExit.new(krash.message)
     end
 
+    # Enable debugging mode.
+    # All xmpp4r-internal calls to Jabber::Debuglog are
+    # printed to $stderr by default.
+    # You may change the logger by using
+    #   Jabber::Logger = Logger.new(…)
+    def debug!
+      Jabber::debug = true
+    end
+
     #
     # connect to Jabber and join channel
     #
     def connect
+      #Jabber::debug = true
       @jid = Jabber::JID.new(login)
       @mucjid = Jabber::JID.new("#{channel}@#{server}")
 
@@ -46,7 +56,7 @@ module Jabbot
       else
         @jid.resource = config[:resource] || "jabbot"
         @mucjid.resource = config[:nick] || "jabbot"
-        @user << config[:nick]
+        @users << config[:nick]
       end
 
       @client = Jabber::Client.new(@jid)
@@ -74,6 +84,7 @@ module Jabbot
         exit
       end
 
+      debug! if config[:debug]
       connect
       poll
     end
@@ -143,8 +154,8 @@ module Jabbot
         end
 
         muc.on_join do |time, nick|
-          unless @user.include? nick
-            @user << nick
+          unless @users.include? nick
+            @users << nick
           end
           if time.nil?
             begin
@@ -155,9 +166,9 @@ module Jabbot
             end
           end
         end
-        
+
         muc.on_leave do |time, nick|
-          @user.delete(nick)
+          @users.delete(nick)
           if time.nil?
             begin
               dispatch_messages(:leave, [Message.new(nick, "leave", Time.now)])
@@ -167,7 +178,7 @@ module Jabbot
             end
           end
         end
-        
+
         muc.on_subject do |time, nick, subject|
           if time.nil?
             begin
@@ -213,7 +224,6 @@ module Jabbot
       @conf = nil
     end
 
-   private
     #
     # Map configuration settings
     #

data/lib/jabbot/config.rb

@@ -27,7 +27,8 @@ module Jabbot
       :nick => 'jabbot',
       :channel => nil,
       :server => nil,
-      :resource => nil
+      :resource => nil,
+      :debug => false
     }
 
     def initialize(settings = {})

data/lib/jabbot/macros.rb

@@ -1,54 +1,105 @@
 module Jabbot
-  @@prompt = false
-
-  def self.prompt=(p)
-    @@prompt = f
-  end
-
+  # Defines the DSL used for bots.
   module Macros
     def self.included(mod)
       @@bot = nil
     end
 
+    # Configure the bot
+    # The block gets passed an instance of OpenStruct used as the config
+    # See lib/jabbot/config.rb for possible options
     def configure(&blk)
       bot.configure(&blk)
     end
 
+    # Returns the current config hash
+    def config
+      bot.config
+    end
+
+    # Add message handler
+    # pattern - can be a String containing :matches
+    #           or a Regexp with matching groups
+    # options - Hash defining users to receive messages from
+    #           { :from => ['user1', 'user2', ...] }
+    # blk     - The block to execute on successfull match
     def message(pattern = nil, options = {}, &blk)
       add_handler(:message, pattern, options, &blk)
     end
 
+    # Add query handler
+    # Only private messages are matched against this handler
+    #
+    # pattern - can be a String containing :matches
+    #           or a Regexp with matching groups
+    # options - Hash defining users to receive messages from
+    #           { :from => ['user1', 'user2', ...] }
+    # blk     - The block to execute on successfull match
     def query(pattern = nil, options = {}, &blk)
       add_handler(:private, pattern, options, &blk)
     end
     alias_method :private_message, :query
 
+    # Add join handler
+    # Block gets executed when new user joins
+    #
+    # options - Hash defining users to react on joins
+    #           { :from => ['user1', 'user2', ...] }
+    # blk     - The block to execute on successfull match
     def join(options = {}, &blk)
       add_handler(:join, /\Ajoin\Z/, options, &blk)
     end
-    
+
+    # Add leave handler
+    # Block gets executed when user leaves the channel
+    #
+    # options - Hash defining users to react on leaves
+    #           { :from => ['user1', 'user2', ...] }
+    # blk     - The block to execute on successfull match
     def leave(options = {}, &blk)
       add_handler(:leave, /\Aleave\Z/, options, &blk)
     end
 
+    # Add subject/topic handler
+    # Block gets executed when topic gets changed
+    #
+    # pattern - can be a String containing :matches
+    #           or a Regexp with matching groups
+    # options - Hash defining users
+    #           { :from => ['user1', 'user2', ...] }
+    # blk     - The block to execute on successfull match
     def subject(pattern = nil, options = {}, &blk)
       add_handler(:subject, pattern, options, &blk)
     end
     alias_method :topic, :subject
 
+    # Returns the Jabber::Client instance used
+    # You may execute low-level functions on this object if needed
     def client
       bot.client
     end
 
+    # Close the connection and exit the bot
     def close
       bot.close
     end
     alias_method :quit, :close
 
-    def user
-      bot.user
+    # Get array of all users in the channel
+    def users
+      bot.users
     end
 
+    # Post message back to the channel
+    # msg - Message to send, can be a String to be send
+    #       or a Hash: { msg => user }
+    # to  - User to send the message to,
+    #       left blank if syntax-sugar variant is used
+    #
+    # Syntax-sugar variant:
+    #   post "msg" => "user1"
+    # is the same as
+    #   post "msg", "user1"
     def post(msg, to=nil)
       if msg.is_a?(Hash) && msg.keys.size == 1
         to = msg.values.first
@@ -57,15 +108,19 @@ module Jabbot
       bot.send_message(msg, to)
     end
 
+    # Returns boolean wether to start the bot at_exit
     def run?
       !@@bot.nil?
     end
 
-   private
+    private
+
+    # Low-level method to add new Handler to the bot
     def add_handler(type, pattern, options, &blk)
       bot.add_handler(type, Jabbot::Handler.new(pattern, options, &blk))
     end
 
+    # Low-level method to create new instance of a bot
     def bot
       return @@bot unless @@bot.nil?