syndi 0.0.1 → 0.1.0

data/lib/syndi/api/events.rb

@@ -0,0 +1,170 @@
+# Copyright (c) 2013, Autumn Perrault, et al. All rights reserved.
+# This free software is distributed under the FreeBSD license (see LICENSE).
+
+require 'thread'
+require 'syndi/verbosity'
+require 'syndi/api/object'
+
+# Entering namespace: Syndi
+module Syndi
+
+  # Entering namespace: API
+  module API
+
+    # A class which provides the the fundamental event system, upon which
+    # much of the API is based, and which follows a simple model of broadcasting
+    # and hooking onto such broadcasts.
+    #
+    # Plugin writers may be rather interested in {Syndi::DSL::Base}, since that
+    # provides a simpler interface to Syndi's instances of this class.
+    #
+    # @api Syndi
+    # @since 4.0.0
+    # @author noxgirl
+    #
+    # @see Syndi::DSL::Base
+    #
+    # @!attribute [r] threads
+    #   @return [Array] An array of threads used by {#call}.
+    class Events < Syndi::API::Object
+
+      attr_reader :events, :threads
+
+      # Create a new instance of Syndi::API::Events.
+      def initialize
+        @events  = {}
+        @threads = []
+      end
+
+      # Listen for (hook onto) an event.
+      #
+      # @param [Symbol] event The name of the event for which to listen.
+      # @param [Integer] priority The priority of the event from 1-5, 1 being utmost priority.
+      #
+      # @yield [...] The arguments that will be yielded to the block vary by event.
+      #   Please consult with the {file:docs/Events.md events specification} for details by event.
+      #
+      # @return [Array(Symbol, Integer, String)] Identification data including a unique string. Keep 
+      #   this if you need to destroy the hook later.
+      #
+      # @example
+      #   events.on :disconnect do |irc|
+      #     puts "I'm dying!"
+      #   end
+      #
+      # @see Syndi::DSL::Base#on
+      # @see file:docs/Events.md
+      def on(event, priority=3, &cb)
+
+        # Priority must be in the range of 1-5.
+        unless (1..5).include? priority
+          return 0
+        end
+
+        # If the event does not exist, create it.
+        @events[event] ||= {1 => {}, 2 => {}, 3 => {}, 4 => {}, 5 => {}}
+
+        # Generate a unique pseudorandom ID for this hook.
+        id = ''
+        10.times { id += get_rand_char }
+        while @events[event][priority].has_key? id
+          id = ''
+          10.times { id += get_rand_char }
+        end
+
+        # Create the hook in memory.
+        @events[event][priority][id] = cb
+
+        [event, priority, id]
+
+      end
+
+      # Broadcast an event and associated arguments.
+      #
+      # The arguments are globbed into an array from the list passed to the
+      # method, so be sure to format your call correctly.
+      #
+      # If a hook returns +false+, all subsequent hook executions will be
+      # forestalled from occurring.
+      #
+      # @param [Symbol] event The event being broadcasted.
+      # @param [Array] args A list of arguments which should be passed to
+      #   the listeners. (splat)
+      #
+      # @example
+      #   events.call(:cow_moo, "the cows", "go moo", [1, 3, 5])
+      #
+      # @see Syndi::DSL::Base#emit
+      def call(event, *args)
+        # Check if any hooks exist for this event.
+        if @events.include? event
+          
+          $m.verbose("A thread is spawning for an event broadcast (:#{event}).", VNOISY) do
+            @threads << Thread.new(event) do |evnt|
+            
+              status = nil
+              
+              begin # catch exceptions
+                # Iterate through the hooks.
+                @events[evnt].each_key do |priority|
+                  @events[evnt][priority].each_value do |prc|
+                    status = prc.call(*args) unless status == false
+                  end # each hook
+                end # each priority
+              rescue => e
+                $m.error "An exception occurred within the thread of :#{event}: #{e}", false, e.backtrace
+              end # begin
+            
+            end # thread
+          end # verbose
+        
+        end # whether this event exists
+      end
+
+      # Delete a hook or listener.
+      #
+      # @param [Array(Symbol, Integer, String)] id The identification data of the hook,
+      #   as provided by #on.
+      #
+      # @see Syndi::DSL::Base#undo_on
+      def del(id)
+        event, priority, hook = id
+
+        if @events.has_key? event
+          if @events[event][priority].has_key? hook
+            @events[event][priority].delete(hook)
+          end
+        end
+
+        tidy
+      end
+
+      # Terminate all active threads.
+      def die
+        @threads.each { |thr| thr.kill }
+      end
+
+      #######
+      private
+      #######
+
+      # Tidy up.
+      def tidy
+        @events.each do |name, lists|
+          empty = true
+          empty = lists.each_value { |v| break false if not v.empty? }
+          if empty
+            # Drop the event.
+            @events.delete name
+            next
+          end
+        end
+      end
+
+    end # class Events
+
+  end # module API
+
+end # module Syndi
+
+# vim: set ts=4 sts=2 sw=2 et:

data/lib/syndi/api/object.rb

@@ -0,0 +1,29 @@
+# Copyright (c) 2013, Autumn Perrault, et al. All rights reserved.
+# This free software is distributed under the FreeBSD license (see LICENSE).
+
+# Namespace: Syndi
+module Syndi
+
+  # Namespace: API
+  module API
+
+    # A superclass for {Syndi::API::Timers} and {Syndi::API::Events}.
+    class Object
+
+      private
+
+      # Get a random character.
+      #
+      # @return [String] A random character.
+      def get_rand_char
+        chrs = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890".split(//)
+        chrs[rand(chrs.length)]
+      end
+
+    end # class Object
+
+  end # module API
+
+end # module Syndi
+
+# vim: set ts=4 sts=2 sw=2 et:

data/lib/syndi/api/plugin.rb

@@ -0,0 +1,155 @@
+# Copyright (c) 2013, Autumn Perrault, et al. All rights reserved.
+# This free software is distributed under the FreeBSD license (see LICENSE).
+
+require 'ostruct'
+require 'libsyndi'
+require 'syndi/bot'
+
+module Syndi
+
+  module API
+
+    # A basic superclass for plugins.
+    #
+    # @api Syndi
+    # @since 4.0.0
+    # @author noxgirl
+    # @author swarley
+    #
+    # @!attribute [r] name
+    #   @return [String] Name of the plugin.
+    #
+    # @!attribute [r] summary
+    #   @return [String] Summary of the plugin.
+    #
+    # @!attribute [r] version
+    #   @return [String] Version of the plugin.
+    #
+    # @!attribute [r] library
+    #   @return [String] The library upon which the plugin is based.
+    #
+    # @!attribute [r] author
+    #   @return [String] Author of the plugin.
+    #
+    # @!attribute [r] syndi
+    #   @return [String] Version of Syndi required by the plugin.
+    class Plugin
+
+      attr_reader :name, :summary, :version, :library, :author, :syndi
+
+      # Configure the plugin.
+      #
+      # @yieldparam [OpenStruct] conf Configuration structure.
+      #
+      # - +conf.name+: Name of the plugin (String).
+      # - +conf.summary+: Summary of the plugin (String).
+      # - +conf.version+: Version of the plugin (String).
+      # - +conf.library+: Library upon which the plugin is based. (String).
+      # - +conf.author+: Author of the plugin (String).
+      # - +conf.syndi+: Required version of Syndi (String). Should be in the format of
+      #   +'~> version'+ or +'>= version'+. +~>+ means at least +version+ but no later
+      #   than the minor version (e.g. +'~> 4.0'+ will allow +4.0.2+ but not +4.1.0+).
+      #   +>=+ means at at least +version+.
+      #
+      # Additionally, it should be noted that +conf.library+ should be either of the
+      # core libraries, *or* 'multi' if it uses multiple libraries.
+      #
+      # @example
+      #   configure do |c|
+      #     c.name    = 'MagicPlugin'
+      #     c.summary = 'A magical extension.'
+      #     c.version = '1.00'
+      #     c.library = 'irc'
+      #     c.author  = 'noxgirl'
+      #     c.syndi    = '~> 4.0'
+      #   end
+      def configure
+
+        # Prepare an open structure.
+        conf = OpenStruct.new
+
+        # Yield it to the configuration block.
+        yield conf if block_given?
+
+        # Check for sufficient configuration.
+        [:name,:summary,:version,:library,:author,:syndi].each do |s|
+          if conf.send(s).nil?
+            raise PluginError, "Plugin #{self.inspect} provided insufficient configuration (#{s} is nil)."
+          end
+        end
+
+        @name    = conf.name
+        @summary = conf.summary
+        @version = conf.version
+        @library = conf.library
+        @author  = conf.author
+
+        # Check for compatibility.
+        if conf.syndi =~ /^(~>\s*)((?:[\dabcr])(?:\.[\dabcr]))+$/ # ~>
+        
+          ver = $2
+          if Gem::Version.new(ver.dup) >= Gem::Version.new(Syndi::VERSION.dup) # must be later than or equal to current
+            
+            # Split current version and plugin-demanded version by '.'.
+            verarr  = Syndi::VERSION.split(/\./)
+            pverarr = ver.split(/\./)
+
+            # Must be no later than the current minor version
+            unless verarr[1] <= pverarr[1]
+              raise PluginError, "Plugin #@name v#@version demands Syndi #{conf.syndi}; current version is #{Syndi::VERSION}. Incompatible! Aborting load!"
+            end
+
+            @syndi = conf.syndi
+          
+          else
+            raise PluginError, "Plugin #@name v#@version demands Syndi #{conf.syndi}; current version is #{Syndi::VERSION}. Incompatible! Aborting load!"
+          end # if ver >=
+
+        elsif conf.syndi =~ /^(>=\s*)((?:[\dabcr])(?:\.[\dabcr]))+$/ # >=
+        
+          ver = $2
+          unless ver >= Syndi::VERSION # must be later than or equal to current
+            raise PluginError, "Plugin #@name v#@version demands Syndi #{conf.syndi}; current version is #{Syndi::VERSION}. Incompatible! Aborting load!"
+          end
+        
+          @syndi = conf.syndi
+
+        else
+          raise PluginError, "Plugin #@name v#@version cannot be checked for compatibility. Aborting load!"
+        end # compat check
+
+        # If we've made it this far, it's sufficiently compatible with the API.
+        # Now, we need to extend this plugin with our domain-specific language (DSL).
+        self.extend Syndi::DSL::Base # this is the base
+        case @library
+        
+        when 'irc'
+          self.extend Syndi::DSL::IRC
+        when 'multi'
+          # the specifications for multilib DSL functionality are yet undecided
+        else
+          # If it's a library we don't comprehend, exception time, it is.
+          raise PluginError, "Plugin #@name v#@version demands '#{@library}' library, which I do not understand. Aborting load!"
+        
+        end
+        
+      end # def configure
+
+      #########
+      protected
+      #########
+
+      # Inheritance event.
+      #
+      # @param [Class] subklass The subclass which has inherited {self}.
+      def self.inherited(subklass)
+        $m.debug("[plugin] Syndi::API::Plugin inherited by #{subklass}")
+      end
+
+    end # class Plugin
+
+  end # module API
+
+end # module Syndi
+
+# vim: set ts=4 sts=2 sw=2 et:

data/lib/syndi/api.rb

@@ -0,0 +1,7 @@
+# Copyright (c) 2013, Autumn Perrault, et al. All rights reserved.
+# This free software is distributed under the FreeBSD license (see LICENSE).
+
+require 'syndi/api/events'
+require 'syndi/api/timers'
+
+# vim: set ts=4 sts=2 sw=2 et:

data/lib/syndi/bot.rb

@@ -0,0 +1,270 @@
+# Copyright (c) 2013, Autumn Perrault, et al. All rights reserved.
+# This free software is distributed under the FreeBSD license (see LICENSE).
+
+syndiload :Redis,  'redis'
+syndiload :FileKV, 'filekv'
+
+require 'syndi/config'
+require 'syndi/api'
+
+# Namespace: Syndi
+module Syndi
+
+  # This is the central class of Syndi, providing all core functionality.
+  #
+  # It should be additionally noted that for each loaded core library, a readable
+  # instance attribute of the library's name will exist, typically pointing to
+  # an instance of its respective Library class. (e.g. @irc = <Syndi::IRC::Library>)
+  #
+  # @!attribute [r] opts
+  #   @return [Slop] The options object.
+  #
+  #
+  # @!attribute [r] log
+  #   @return [Syndi::Logger] The logging instance.
+  #
+  # @!attribute [r] conf
+  #   @return [Syndi::Config] The configuration instance.
+  #
+  # @!attribute [r] events
+  #   @return [Syndi::API::Events] The event system instance.
+  #
+  # @!attribute [r] clock
+  #   @return [Syndi::API::Timers] The timer system instance.
+  #
+  # @!attribute [r] db
+  #   @return [Redis] The Redis database.
+  #
+  # @!attribute [r] libs
+  #   @return [Array<String>] List of loaded core libraries.
+  #
+  # @!attribute [r] netloop
+  #   @return [Thread] The thread in which #main_loop is running.
+  #
+  # @!attribute [r] sockets
+  #   @return [Array<Object>] A list of socket objects.
+  class Bot
+
+    attr_reader :opts, :log, :conf, :events, :clock, :db, :libs,
+                :netloop, :sockets
+
+    # Create a new instance of Syndi.
+    #
+    # @param [Hash{String => Object}] opts A hash of options.
+    def initialize opts
+      # Save options.
+      @opts = opts
+    end      
+
+    # Initialize this instance.
+    def init
+    
+      # Load configuration
+      load_config
+
+      # Initialize the central event system
+      @events = Syndi::API::Events.new
+
+      # Start the timer system.
+      @clock = Syndi::API::Timers.new
+
+      # Prepare for sockets.
+      @sockets = []
+
+      # Initialize the database
+      @db = load_database
+
+      # Load core libraries.
+      load_libraries
+
+      true
+    end
+
+    # Start the bot.
+    def start
+      
+      # Call the start event.
+      @events.call :start
+
+      # Throw the program into the main loop.
+      @events.threads.each { |thr| thr.join } # block until we're ready to go
+      $log.verbose("Producing a thread and entering the main loop...", VUSEFUL) do
+        @netloop = Thread.new { main_loop }
+        @netloop.join
+      end
+
+    end
+
+    # Daemonize the bot.
+    def daemonize
+      $log.info "Forking into the background. . . ."
+  
+      # Direct all incoming data on STDIN and outgoing data on STDOUT/STDERR to /dev/null.
+      $stdin  =           File.open '/dev/null'
+      $stdout = $stderr = File.open '/dev/null', 'w'
+      
+      # Fork and retrieve the PID.
+      pid = fork
+
+      # Save it to syndi.pid.
+      unless pid.nil?
+        File.open('syndi.pid', 'w') { |io| io.puts pid }
+        exit 0
+      end
+    end
+
+    # Main loop.
+    def main_loop
+      loop do
+        # Build a list of sockets.
+        sockets       = []
+        assoc_objects = {}
+        @sockets.each do |o|
+          unless o.socket.nil? or o.socket.closed?
+            sockets << o.socket
+            assoc_objects[o.socket] = o
+          end
+        end
+        next if sockets.empty?
+
+        # Call #select.
+        ready_read, _, _ = IO.select(sockets, [], [], nil)
+
+        # Iterate through sockets ready for reading.
+        ready_read.each do |socket|
+          @events.call :net_receive, assoc_objects[socket]
+        end
+      end
+    end
+
+    # Terminate the bot.
+    #
+    # @param [String] reason The reason for termination.
+    def terminate reason = 'Terminating'
+      info "Syndi is terminating owing to thus: #{reason}"
+
+      # Call :die
+      @events.call :die, reason
+    
+      # Close the database.
+      @db.disconnect
+
+      # When dying, allow about three seconds for hooks to execute before
+      # fully terminating.
+      sleep 3
+
+      # Delete syndi.pid
+      File.delete 'syndi.pid' unless @opts.foreground?
+
+      exit 0
+    end
+
+    #######
+    private
+    #######
+
+    # Load the configuration.
+    def load_config
+
+      # Try to find the file
+      # if we're a gem, we'll try ~/.syndi/syndi.yml
+      # else we'll try ./conf/syndi.yml
+      confpath = nil
+      if Syndi.gem?
+        confpath = File.join(SYNDI_DIR, 'syndi.yml')
+      else
+        confpath = File.join('conf', 'syndi.yml')
+      end
+      confpath = @opts[:conf] if @opts.conf? # --conf=FILE has supreme precedence
+
+      $log.info "Reading the configuration file #{confpath}..."
+      @conf = Syndi::Config.new File.expand_path(confpath)
+
+    end
+
+    # Load Syndi libraries.
+    def load_libraries
+      
+      $log.info 'Loading core libraries...'
+      @libs = []
+
+      # Iterate through each configured library.
+      @conf['libraries'].each do |lib|
+        lib.dc!
+
+        if @libs.include? lib
+          # Don't load a library more than once!
+          $log.error "Cannot load library twice (#{lib})! Please fix your configuration."
+          next
+        end
+
+        begin
+          load_library lib
+          @libs.push lib
+        rescue => e
+          $log.error_bt "Failed to load core library '#{lib}': #{e}", e.backtrace
+        end
+
+      end
+
+    end
+
+    # Load a core library.
+    def load_library lib
+      # here is where magic occurs to load a library
+      require "syndi/#{lib}"
+      instance_variable_set "@#{lib}".to_sym, Object.const_get("LIBRARY_#{lib.uc}")
+      define_singleton_method(lib.to_sym) { self.instance_variable_get("@#{__method__}".to_sym) }
+    end
+
+    # Load the Redis database.
+    def load_database
+
+      driver = @conf['database']['driver'] || 'redis'
+
+      case driver
+      when 'redis'
+        load_db_redis
+      when 'flatfile'
+        load_db_flatfile
+      end
+
+    end
+
+    # Initializes Redis.
+    def load_db_redis
+
+      config = Hash.new
+      if host = @conf['database']['address']
+        config[:host] = host
+      end
+      if port = @conf['database']['port']
+        config[:port] = port
+      end
+      if path = @conf['database']['path']
+        config[:path] = path
+      end
+
+      redis = Redis.new config
+
+      if passwd = @conf['database']['password']
+        redis.auth passwd
+      end
+      if id = @conf['database']['number']
+        redis.select id
+      end
+
+      redis
+
+    end
+
+    # Initializes Flatfile.
+    def load_db_flatfile
+      FileKV.new 'syndi.db'
+    end
+
+  end # class Bot
+  
+end # module Syndi
+
+# vim: set ts=4 sts=2 sw=2 et: