adhearsion 2.0.0.rc5 → 2.0.0

data/README.markdown

@@ -1,24 +1,21 @@
-Adhearsion
-===========
+# Adhearsion
 
 Adhearsion is an open-source voice application development framework. Adhearsion users write applications atop the framework with Ruby and **call into their code**.
 
 Adhearsion rests above a lower-level telephony platform, for example [Asterisk](http://asterisk.org) or [Voxeo PRISM](http://voxeolabs.com/prism/), and provides a framework for integrating with various resources, such as SQL, LDAP and XMPP (Jabber).
 
-Features
---------
+## Features
 
-* An elegant system of call controllers for writing the code which controls a live phone call.
-* An events subsystem which maintains a Thread-pool for executing your namespaced callbacks.
-* A very useful plugin architecture with which you may write Adhearsion plugins and share them with the world via RubyGems.
-* JRuby compatibility for running atop the Java Virtual Machine and using virtually any Java library.
-* Ability to re-use existing Ruby on Rails database models with ActiveRecord/ActiveLDAP
-* Easy interactive communication via XMPP instant messages using the Blather library
-* Strong test coverage
-* Much more
+* Simple Ruby code
+* Flexible CallControllers to handle calls
+* High-level media handling constructs
+* Simple interaction between calls
+* Self-documenting configuration engine
+* Support for plugins and other code reuse
+* Integration with databases, web APIs, etc
+* Event monitoring, async communication
 
-Requirements
-------------
+## Requirements
 
 * Ruby 1.9.2+ or JRuby 1.6.7+
 * A VoIP platform:
@@ -26,13 +23,11 @@ Requirements
   * Prism 11+ with rayo-server
 * An interest in building cool new things
 
-Install
--------
+## Install
 
 `gem install adhearsion`
 
-Examples
---------
+## Examples
 
 An Adhearsion application can be as simple as this:
 
@@ -45,17 +40,13 @@ hangup
 
 For more examples, check out [the website](http://adhearsion.com/examples).
 
-Documentation
-=============
+## Documentation
 
 Visit [Adhearsion's website](http://adhearsion.com) for code examples and more information about the project. Also checkout the [Adhearsion wiki on Github](http://github.com/adhearsion/adhearsion/wiki) for community documentation.
 
 If you're having trouble, you may want to try asking your question on the IRC channel (#adhearsion on irc.freenode.net), [mailing list](http://groups.google.com/group/adhearsion) or, if you've found a bug, report it on the [bug tracker](https://github.com/adhearsion/adhearsion/issues).
 
-Author
-------
-
-Original author: [Jay Phillips](https://github.com/jicksta)
+## Author
 
 Core team:
 
@@ -65,13 +56,13 @@ Core team:
 
 Contributors: https://github.com/adhearsion/adhearsion/contributors
 
-Contributions
------------------------------
+Original author: [Jay Phillips](https://github.com/jicksta)
+
+### Contributions
 
 Adhearsion has a set of [contribution guidelines](https://github.com/adhearsion/adhearsion/wiki/Contributing) which help to smooth the contribution process.
 There is a pre-commit hook that runs encoding checks available in pre-commit. To use it, please copy it to .git/hooks/pre-commit and make it executable.
 
-Copyright
----------
+### Copyright
 
-Copyright (c) 2011 Individual contributors. GNU LESSER GENERAL PUBLIC LICENSE (see LICENSE for details).
+Copyright (c) 2012 Adhearsion Foundation Inc. MIT LICENSE (see LICENSE for details).

data/adhearsion.gemspec

@@ -7,53 +7,44 @@ Gem::Specification.new do |s|
   s.version     = Adhearsion::VERSION
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Jay Phillips", "Jason Goecke", "Ben Klang", "Ben Langfeld"]
-  s.email       = "dev&Adhearsion.com"
+  s.email       = "dev@adhearsion.com"
   s.homepage    = "http://adhearsion.com"
   s.summary     = "Adhearsion, open-source telephony development framework"
   s.description = "Adhearsion is an open-source telephony development framework"
-  s.date        = Date.today.to_s
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  # Runtime dependencies
-  s.add_runtime_dependency 'bundler', [">= 1.0.10"]
-  s.add_runtime_dependency 'punchblock', [">= 0.12.0"]
-  s.add_runtime_dependency 'logging', [">= 1.6.1"]
-  s.add_runtime_dependency 'adhearsion-loquacious', [">= 1.9.0"]
   s.add_runtime_dependency 'activesupport', [">= 3.0.10"]
-  # i18n is only strictly a dependency for ActiveSupport >= 3.0.0
-  # Since it doesn't conflict with <3.0.0 we'll require it to be
-  # on the safe side.
-  s.add_runtime_dependency 'i18n', [">= 0.5.0"]
-  s.add_runtime_dependency 'json'
-  s.add_runtime_dependency 'thor'
-  s.add_runtime_dependency 'rake'
-  s.add_runtime_dependency 'pry'
-  s.add_runtime_dependency 'uuid'
-  s.add_runtime_dependency 'future-resource', [">= 0.0.2"]
-  s.add_runtime_dependency 'ruby_speech', [">= 0.4.0"]
+  s.add_runtime_dependency 'adhearsion-loquacious', [">= 1.9.0"]
+  s.add_runtime_dependency 'bundler', ["~> 1.0"]
+  s.add_runtime_dependency 'celluloid', [">= 0.10.0"]
   s.add_runtime_dependency 'countdownlatch'
-  s.add_runtime_dependency 'has-guarded-handlers', [">= 1.1.0"]
+  s.add_runtime_dependency 'deep_merge'
+  s.add_runtime_dependency 'ffi', [">= 1.0.11"]
+  s.add_runtime_dependency 'future-resource', ["~> 1.0"]
   s.add_runtime_dependency 'girl_friday'
+  s.add_runtime_dependency 'has-guarded-handlers', ["~> 1.1"]
   s.add_runtime_dependency 'jruby-openssl' if RUBY_PLATFORM == 'java'
-  s.add_runtime_dependency 'ffi', [">= 1.0.11"]
-  s.add_runtime_dependency 'celluloid', [">= 0.10.0"]
-  s.add_runtime_dependency 'deep_merge'
+  s.add_runtime_dependency 'logging', [">= 1.6.1"]
+  s.add_runtime_dependency 'pry'
+  s.add_runtime_dependency 'punchblock', ["~> 1.0"]
+  s.add_runtime_dependency 'rake'
+  s.add_runtime_dependency 'ruby_speech', ["~> 1.0"]
+  s.add_runtime_dependency 'thor'
+  s.add_runtime_dependency 'uuid'
 
-  # Development dependencies
-  s.add_development_dependency 'rspec', ["~> 2.7.0"]
+  s.add_development_dependency 'aruba'
+  s.add_development_dependency 'ci_reporter'
+  s.add_development_dependency 'cucumber'
   s.add_development_dependency 'flexmock'
-  s.add_development_dependency 'activerecord', [">= 3.0.10"]
+  s.add_development_dependency 'guard-cucumber'
+  s.add_development_dependency 'guard-rspec'
+  s.add_development_dependency 'rspec', ["~> 2.7.0"]
+  s.add_development_dependency 'ruby_gntp'
   s.add_development_dependency 'simplecov'
   s.add_development_dependency 'simplecov-rcov'
-  s.add_development_dependency 'ci_reporter'
   s.add_development_dependency 'yard'
-  s.add_development_dependency 'guard-rspec'
-  s.add_development_dependency 'guard-cucumber'
-  s.add_development_dependency 'ruby_gntp'
-  s.add_development_dependency 'cucumber'
-  s.add_development_dependency 'aruba'
 end

data/lib/adhearsion.rb

@@ -94,7 +94,10 @@ end
 Celluloid.exception_handler { |e| Adhearsion::Events.trigger :exception, e }
 
 module Celluloid
-  def self.logger
-    ::Logging.logger['Celluloid']
+  class << self
+    undef :logger
+    def logger
+      ::Logging.logger['Celluloid']
+    end
   end
 end

data/lib/adhearsion/call.rb

@@ -25,7 +25,10 @@ module Adhearsion
       end
     end
 
-    attr_accessor :offer, :client, :end_reason, :commands, :variables, :controllers
+    # @private
+    attr_accessor :offer, :client, :end_reason, :commands, :controllers
+
+    attr_accessor :variables
 
     delegate :[], :[]=, :to => :variables
     delegate :to, :from, :to => :offer, :allow_nil => true
@@ -42,28 +45,46 @@ module Adhearsion
       self << offer if offer
     end
 
+    #
+    # @return [String, nil] The globally unique ID for the call
+    #
     def id
       offer.target_call_id if offer
     end
 
+    #
+    # @return [Array] The set of labels with which this call has been tagged.
+    #
     def tags
       @tags.clone
     end
 
-    # This may still be a symbol, but no longer requires the tag to be a symbol although beware
-    # that using a symbol would create a memory leak if used improperly
+    #
+    # Tag a call with an arbitrary label
+    #
     # @param [String, Symbol] label String or Symbol with which to tag this call
+    #
     def tag(label)
       abort ArgumentError.new "Tag must be a String or Symbol" unless [String, Symbol].include?(label.class)
       @tags << label
     end
 
-    def remove_tag(symbol)
-      @tags.reject! { |tag| tag == symbol }
+    #
+    # Remove a label
+    #
+    # @param [String, Symbol] label
+    #
+    def remove_tag(label)
+      @tags.reject! { |tag| tag == label }
     end
 
-    def tagged_with?(symbol)
-      @tags.include? symbol
+    #
+    # Establish if the call is tagged with the provided label
+    #
+    # @param [String, Symbol] label
+    #
+    def tagged_with?(label)
+      @tags.include? label
     end
 
     def register_event_handler(*guards, &block)
@@ -74,10 +95,10 @@ module Adhearsion
       logger.debug "Receiving message: #{message.inspect}"
       catching_standard_errors { trigger_handler :event, message }
     end
-
     alias << deliver_message
 
-    def register_initial_handlers # :nodoc:
+    # @private
+    def register_initial_handlers
       register_event_handler Punchblock::Event::Offer do |offer|
         @offer  = offer
         @client = offer.client
@@ -110,7 +131,8 @@ module Adhearsion
       end
     end
 
-    def after_end_hold_time # :nodoc:
+    # @private
+    def after_end_hold_time
       30
     end
 
@@ -121,6 +143,9 @@ module Adhearsion
       end
     end
 
+    #
+    # @return [Boolean] if the call is currently active or not (disconnected)
+    #
     def active?
       !end_reason
     end
@@ -144,7 +169,8 @@ module Adhearsion
       write_and_await_response Punchblock::Command::Hangup.new(:headers => headers)
     end
 
-    def clear_from_active_calls # :nodoc:
+    # @private
+    def clear_from_active_calls
       Adhearsion.active_calls.remove_inactive_call current_actor
     end
 
@@ -157,7 +183,7 @@ module Adhearsion
     # @param [Hash, Optional] options further options to be joined with
     #
     def join(target, options = {})
-      command = Punchblock::Command::Join.new join_options_with_target(target, options)
+      command = Punchblock::Command::Join.new options.merge(join_options_with_target(target))
       write_and_await_response command
     end
 
@@ -173,8 +199,9 @@ module Adhearsion
       write_and_await_response command
     end
 
-    def join_options_with_target(target, options = {})
-      options.merge(case target
+    # @private
+    def join_options_with_target(target)
+      case target
       when Call
         { :call_id => target.id }
       when String
@@ -184,7 +211,7 @@ module Adhearsion
         target
       else
         abort ArgumentError.new "Don't know how to join to #{target.inspect}"
-      end)
+      end
     end
 
     def wait_for_joined(expected_target)
@@ -209,6 +236,7 @@ module Adhearsion
       write_and_await_response ::Punchblock::Command::Unmute.new
     end
 
+    # @private
     def write_and_await_response(command, timeout = 60)
       commands << command
       write_command command
@@ -229,6 +257,7 @@ module Adhearsion
       abort CommandTimeout.new(command.to_s)
     end
 
+    # @private
     def write_command(command)
       abort Hangup.new(@end_reason) unless active? || command.is_a?(Punchblock::Command::Hangup)
       variables.merge! command.headers_hash if command.respond_to? :headers_hash
@@ -236,18 +265,22 @@ module Adhearsion
       client.execute_command command, :call_id => id, :async => true
     end
 
-    def logger_id # :nodoc:
+    # @private
+    def logger_id
       "#{self.class}: #{id}"
     end
 
-    def logger # :nodoc:
+    # @private
+    def logger
       super
     end
 
+    # @private
     def to_ary
       [current_actor]
     end
 
+    # @private
     def inspect
       attrs = [:offer, :end_reason, :commands, :variables, :controllers, :to, :from].map do |attr|
         "#{attr}=#{send(attr).inspect}"
@@ -268,24 +301,28 @@ module Adhearsion
       end.tap { |t| Adhearsion::Process.important_threads << t }
     end
 
+    # @private
     def register_controller(controller)
       @controllers << controller
     end
 
+    # @private
     def pause_controllers
       controllers.each(&:pause!)
     end
 
+    # @private
     def resume_controllers
       controllers.each(&:resume!)
     end
 
-    class CommandRegistry < ThreadSafeArray # :nodoc:
+    # @private
+    class CommandRegistry < ThreadSafeArray
       def terminate
         hangup = Hangup.new
         each { |command| command.response = hangup if command.requested? }
       end
     end
 
-  end#Call
-end#Adhearsion
+  end
+end

data/lib/adhearsion/call_controller.rb

@@ -35,6 +35,11 @@ module Adhearsion
     end
 
     class << self
+      #
+      # Execute a call controller, allowing passing control to another controller
+      #
+      # @param [CallController] controller
+      #
       def exec(controller)
         new_controller = catch :pass_controller do
           controller.execute!
@@ -44,23 +49,35 @@ module Adhearsion
         exec new_controller if new_controller
       end
 
-      ##
+      #
       # Include another module into all CallController classes
+      #
       def mixin(mod)
         include mod
       end
     end
 
-    attr_reader :call, :metadata, :block
+    attr_reader :call, :metadata
+
+    # @private
+    attr_reader :block
 
     delegate :[], :[]=, :to => :@metadata
     delegate :variables, :logger, :to => :call
 
+    #
+    # Create a new instance
+    #
+    # @param [Call] call the call to operate the controller on
+    # @param [Hash] metadata generic key-value storage applicable to the controller
+    # @param block to execute on the call
+    #
     def initialize(call, metadata = nil, &block)
       @call, @metadata, @block = call, metadata || {}, block
     end
 
-    def execute!(*options) # :nodoc:
+    # @private
+    def execute!(*options)
       call.register_controller! self
       execute_callbacks :before_call
       run
@@ -73,20 +90,36 @@ module Adhearsion
       logger.debug "Finished executing controller #{self.inspect}"
     end
 
+    #
+    # Invoke the block supplied when creating the controller
+    #
     def run
       instance_exec(&block) if block
     end
 
+    #
+    # Invoke another controller class within this controller, returning to this context on completion.
+    #
+    # @param [Class] controller_class The class of controller to execute
+    # @param [Hash] metadata generic key-value storage applicable to the controller
+    #
     def invoke(controller_class, metadata = nil)
       controller = controller_class.new call, metadata
       controller.run
     end
 
+    #
+    # Cease execution of this controller, and pass to another.
+    #
+    # @param [Class] controller_class The class of controller to pass to
+    # @param [Hash] metadata generic key-value storage applicable to the controller
+    #
     def pass(controller_class, metadata = nil)
       throw :pass_controller, controller_class.new(call, metadata)
     end
 
-    def execute_callbacks(type) # :nodoc:
+    # @private
+    def execute_callbacks(type)
       self.class.callbacks[type].each do |callback|
         catching_standard_errors do
           instance_exec(&callback)
@@ -94,21 +127,29 @@ module Adhearsion
       end
     end
 
-    def after_call # :nodoc:
+    # @private
+    def after_call
       @after_call ||= execute_callbacks :after_call
     end
 
+    #
+    # Hangup the call, and execute after_call callbacks
+    #
+    # @param [Hash] headers
+    #
     def hangup(headers = nil)
       block_until_resumed
       hangup_response = call.hangup headers
       after_call unless hangup_response == false
     end
 
+    # @private
     def write_and_await_response(command)
       block_until_resumed
       call.write_and_await_response command
     end
 
+    # @private
     def execute_component_and_await_completion(component)
       write_and_await_response component
 
@@ -119,33 +160,58 @@ module Adhearsion
       component
     end
 
+    #
+    # Answer the call
+    #
+    # @see Call#answer
+    #
     def answer(*args)
       block_until_resumed
       call.answer(*args)
     end
 
+    #
+    # Reject the call
+    #
+    # @see Call#reject
+    #
     def reject(*args)
       block_until_resumed
       call.reject(*args)
     end
 
+    #
+    # Mute the call
+    #
+    # @see Call#mute
+    #
     def mute(*args)
       block_until_resumed
       call.mute(*args)
     end
 
+    #
+    # Unmute the call
+    #
+    # @see Call#unmute
+    #
     def unmute(*args)
       block_until_resumed
       call.unmute(*args)
     end
 
+    #
+    # Join the call to another call or a mixer, and block until the call is unjoined (by hangup or otherwise).
+    #
+    # @param [Object] target See Call#join for details
+    # @param [Hash] options
+    # @option options [Boolean] :async Return immediately, without waiting for the calls to unjoin. Defaults to false.
+    #
+    # @see Call#join
+    #
     def join(target, options = {})
-      async = if target.is_a?(Hash)
-        target.delete :async
-      else
-        options.delete :async
-      end
       block_until_resumed
+      async = (target.is_a?(Hash) ? target : options).delete :async
       join_command = call.join target, options
       waiter = join_command.call_id || join_command.mixer_name
       if async
@@ -155,20 +221,24 @@ module Adhearsion
       end
     end
 
-    def block_until_resumed # :nodoc:
+    # @private
+    def block_until_resumed
       instance_variable_defined?(:@pause_latch) && @pause_latch.wait
     end
 
-    def pause! # :nodoc:
+    # @private
+    def pause!
       @pause_latch = CountDownLatch.new 1
     end
 
-    def resume! # :nodoc:
+    # @private
+    def resume!
       return unless @pause_latch
       @pause_latch.countdown!
       @pause_latch = nil
     end
 
+    # @private
     def inspect
       "#<#{self.class} call=#{call.id}, metadata=#{metadata.inspect}>"
     end