[FEATURE] yielding dial object during Dial#dial (#623)

lib/adhearsion/call_controller/dial.rb

@@ -48,6 +48,8 @@ module Dial
       #
       # @option options [Array, #call] :ringback A collection of audio (see #play for acceptable values) to render as a replacement for ringback. If a callback is passed, it will be used to start ringback, and must return something that responds to #stop! to stop it.
       #
+      # @yield [Adhearsion::CallController::Dial::Dial] Provides the newly initialized Dial object to the given block, particularly useful in order to obtain a reference to it for later use.
+      #
       # @example Make a call to the PSTN using my SIP provider for VoIP termination
       #   dial "SIP/19095551001@my.sip.voip.terminator.us"
       #
@@ -61,6 +63,7 @@ module Dial
       #
       def dial(to, options = {})
         dial = Dial.new to, options, call
+        yield dial if block_given?
         dial.run(self)
         dial.await_completion
         dial.terminate_ringback

spec/adhearsion/call_controller/dial_spec.rb

@@ -1485,6 +1485,31 @@ def dial_in_thread
             end
           end
         end
+
+        context 'when given a block with one argument' do
+          before(:each) do
+            expect(other_mock_call).to receive(:dial).with(to, options).once
+            expect(OutboundCall).to receive(:new).and_return other_mock_call
+          end
+          let(:yield_latch) { CountDownLatch.new 1 }
+          let(:thread_latch) { CountDownLatch.new 1 }
+
+          it 'yields a block on the dial obj' do
+            my_dial_block = proc do |dial|
+              @dial_obj = dial
+              yield_latch.countdown!
+            end
+            Thread.new do
+              subject.dial to, options, &my_dial_block
+              thread_latch.countdown!
+            end
+            expect(yield_latch.wait(2)).to be_truthy
+            expect(@dial_obj).to be_instance_of Dial::Dial
+            other_mock_call << mock_answered
+            other_mock_call << mock_end
+            expect(thread_latch.wait(2)).to be_truthy
+          end
+        end
       end
 
       describe Dial::Dial do