syndi 0.0.1 → 0.1.0

data/lib/syndi/events.rb

@@ -0,0 +1,114 @@
+# Copyright (c) 2013, Autumn Perrault, et al. All rights reserved.
+# This free software is distributed under the FreeBSD license (see LICENSE).
+
+require 'syndi/verbosity'
+
+module Syndi
+
+  # A simple event management system, designed particularly for Syndi.
+  #
+  # @!attribute [r] events
+  #   @return [Hash{Symbol => Array<Syndi::Events::Listener>}] The collection of events and associated listeners.
+  class Events
+
+    attr_reader :events
+
+    def initialize
+      @events = Hash.new
+    end
+
+    # Create a new listener on a given +event+, which will have the given
+    # block attached and executed upon the event's occurrence.
+    #
+    # @param [Symbol] event The event which to await.
+    # @param [Integer] priority The priority this listener should have in the hook
+    #    execution procedure. Must be 1-5 with 1 being of utmost priority.
+    #
+    # @yield [...] The parameters passed when the event was broadcasted. This varies
+    #   by event. See the official event reference for Syndi events.
+    #
+    # @return [Syndi::Events::Listener] The listener.
+    def on event, priority = 3, &prc
+      @events[event] ||= Array.new
+
+      if priority < 1 || priority > 5
+        raise ArgumentError, "invalid event priority specified"
+      end
+
+      hook = Listener.new self, event, priority, prc
+      @events[event] << hook
+      hook
+    end
+
+    # This will broadcast the given +event+, executing each listener and passing
+    # to it the parameters supplied here, respecting priority and operating in a
+    # thread.
+    #
+    # @param [Symbol] event
+    # @param [...] parameters The arguments to be passed to each listener.
+    def emit event, *parameters
+      if @events[event]
+
+        # collect the listeners with respect to priority
+        one   = @events.collect { |hook| (hook.priority == 1 ? hook : nil) }.compact
+        two   = @events.collect { |hook| (hook.priority == 2 ? hook : nil) }.compact
+        three = @events.collect { |hook| (hook.priority == 3 ? hook : nil) }.compact
+        four  = @events.collect { |hook| (hook.priority == 4 ? hook : nil) }.compact
+        five  = @events.collect { |hook| (hook.priority == 5 ? hook : nil) }.compact
+
+        Syndi.log.verbose "event *#{event}* is being broadcasted on #{self}", VNOISY
+
+        # spawn a thread and perform the executions
+        Thread.new do
+          begin
+            # cease if status ever becomes false/nil
+            status = true
+            
+            one.each   { |code| status = code.call parameters if status }
+            two.each   { |code| status = code.call parameters if status }
+            three.each { |code| status = code.call parameters if status }
+            four.each  { |code| status = code.call parameters if status }
+            five.each  { |code| status = code.call parameters if status }
+          rescue => e
+            # catch thread errors
+            Syndi.log.error "A listener to a broadcast of #{event} on #{self} caused an exception to rise (#{e})", true
+          end
+        end
+
+      end
+    end
+
+    def inspect
+      "<#Syndi::Events: obj_id=#{object_id} event_count=#{@events.length}>"
+    end
+    alias_method :to_s, :inspect
+
+    # A class which represents a listener.
+    class Listener
+      attr_reader :event, :priority, :code
+
+      def initialize sys, event, priority, prc
+        @sys      = sys
+        @event    = event
+        @priority = priority
+        @code     = prc
+
+        Syndi.log.verbose "new listener spawned and attached to #{event}: #{self}", VNOISY
+      end
+
+      def deaf
+        @sys.events[event].delete self
+      end
+
+      def inspect
+        "<#Syndi::Events::Listener: sys=#@sys event=#@event priority=#@priority proc={#@code}>"
+      end
+      alias_method :to_s, :inspect
+
+    end
+
+  end
+
+end
+
+# vim: set ts=4 sts=2 sw=2 et:

data/lib/syndi/irc/common.rb

@@ -0,0 +1,63 @@
+# Copyright (c) 2013, Autumn Perrault, et al. All rights reserved.
+# This free software is distributed under the FreeBSD license (see LICENSE).
+
+module Syndi
+
+  module IRC
+
+    # A class which manages such common IRC functions as syndijoining channels,
+    # and identifying to services the traditional PRIVMSG way.
+    class Common
+
+      # Construct a new common function handler.
+      #
+      # @param [Syndi::IRC::Library] lib The IRC library instance.
+      def initialize lib
+        @lib = lib
+        $m.events.on   :die,       &method(:do_die)
+        @lib.events.on :connected, &method(:do_syndijoin)
+      end
+
+      # Automatically identify with services the traditional way, which is
+      # to say by a /msg.
+      #
+      # @param [Syndi::IRC::Server] irc The IRC connection.
+      def do_identify irc
+        if $m.conf['irc'][irc.s]['nickIdentify']
+          
+          # Assume the service is NickServ if not specified
+          service = $m.conf['irc'][irc.s]['nickIdentify']['service'] || 'NickServ'
+          # and assume the command is IDENTIFY if not specified
+          command = $m.conf['irc'][irc.s]['nickIdentify']['command'] || 'IDENTIFY'
+
+          # we can't actually /msg anyone yet.....
+        end
+      end
+
+      # Automatically join IRC channels upon connection.
+      #
+      # @param [Syndi::IRC::Server] irc The IRC connection.
+      def do_syndijoin irc
+        if $m.conf['irc'][irc.s]['syndijoin']
+          
+          $m.conf['irc'][irc.s]['syndijoin'].each do |chan|
+            irc.join(chan['name'], chan['key']||nil)
+          end
+
+        end
+      end
+
+      # Disconnect from servers on termination.
+      #
+      # @param [String] reason Reason for termination.
+      def do_die reason
+        @lib.connections.each { |net, irc| irc.disconnect reason }
+      end
+
+    end # class Common
+
+  end # module IRC
+
+end # module Syndi
+
+# vim: set ts=4 sts=2 sw=2 et:

data/lib/syndi/irc/library.rb

@@ -0,0 +1,89 @@
+# Copyright (c) 2013, Autumn Perrault, et al. All rights reserved.
+# This free software is distributed under the FreeBSD license (see LICENSE).
+
+require 'syndi/irc/server'
+require 'syndi/irc/object/entity'
+require 'syndi/irc/object/channel'
+require 'syndi/irc/object/user'
+require 'syndi/irc/protocol'
+require 'syndi/irc/common'
+
+module Syndi
+  
+  module IRC
+    
+    # The base of the IRC framework.
+    #
+    # @!attribute [r] events
+    #   @return [Syndi::API::Events] The IRC event system.
+    #
+    # @!attribute [r] connections
+    #   @return [Hash{String => Syndi::IRC::Server}] Collection of IRC connections. 
+    class Library
+
+      attr_reader :events, :connections
+
+      def initialize
+
+        # Initialize our event system.
+        @events      = Syndi::API::Events.new
+        # Prepare our collection of IRC server connections.
+        @connections = Hash.new
+      
+        # Be ready to accept data.
+        $m.events.on :net_receive, 1, &method(:receive)
+
+        # Start connections when Syndi is started.
+        $m.events.on :start, &method(:start)
+
+        # Parse data.
+        @parser = Syndi::IRC::Protocol.new self
+
+        # Handle common functions.
+        @common = Syndi::IRC::Common.new self
+        
+      end # def initialize
+
+      # Process incoming network data.
+      #
+      # @param [Object] socket_object The socket object, which in the case of
+      #   ourselves should be an {Syndi::IRC::Server}, or we won't handle it.
+      def receive socket_object
+        if socket_object.instance_of? Syndi::IRC::Server
+          socket_object.recv
+        end
+      end
+
+      # Initiate IRC connections.
+      def start
+        
+        # Iterate through each IRC server in the config, and connect to it.
+        $m.conf['irc'].each do |name, hash|
+          begin
+            # Configure the IRC instance.
+            @connections[name] = Syndi::IRC::Server.new(name) do |c|
+              c.address = hash['address']
+              c.port    = hash['port']
+              c.nick    = hash['nickname'][0] 
+              c.user    = hash['username']
+              c.real    = hash['realName']
+              c.ssl     = hash['useSSL']
+            end
+
+            # Connect.
+            $m.sockets << @connections[name]
+            @connections[name].connect
+          rescue => e
+            $m.error("Connection to #{name} failed: #{e}", false, e.backtrace)
+          end
+        end
+
+      end # def start
+
+    end # class Library
+
+  end # module IRC
+
+end # module Syndi
+
+# vim: set ts=4 sts=2 sw=2 et:

data/lib/syndi/irc/object/channel.rb

@@ -0,0 +1,21 @@
+# Copyright (c) 2013, Autumn Perrault, et al. All rights reserved.
+# This free software is distributed under the FreeBSD license (see LICENSE).
+
+# Namespace: IRC
+module IRC
+
+  # Namespace: Object
+  module Object
+
+    # A class which represents an individual IRC channel, its associated
+    # properties, the users which it contains, and methods to interact with it.
+    class Channel
+
+
+    end # class Channel
+
+  end # module Object
+
+end # module IRC
+
+# vim: set ts=4 sts=2 sw=2 et:

data/lib/syndi/irc/object/entity.rb

@@ -0,0 +1,90 @@
+# Copyright (c) 2013, Autumn Perrault, et al. All rights reserved.
+# This free software is distributed under the FreeBSD license (see LICENSE).
+
+module Syndi
+
+  module IRC
+  
+    module Object
+
+      # A superclass which represents an IRC 'entity'; i.e., a channel or user.
+      # It acts as a base for {Syndi::IRC::Object::User} and {Syndi::IRC::Object::Channel}.
+      #
+      # @api IRC
+      # @since 4.0.0
+      # @author noxgirl
+      #
+      # @!attribute [r] irc
+      #   @return [Syndi::IRC::Server] The IRC server on which this entity exists.
+      #
+      # @!attribute [r] name
+      #   @return [String] The name of the entity.
+      class Entity
+
+        attr_reader :irc, :name
+
+        # New instance.
+        #
+        # @param [Syndi::IRC::Server] irc The server.
+        # @param [Symbol] type Either +:channel+ or +:user+.
+        # @param [String] name The name of this entity (nickname or channel name).
+        def initialize(irc, type, name)
+          @irc         = irc
+          @entity_type = type
+          @name        = name
+        end
+
+        # @return [true, false] Whether we're a channel.
+        def channel?
+          @entity_type == :channel ? true : false
+        end
+        
+        # @return [true, false] Whether we're a user.
+        def user?
+          @entity_type == :user ? true : false
+        end
+
+        # Send a message to this entity. This will additionally divide messages
+        # which are too long into multiple messages.
+        #
+        # This will call irc:onMsg with +self+ and +message+.
+        #
+        # @param [String] message The message.
+        # @param [true, false] notice Whether this should be a /notice as opposed
+        #   to a /msg.
+        def msg(message, notice=false)
+          
+          command = (notice == false ? 'PRIVMSG' : 'NOTICE')
+          len     = ":#{@irc.nick}!#{@irc.user}@#{@irc.mask} #{command} #@name :".length
+          raw     = ":#{@irc.nick}!#{@irc.user}@#{@irc.mask} #{command} #@name :#{message}\r\n"
+
+          if raw.length > 512
+            
+            msgs     = []
+            nmessage = message 
+            until raw.length <= 512
+              msgs << nmessage.slice!(0, 512-len)
+              raw = ":#{@irc.nick}!#{@irc.user}@#{@irc.mask} #{command} #@name :#{nmessage}\r\n"
+            end
+            
+            msgs.each { |m| @irc.snd "#{command} #@name :#{m}" }
+          
+          else
+            @irc.snd "#{command} #@name :#{message}"
+          end
+
+          $m.events.call 'irc:onMsg', self, message
+
+        end # def msg
+
+        def to_s; @name; end
+
+      end # class Entity
+
+    end # module Object
+
+  end # module IRC
+
+end # module Syndi
+
+# vim: set ts=4 sts=2 sw=2 et:

data/lib/syndi/irc/object/message.rb

@@ -0,0 +1,99 @@
+# Copyright (c) 2013, Autumn Perrault, et al. All rights reserved.
+# This free software is distributed under the FreeBSD license (see LICENSE).
+
+# Namespace: IRC
+module IRC
+  
+  # Namespace: Object
+  module Object
+    
+    # A class which represents an IRC message, its associated properties, and
+    # offers methods for working with the message.
+    #
+    # @since 4.0.0
+    # @author noxgirl
+    # @api IRC
+    #
+    # @!attribute [r] irc
+    #   @return [IRC::Server] The server on which the message was received.
+    #
+    # @!attribute [r] sender
+    #   @return [IRC::Object::User] The user from whom the message was received.
+    #
+    # @!attribute [r] body
+    #   @return [Array<String>] The body of the message, divided into elements by its spaces.
+    #
+    # @!attribute [r] nature
+    #   @return [Symbol] The nature of the message, +:notice+ or +:msg+.
+    #
+    # @!attribute [r] channel
+    #   @return [nil] If this message was received privately and not through a channel, this is nil.
+    #   @return [IRC::Object::Channel] If it was received through a channel, the channel in question.
+    #   @see #in_channel?
+    class Message
+
+      attr_reader :irc, :sender, :body, :nature, :channel
+
+      # Process a new message.
+      #
+      # @param [IRC::Server] irc The server on which the message was received.
+      # @param [IRC::Object::User] sender The user from whom the message was received.
+      # @param [String] body The body of the message.
+      # @param [Symbol] nature The nature of the message: either a +:notice+ or a +:msg+.
+      # @param [IRC::Object::Channel] channel If it was received through a channel, the channel.
+      #
+      # @example
+      #   message = IRC::Object::Message.new(irc, user, body, :msg, channel)
+      def initialize(irc, sender, body, nature=:notice, channel=nil)
+
+        @irc     = irc
+        @sender  = sender
+        @body    = body
+        @nature  = nature
+        @channel = channel
+
+      end
+
+      # Reply to this message.
+      #
+      # @param [String] msg The message with which to reply.
+      # @param [true, false] in_channel If the response should be in-channel (assuming it was received in a channel), specify +true+.
+      #   If it should be private regardless of where it was received, specify +false+.
+      #
+      # @note Essentially reply() exists to simplify the API. 
+      #   Rather than necessitating that commands use endless, illegible conditional
+      #   nests to determine what to do, reply() is available so the API will just
+      #   use some common sense to do it for them.
+      #
+      # @example
+      #   msg.reply("The bar is of foo, indeed.", true)
+      #
+      # @todo Unfinished.
+      def reply(msg, in_channel)
+        
+        case [@channel.nil, in_channel, @nature]
+        
+        # Respond in-channel if this was sent to a channel *and* in_channel
+        # is specified as true.
+        when false, true, :msg
+          irc.msg(@channel, msg)
+
+        # Likewise for channel notices. 
+        when false, true, :notice
+          
+        end
+
+      end
+
+      # Checks whether the message was received through a channel.
+      #
+      # @return [true, false]
+      def in_channel?; @channel.nil?; end
+
+    end # class Message
+
+  end # module Object
+
+end # module IRC
+
+# vim: set ts=4 sts=2 sw=2 et:

data/lib/syndi/irc/object/user.rb

@@ -0,0 +1,139 @@
+# Copyright (c) 2013, Autumn Perrault, et al. All rights reserved.
+# This free software is distributed under the FreeBSD license (see LICENSE).
+
+module Syndi
+
+  # Namespace: IRC
+  module IRC
+
+    # Namespace: Object
+    module Object
+
+      # A class which represents an individual user on IRC, and which provides
+      # useful data regarding said user, and methods using which to interact
+      # with the user.
+      #
+      # @api IRC
+      # @since 4.0.0
+      # @author noxgirl
+      #
+      # @!attribute irc
+      #   @return [Syndi::IRC::Server] The server on which the user is located.
+      #
+      # @!attribute nick
+      #   @return [String] The user's nickname.
+      #
+      # @!attribute user
+      #   @return [String] If known, the user's username or ident.
+      #   @return [nil] If unknown.
+      #   @see #user_known?
+      #
+      # @!attribute host
+      #   @return [String] If known, the user's hostname or mask.
+      #   @return [nil] If unknown.
+      #   @see #host_known?
+      #
+      # @!attribute account
+      #   @return [String] If the user is logged in, their account name.
+      #   @see #logged_in?
+      #
+      # @!attribute away
+      #   @return [true] If the user is away.
+      #   @return [false] If the user is present.
+      class User < Entity
+
+        attr_reader :nick, :user, :host, :account, :away
+
+        # Process a new user.
+        #
+        # @param [Syndi::IRC::Server] irc The server the user is on.
+        # @param [String] nickname The user's nickname.
+        # @param [String] username The user's username or ident.
+        # @param [String] hostname The user's hostname or mask.
+        # @param [true, false] away Whether the user is away: +true+ or +false+.
+        #
+        # @example
+        #   user = Syndi::IRC::Object::User.new(irc, 'missfoo', 'cowmilk', 'the.night.is.lovely', false)
+        def initialize(irc, nickname, username=nil, hostname=nil, away=false)
+
+          super(irc, :user, nickname) # Entity#initialize
+          @nick    = nickname
+          @user    = username
+          @host    = hostname
+          @away    = away
+          @account = nil
+
+        end
+
+        # If the user logs into an account, this is used to specify the name of
+        # the account with which ze has identified.
+        #
+        # @param [String] accountname The name of the account.
+        #
+        # @example
+        #   user.login('root')
+        def login(accountname)
+          unless accountname.nil?
+            @account = accountname
+          end
+        end
+
+        # If the user logs out of hir account, this is used to update their
+        # logged-in status.
+        def logout
+          @account = nil
+        end
+
+        # Update the user's known away status.
+        #
+        # @param [true, false] new The user's new away status, which should be +true+ or +false+.
+        def away=(new)
+          if new == true or new == false
+            @away = new
+          end
+        end
+      
+        # Update the user's known hostname or mask.
+        #
+        # @param [String] new The user's new hostname.
+        def host=(new); @host = new unless new.nil?; end
+
+        # Update the user's known nickname.
+        #
+        # @param [String] new The user's new nickname.
+        def nick=(new); @nick = new unless new.nil?; end
+      
+        # Update the user's known username or ident.
+        #
+        # @param [String] new The user's new username.
+        def user=(new); @user = new unless new.nil?; end
+
+        # This will check whether the user's username is known.
+        #
+        # @return [true] If known.
+        # @return [false] If Unknown.
+        def user_known?; @user.nil? ? false : true; end
+      
+        # This will check whether the user's hostname is known.
+        #
+        # @return [true] If known.
+        # @return [false] If Unknown.
+        def host_known?; @host.nil? ? false : true; end
+      
+        # This will check whether the user is logged in.
+        #
+        # @return [true] If known.
+        # @return [false] If Unknown.
+        def logged_in?; @account.nil? ? false : true; end
+
+        def inspect; "#<Syndi::IRC::Object::User: irc=#@irc nick=#@nick account=#@account>"; end
+
+      end # class User
+
+    end # module Object
+
+  end # module IRC
+
+end # module Syndi
+
+# vim: set ts=4 sts=2 sw=2 et:

data/lib/syndi/irc/protocol/numerics.rb

@@ -0,0 +1,60 @@
+# Copyright (c) 2013, Autumn Perrault, et al. All rights reserved.
+# This free software is distributed under the FreeBSD license (see LICENSE).
+
+require 'syndi/irc/std/numerics'
+
+module Syndi
+
+  module IRC
+
+    class Protocol
+
+      # An extension of {Syndi::IRC::Protocol}, which parses numerics.
+      module Numerics
+        include Syndi::IRC::Std::Numerics
+
+        # RPL_WELCOME
+        define_method("on_#{RPL_WELCOME}") do |irc, raw, params|
+          $m.info "Successfully connected to #{irc} IRC network!" # log
+        end
+
+        # RPL_MYINFO
+        define_method("on_#{RPL_MYINFO}") do |irc, raw, params|
+          irc.supp.server_name = params[3]
+        end
+
+        # RPL_ISUPPORT
+        define_method("on_#{RPL_ISUPPORT}") do |irc, raw, params|
+          irc.supp.isupport(irc, params[3..-5].join(' ')) # process the isupport data
+          unless irc.supp.connected
+            irc.supp.connected = true
+            $m.irc.events.call :connected, irc # emit the :connected event
+          end
+        end
+
+        # RPL_SASLSUCCESS
+        define_method("on_#{RPL_SASLSUCCESS}") do |irc, raw, params|
+          $m.info "SASL authentication on #{irc} succeeded!"
+          irc.cap_end
+        end
+
+        # ERR_SASLFAIL
+        define_method("on_#{ERR_SASLFAIL}") do |irc, raw, params|
+          if irc.supp.sasl_method == :dh_blowfish
+            irc.authenticate # try again with the PLAIN mechanism
+          else
+            # ope, failed
+            $m.error "SASL authentication on #{irc} failed: received ERR_SASLFAIL from server."
+            irc.cap_end
+          end
+        end
+
+      end # class Numerics
+
+    end # class Protocol
+
+  end # module IRC
+
+end # module Syndi
+
+# vim: set ts=4 sts=2 sw=2 et: