adhearsion 0.7.7 → 0.8.0

data/lib/adhearsion/voip/menu_state_machine/matchers.rb

@@ -0,0 +1,123 @@
+require File.join(File.dirname(__FILE__), 'calculated_match')
+
+module Adhearsion
+  module VoIP
+    class MatchCalculator
+
+      class << self
+
+        def build_with_pattern(pattern, match_payload, &block)
+          class_for_pattern_type(pattern.class.name).new(pattern, match_payload, &block)
+        end
+
+        def inherited(klass)
+          subclasses << klass
+        end
+
+        private
+
+        def class_for_pattern_type(pattern_type)
+          sought_class_name = "Adhearsion::VoIP::#{pattern_type.camelize}MatchCalculator"
+          subclasses.find { |klass| klass.name == sought_class_name }
+        end
+
+        def subclasses
+          @@subclasses ||= []
+        end
+
+      end
+
+      attr_reader :pattern, :match_payload
+      def initialize(pattern, match_payload)
+        @pattern, @match_payload = pattern, match_payload
+      end
+
+      protected
+
+      def new_calculated_match(options)
+        CalculatedMatch.new({:pattern => pattern, :match_payload => match_payload}.merge(options))
+      end
+
+      def coerce_to_numeric(victim)
+        victim.kind_of?(Numeric) ? victim : (victim.to_s =~ /^\d+$/ ? victim.to_s.to_i : nil )
+      end
+    end
+
+    class RangeMatchCalculator < MatchCalculator
+
+      def initialize(pattern, match_payload)
+        raise unless pattern.first.kind_of?(Numeric) && pattern.last.kind_of?(Numeric)
+        super
+      end
+
+      def match(query)
+        numerical_query = coerce_to_numeric query
+        if numerical_query      
+          exact_match = pattern.include?(numerical_query) ? query : nil
+          potential_matches = numbers_in_range_like numerical_query
+          potential_matches.reject! { |m| m.to_s == exact_match.to_s } if exact_match
+    
+          new_calculated_match :query => query, :exact_matches => exact_match,
+                               :potential_matches => potential_matches
+        else
+          CalculatedMatch.failed_match!(pattern, query, match_payload)
+        end
+      end
+
+      private
+
+      # Returns all numbers in the range (@pattern) that +begin with+ the number given
+      # as the first argument.
+      #
+      # NOTE! If you're having trouble reading what this method is actually doing, it's
+      # effectively a much more efficient version of this:
+      #
+      # pattern.to_a.select { |x| x.to_s.starts_with? num.to_s }.flatten
+      #
+      # Huge thanks to Dave Troy (http://davetroy.blogspot.com) for this awesomely
+      # efficient code!
+      def numbers_in_range_like(num)
+        return (pattern === 0 ? [0] : nil) if num == 0
+        raise ArgumentError unless num.kind_of?(Numeric)
+        returning Array.new do |matches|
+          first, last = pattern.first, pattern.last
+          power = 0
+          while num < last
+            ones_count = 10**power - 1
+            matches.concat((([num, first].max)..[(num+ones_count), last].min).to_a)
+            num *= 10
+            power += 1
+          end
+        end
+      end
+    end
+
+    class FixnumMatchCalculator < MatchCalculator
+      def match(query)
+        numeric_query = coerce_to_numeric query
+        exact_match, potential_match = nil
+        if pattern == numeric_query
+          exact_match = pattern
+        elsif pattern.to_s.starts_with? query.to_s
+          potential_match = pattern
+        end
+        new_calculated_match :query => query, :exact_matches => exact_match, :potential_matches => potential_match
+      end
+    end
+
+    class StringMatchCalculator < MatchCalculator
+      def match(query)
+        args = { :query => query, :exact_matches => nil,
+                 :potential_matches => nil }
+
+        if pattern == query.to_s
+          args[:exact_matches] = [pattern]
+        elsif pattern.starts_with? query.to_s
+          args[:potential_matches] = [pattern]
+        end
+
+        new_calculated_match args
+      end
+    end
+  end
+end

data/lib/adhearsion/voip/menu_state_machine/menu_builder.rb

@@ -0,0 +1,58 @@
+require File.join(File.dirname(__FILE__), 'matchers.rb')
+
+module Adhearsion
+  module VoIP
+    class MenuBuilder
+
+      def initialize
+        @patterns = []
+        @menu_callbacks = {}
+      end
+
+      def method_missing(match_payload, *patterns, &block)
+        name_string = match_payload.to_s
+        if patterns.any?
+          patterns.each do |pattern|
+            @patterns << MatchCalculator.build_with_pattern(pattern, match_payload)
+          end
+        else
+          raise ArgumentError, "You cannot call this method without patterns!"
+        end
+        nil
+      end
+
+      def weighted_match_calculators
+        @patterns
+      end
+
+      def execute_hook_for(symbol, input)
+        callback = @menu_callbacks[symbol]
+        callback.call input if callback
+      end
+
+      def on_invalid(&block)
+        raise LocalJumpError, "Must supply a block!" unless block_given?
+        @menu_callbacks[:invalid] = block
+      end
+
+      def on_premature_timeout(&block)
+        raise LocalJumpError, "Must supply a block!" unless block_given?
+        @menu_callbacks[:premature_timeout] = block
+      end
+
+      def on_failure(&block)
+        raise LocalJumpError, "Must supply a block!" unless block_given?
+        @menu_callbacks[:failure] = block
+      end
+
+      def calculate_matches_for(result)
+        returning CalculatedMatchCollection.new do |collection|
+          weighted_match_calculators.each do |pattern|
+            collection << pattern.match(result)
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/adhearsion/voip/menu_state_machine/menu_class.rb

@@ -0,0 +1,149 @@
+require 'adhearsion/voip/menu_state_machine/menu_builder'
+module Adhearsion
+  module VoIP
+    class Menu
+
+      DEFAULT_MAX_NUMBER_OF_TRIES = 1
+      DEFAULT_TIMEOUT             = 5 # seconds
+
+      relationships :menu_builder => MenuBuilder
+
+      attr_reader :builder, :timeout, :tries_count, :max_number_of_tries
+      def initialize(options={}, &block)
+        @tries_count         = 0 # Counts the number of tries the menu's been executed
+        
+        @timeout             = options[:timeout] || DEFAULT_TIMEOUT
+        @max_number_of_tries = options[:tries]   || DEFAULT_MAX_NUMBER_OF_TRIES
+
+        @builder = menu_builder.new
+        yield @builder
+
+        initialize_digit_buffer
+      end
+
+      def <<(other)
+        digit_buffer << other
+      end
+      
+      def digit_buffer
+        @digit_buffer
+      end
+      
+      def digit_buffer_string
+        digit_buffer.to_s
+      end
+      
+      def digit_buffer_empty?
+        digit_buffer.empty?
+      end
+
+      def continue
+        raise MenuGetAnotherDigitOrTimeout if digit_buffer_empty?
+
+        calculated_matches = builder.calculate_matches_for digit_buffer_string
+
+        if calculated_matches.exact_match_count >= 1
+          first_exact_match = calculated_matches.exact_matches.first
+          if calculated_matches.potential_match_count.zero?
+            # Match found with no extenuating ambiguities! Go with the first exact match
+            menu_result_found! first_exact_match.match_payload, digit_buffer_string
+          else
+            get_another_digit_or_finish!(first_exact_match.match_payload, first_exact_match.query)
+          end
+        elsif calculated_matches.potential_match_count >= 1
+          get_another_digit_or_timeout!
+        else
+          invalid!
+        end
+      end
+
+      def should_continue?
+        tries_count < max_number_of_tries
+      end
+
+      def restart!
+        @tries_count += 1
+        digit_buffer.clear!
+      end
+
+      def execute_invalid_hook
+        builder.execute_hook_for(:invalid, digit_buffer_string)
+      end
+
+      def execute_timeout_hook
+        builder.execute_hook_for(:premature_timeout, digit_buffer_string)
+      end
+
+      def execute_failure_hook
+        builder.execute_hook_for(:failure, digit_buffer_string)
+      end
+
+      protected
+      
+      # If you're using a more complex class in subclasses, you may want to override this method in addition to the 
+      # digit_buffer, digit_buffer_empty, and digit_buffer_string methods
+      def initialize_digit_buffer
+        @digit_buffer = ClearableStringBuffer.new
+      end
+
+      def invalid!
+        raise MenuResultInvalid
+      end
+
+      def menu_result_found!(match_payload, new_extension)
+        raise MenuResultFound.new(match_payload, new_extension)
+      end
+
+      def get_another_digit_or_finish!(match_payload, new_extension)
+        raise MenuGetAnotherDigitOrFinish.new(match_payload, new_extension)
+      end
+
+      def get_another_digit_or_timeout!
+        raise MenuGetAnotherDigitOrTimeout
+      end
+
+      # The superclass from which all message-like exceptions decend. It should never
+      # be instantiated directly.
+      class MenuResult < Exception; end
+
+      # Raised when the user's input matches
+      class MenuResultFound < MenuResult
+        attr_reader :match_payload, :new_extension
+        def initialize(match_payload, new_extension)
+          super()
+          @match_payload  = match_payload
+          @new_extension = new_extension
+        end
+      end
+
+      module MenuGetAnotherDigit; end
+
+      class MenuGetAnotherDigitOrFinish < MenuResultFound
+        include MenuGetAnotherDigit
+      end
+
+      class MenuGetAnotherDigitOrTimeout < MenuResult
+        include MenuGetAnotherDigit
+      end
+
+      class MenuResultFound < MenuResult; end
+
+      # Raised when the user's input matches no patterns
+      class MenuResultInvalid < MenuResult; end
+
+      # For our default purposes, we need the digit_buffer to behave much like a normal String except that it should 
+      # handle its own resetting (clearing).
+      class ClearableStringBuffer < String
+        def clear!
+          replace ""
+        end
+        
+        def <<(other)
+          super other.to_s
+        end
+        
+      end
+
+    end
+  end
+end

data/lib/theatre.rb

@@ -0,0 +1,151 @@
+require 'thread'
+require 'rubygems'
+
+$: << File.expand_path(File.dirname(__FILE__))
+
+require 'theatre/version'
+require 'theatre/namespace_manager'
+require 'theatre/invocation'
+require 'theatre/callback_definition_loader'
+
+module Theatre
+  
+  class Theatre
+    
+    attr_reader :namespace_manager
+    
+    ##
+    # Creates a new stopped Theatre. You must call start!() after you instantiate this for it to begin processing events.
+    #
+    # @param [Fixnum] thread_count Number of Threads to spawn when started.
+    #
+    def initialize(thread_count=6)
+      @thread_count      = thread_count
+      @started           = false
+      @namespace_manager = ActorNamespaceManager.new
+      @thread_group      = ThreadGroup.new
+      @master_queue      = Queue.new
+      @loader_mixins     = []
+    end
+    
+    ##
+    # Send a message to this Theatre for asynchronous processing.
+    #
+    # @param [String] namespace The namespace to which the payload should be sent
+    # @param [Object] payload The actual content to be sent to the callback. Optional.
+    # @return [Array<Theatre::Invocation>] An Array of Invocation objects
+    # @raise Theatre::NamespaceNotFound Raised when told to enqueue an unrecognized namespace
+    #
+    def trigger(namespace, payload=:argument_undefined)
+      @namespace_manager.callbacks_for_namespaces(namespace).map do |callback|
+        invocation = if payload.equal?(:argument_undefined)
+          Invocation.new(namespace, callback)
+        else
+          Invocation.new(namespace, callback, payload)
+        end
+        invocation.queued
+        @master_queue << invocation
+        invocation
+      end
+    end
+    
+    ##
+    # Send a message to this Theatre for synchronous processing. The execution of this will not go through this Theatre's
+    # Thread pool. If an error occurred in any of callbacks, the Exception object will be placed in the returned Array 
+    # instead for you to act upon.
+    #
+    # @param [String] namespace The namespace to which the payload should be sent
+    # @param [Object] payload The actual content to be sent to the callback. Optional.
+    # @return [Array] An Array containing each callback's return value (or Exception raised, if any) when given the payload
+    # @raise Theatre::NamespaceNotFound Raised when told to enqueue an unrecognized namespace
+    #
+    def trigger_immediately(namespace, payload=:argument_undefined)
+      @namespace_manager.callbacks_for_namespaces(namespace).map do |callback|
+        begin
+          invocation = if payload.equal?(:argument_undefined)
+            callback.call
+          else
+            callback.call payload
+          end
+        rescue => captured_error_to_be_returned
+          captured_error_to_be_returned
+        end
+      end
+    end
+    
+    def load_events_code(code, *args)
+      loader = CallbackDefinitionLoader.new(self, *args)
+      loader.load_events_code code
+    end
+    
+    def load_events_file(file, *args)
+      loader = CallbackDefinitionLoader.new(self, *args)
+      loader.load_events_file file
+    end
+    
+    def register_namespace_name(*args)
+      @namespace_manager.register_namespace_name(*args)
+    end
+    
+    def register_callback_at_namespace(*args)
+      @namespace_manager.register_callback_at_namespace(*args)
+    end
+    
+    def register_loader_mixin(mod)
+      @loader_mixins << mod
+    end
+    
+    def join
+      @thread_group.list.each do |thread|
+        begin
+          thread.join
+        rescue
+          # Ignore any exceptions
+        end
+      end
+    end
+    
+    ##
+    # Starts this Theatre.
+    #
+    # When this method is called, the Threads are spawned and begin pulling messages off this Theatre's master queue.
+    #
+    def start!
+      return false if @thread_group.list.any? # Already started
+      @started_time = Time.now
+      @thread_count.times do
+        @thread_group.add Thread.new(&method(:thread_loop))
+      end
+    end
+    
+    ##
+    # Notifies all Threads for this Theatre to stop by sending them special messages. Any messages which were queued and
+    # untriggered when this method is received will still be processed. Note: you may start this Theatre again later once it
+    # has been stopped.
+    #
+    def graceful_stop!
+      @thread_count.times { @master_queue << :THEATRE_SHUTDOWN! }
+      @started_time = nil
+    end
+    
+    protected
+    
+    # This will use the Adhearsion logger eventually.
+    def warn(exception)
+      # STDERR.puts exception.message, *exception.backtrace
+    end
+    
+    def thread_loop
+      loop do
+        begin
+          next_invocation = @master_queue.pop
+          return :stopped if next_invocation.equal? :THEATRE_SHUTDOWN!
+          next_invocation.start
+        rescue => error
+          warn error
+        end
+      end
+    end
+    
+  end
+end