duwanis-aide 0.0.4

data/README

@@ -0,0 +1,82 @@
+= Aide - What can Jabber do for you?
+
+http://github.com/duwanis/aide
+
+== DESCRIPTION:
+
+Aide is a DSL for defining and running Jabber bots.
+In order to have a good grasp on how to use Aide, you'll want to familiarize
+yourself with two classes: Aide::Dsl (used to actually read the Aide DSL), and
+Aide::ActionContext (blocks defined using the DSL get executed in the scope of
+an ActionContext). More thorough documentation will be coming soon...
+
+== FEATURES/PROBLEMS:
+
+It doesn't do anything yet. This is the main problem, really.
+
+== EXAMPLE:
+
+Check out example.aide in the source. If you install the gem
+(see INSTALL below), you should be able to do the following to
+see the results of parsing the file (or any other file matching
+the DSL):
+  aide example.aide
+
+
+== REQUIREMENTS:
+
+Patience.
+
+
+== INSTALL:
+
+  sudo gem install duwanis-aide --source=http://gems.github.com
+
+== ROADMAP:
+
+Here's the plan:
+- 0.1 - Functionality in place to create a very simple bot. Can take in any 
+  number of static commands, but nothing fancy.
+- 0.2 - Help/describe functionality built in by default.
+- 0.3 - Dynamic commands.
+- 0.4 - Ability to subscribe to an XMPP Publisher (XEP-0060)
+- 0.5 - Scheduled tasks (e.g. "execute this code every minute")
+- 0.6 - Ability to act as an XMPP Publisher (XEP-0060)
+- 0.7 - Command-line interface for publishing events (e.g. aide-publish [botname] [event])
+- 0.8 - ?????
+- 0.9 - Profit!
+- 1.0 - Fully functional 1.0 release.
+
+== HISTORY:
+
+- 0.0.4 - Beginnings of xmpp4r integration.
+- 0.0.2 - Bot class started, DSL is done in a sane way (no more creating kernel
+  methods, woo)
+- 0.0.1 - Proof of concept. DSL is somewhat spec'd out, and you
+  are now capable of parsing files (albeit crudely).
+- 0.0.0 - A new project is born!
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Tommy Morgan
+
+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/bin/aide

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'aide'
+require 'daemons'
+
+filepath = Pathname.new(ARGV[0]).cleanpath.to_s
+
+bot = Aide::Bot.new
+dsl = Aide::Dsl.new(bot, filepath)
+
+#become a daemon
+Daemons.daemonize
+
+bot.login

data/lib/aide.rb

@@ -0,0 +1,15 @@
+# Just to make our requires at the top of the gem a little easier.
+require 'pathname'
+$:.unshift(Pathname(__FILE__).dirname.expand_path)
+
+require 'rubygems'
+require 'xmpp4r'
+require 'logger'
+
+
+require 'aide/logging'
+require 'aide/errors'
+require 'aide/actioncontext'
+require 'aide/bot'
+require 'aide/dsl'
+require 'aide/version'

data/lib/aide/actioncontext.rb

@@ -0,0 +1,49 @@
+module Aide
+  ##
+  # This class is used to provide an execution context for processing messages.
+  # It houses all the attributes and helper methods that are to be exposed to
+  # the blocks that are passed in to Aide via the Aide::Dsl.with method.
+  # These contexts are created and destroyed on a per-message basis, so all
+  # attribute values refer to the message that is currently being processed.
+  #
+  class ActionContext
+    #String - The Jabber address from which the message was sent.
+    attr_accessor :from
+    #String - The Jabber address to which the message was sent.
+    attr_accessor :to
+    #String - The text of the message, minus the portion that was
+    #matched by the bot.
+    attr_accessor :message
+    #String - The full text of the message, including the portion that
+    #was matched by the bot.
+    attr_accessor :text
+    #Symbol - The type of the message (e.g. :chat, :group, etc.)
+    attr_accessor :type
+    #Aide::Bot - The bot instance that received and is acting on this
+    #message.
+    attr_accessor :bot
+    
+    ##
+    # Sends a message back to the jabber id that sent the original message.
+    #=== Parameters:
+    # - *msg*: String. The text of the message to send.
+    #
+    def respond(msg)
+      send(msg, from)
+    end
+    
+    ##
+    # Sends a message to the specified jabber id.
+    #=== Parameters:
+    # - *msg*: String. The text of the message to send.
+    # - *rec*: String. The jabber id to send the message to.
+    #
+    def send(msg, rec)
+      response = Jabber::Message.new(rec, msg)
+      response.type = :chat
+
+      bot.send(response)
+    end
+   
+  end
+end

data/lib/aide/bot.rb

@@ -0,0 +1,198 @@
+module Aide
+  ##
+  # The Bot class is the workhorse of aide. It is responsible for representing
+  # and executing the logic described by the dsl, and interacts with xmpp4r
+  # in order to send and receive messages via the jabber protocol.
+  #
+  class Bot
+    LOG = Aide::Logging.log
+
+    #Hash[String, Block] - the match strings to look for, and the code to execute when found.
+    attr_writer :actions
+    
+    #String - the username to sign this bot in with.
+    attr_writer :username
+    #Password - the password for this bot to use.
+    attr_writer :password
+    #Array[String] - a list of jabber IDs to allow this bot to interact with. Precludes block_list.
+    attr_accessor :allow_list
+    #Array[String] - a list of jabber IDs to explicitly block. Ignored if allow_list is set.
+    attr_accessor :block_list
+    
+    ##
+    #Creates a new Bot instance.
+    #
+    def initialize
+      @actions = {}
+    end
+    
+    ##
+    #Logs this Bot instance in to the jabber network and starts it listening
+    #for messages.
+    #=== Preconditions
+    #This method assumes that the Bot has already been properly configured;
+    #specifically, that at least the username and password properties have
+    #been set.
+    #=== Postconditions
+    #- The Bot will be logged on,
+    #- Its presence will be set to 'chat,' and
+    #- It will be listening for messages from privileged users in its own
+    # process (see is_user_allowed?)
+    #=== Returns
+    #+nil+
+    #
+    def login
+      if @password == nil or @username == nil
+        raise Aide::Login_Error, "credentials missing"
+      end
+      @client = Jabber::Client.new(Jabber::JID.new(@username))
+      @client.connect
+      
+      #actual authentication with the host
+      begin
+        @client.auth(@password)
+      rescue Jabber::ClientAuthenticationFailure => af
+        raise Aide::Login_Error, "Authentication failure: #{af.message}", af.backtrace
+      end
+      
+      @client.send(Jabber::Presence.new)
+      
+      LOG.debug "forking the sub-process..."
+      @pid = fork do
+        Signal.trap("HUP") { LOG.info "I'm dying!"; exit }
+
+        @client.add_message_callback do |m|
+          if m.type == :chat and is_user_allowed? m.from.to_s.split('/')[0]
+            process_message m
+          end
+        end
+       
+        loop { sleep 0.01 }
+      end
+      Process.detach(@pid)
+      LOG.debug "process forked with pid #{@pid}"
+
+    end
+   
+    ##
+    #Sends the given message.
+    #=== Parameters
+    #- *message*: Jabber::Message. The message to send.
+    #
+    def send(message)
+      @client.send message 
+    end
+    
+    ##
+    #Examines the given message to see if any actions need to be performed
+    #on it. If this message matches any actions defined for this Bot, an
+    #Aide::ActionContext is created and used to evaluate the block associated
+    #with that action.
+    #=== Parameters
+    #- *message*: Jabber::Message. The message to process.
+    #
+    def process_message(message)
+      results = match(message.body)
+      return nil unless results #no need to do anything if there's no match
+      
+      context = Aide::ActionContext.new      
+      block = @actions[results[:action_name]]
+      context.message = results[:message]
+      context.from = message.from
+      context.to = message.to
+      context.bot = self
+      context.text = message.body
+      context.type = message.type
+      context.instance_eval(&block)
+      
+      nil #no need to complicate things by returning the results of the block
+    end
+    
+    ##
+    #Log the bot out of jabber and kill the process that is listening for
+    #messages.
+    #
+    def logout
+      @client.close
+      
+      LOG.debug "sending pid #{@pid} the HUP signal"
+      Process.kill("HUP", @pid)
+    end
+    
+    ##
+    #Given the text of a message, determines if that text matches any of the
+    #actions defined for this Bot.
+    #=== Parameters
+    #- *text*: String. The text of the message to check for matches.
+    #=== Returns
+    #Hash[:action_name, :message]
+    #Where :action_name corresponds to the name of the action this text
+    #matches, and :message corresponds to everything in +text+ after the match.
+    #Returns +nil+ if no match was found.
+    #
+    def match(text)
+      result = nil
+      return result unless text
+      #tokenizing the string makes it easy to check for false matches
+      #e.g. match("tokentastic") shouldn't successfully match "token"
+      tokens = text.split
+      @actions.each do |name, block|
+        ntokens = name.split
+        if tokens[0...ntokens.size] == ntokens
+          result = { :action_name => name, :message => text[(name.size + 1)..text.size] }
+        end
+      end
+
+      result
+    end
+    
+    ##
+    #Checks a given username to see if it is explicitly allowed or blocked.
+    #=== Parameters
+    #- *username*: String. The username to check privileges for.
+    #=== Returns
+    #+boolean+ - the value of this boolean depends on the level of privileges
+    #set when the Bot was configured. If an allow_list is defined, then that
+    #list has highest precedence - +true+ is returned if the user is in that
+    #list, and +false+ is returned otherwise. If allow_list is not defined,
+    #but block_list is, then the inverse check is performed (+true+ is 
+    #returned when the user is absent from the block_list, and vice-versa).
+    #If neither list is defined then the user is assumed to be authorized.
+    #
+    def is_user_allowed?(username)
+      return @allow_list.member?(username) if @allow_list
+      return !@block_list.member?(username) if @block_list
+      return true
+    end
+  
+    ##
+    # Adds an action to the bot.
+    #=== Parameters:
+    #- *match*: String. The text to match for this action.
+    #- *block*: Proc. The code to execute when this action is fired.
+    #
+    def add_action(match, block)
+      @actions[match] = block
+    end
+  
+    ##
+    # Allows for appending to the allow_list.
+    #=== Parameters:
+    #- *list*: Array[String]. The list of users to add to the allow_list.
+    #
+    def add_allow_list(list)
+      @allow_list ||= []
+      @allow_list += list
+    end
+    
+    ##
+    # Allows for appending to the block_list.
+    #=== Parameters:
+    #- *list*: Array[String]. The list of users to add to the block_list.
+    #
+    def add_block_list(list)
+      @block_list ||= []
+      @block_list += list
+    end
+  end # Bot
+end # Aide

data/lib/aide/dsl.rb

@@ -0,0 +1,74 @@
+module Aide
+  ##
+  #The Dsl class is used for parsing Aide dsl files. All of the functions made
+  #available by this class are available to any dsl file.
+  #TODO: This class needs better documentation.
+  #
+  class Dsl
+    ##
+    # Creates a new Dsl instance.
+    #=== Parameters:
+    #- *bot*: Aide::Bot. The bot this dsl will modify/set up.
+    #- *filename*: String. The file to parse, if any; defaults to nil.
+    #=== Yields:
+    #Yields self after the file is parsed.
+    #
+    def initialize(bot, filename = nil)
+      @bot = bot
+      load_file filename if filename
+      yield self if block_given?
+    end
+    
+    ##
+    # Sets the username for the Bot that is being loaded.
+    #
+    def bot_username(text)
+      @bot.username=text
+    end
+    
+    ##
+    # Sets the password for the Bot that is being loaded.
+    #
+    def bot_password(text)
+      @bot.password=text
+    end
+    
+    ##
+    # Adds *people to the allow_list.
+    #
+    def allow(*people)
+      @bot.add_allow_list people
+    end
+    
+    ##
+    # Adds *people to the block_list.
+    #
+    def block(*people)
+      @bot.add_block_list people   
+    end
+    
+    ##
+    # Defines an action for the bot.
+    #===Parameters:
+    #- *text*: String. The text to match on.
+    #- *&block*: Block. The code to execute when *text* is found (see Aide::ActionContext)
+    #
+    def with(text,&block)
+      @bot.add_action text, block
+    end
+    
+    ##
+    # Reads in and parses a Dsl file.
+    #
+    def load_file(filename)
+      instance_eval(File.read(filename), filename)
+    end
+    
+    ##
+    # Parses a block as though it were a Dsl file.
+    #
+    def load_block(&block)
+      instance_eval(&block)
+    end 
+  end
+end

data/lib/aide/errors.rb

@@ -0,0 +1,8 @@
+module Aide
+  ##
+  #Login_Error represents a problem with the credentials
+  #given to an instance of Aide::Bot.
+  #
+  class Login_Error < StandardError
+  end
+end

data/lib/aide/logging.rb

@@ -0,0 +1,16 @@
+module Aide
+  class Logging
+    class << self
+      attr_accessor :log
+    end
+  end
+
+  def log
+    Aide::Logging.log
+  end
+
+end
+
+#set this log to whatever you want...
+Aide::Logging.log = Logger.new(STDOUT)
+Aide::Logging.log.sev_threshold = Logger::DEBUG

data/lib/aide/version.rb

@@ -0,0 +1,9 @@
+module Aide #:nodoc:
+  module VERSION #:nodoc:
+    MAJOR = 0
+    MINOR = 0
+    TINY  = 4
+
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification 
+name: duwanis-aide
+version: !ruby/object:Gem::Version 
+  version: 0.0.4
+platform: ruby
+authors: 
+- Tommy Morgan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-06-09 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: xmpp4r
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.3.0
+    version: 
+description: Aide provides a DSL for quickly and easily building Jabber (XMPP) bots.
+email: tommy.morgan@gmail.com
+executables: 
+- aide
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README
+- bin/aide
+- lib/aide.rb
+- lib/aide/actioncontext.rb
+- lib/aide/bot.rb
+- lib/aide/dsl.rb
+- lib/aide/logging.rb
+- lib/aide/errors.rb
+- lib/aide/version.rb
+has_rdoc: true
+homepage: http://github.com/duwanis/aide
+post_install_message: 
+rdoc_options: 
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A DSL for defining and running Jabber bots.
+test_files: []
+