README

= Batphone

link:../theme/batphone.png

Batphone is an Asterisk Gateway Interface (AGI) library for Ruby. It is
well-suited to simple bat-tasks, with a small learning curve. (I promise you'll
spend more time figuring out AGI than batphone). It is also perfectly capable
of making all your wildest AGI dreams come true. It won't get in your way.

1. http://www.voip-info.org/wiki-Asterisk+AGI

== Synopsis

In extensions.conf:

    exten => batphone,1,AGI(batphone.agi)

batphone.agi:

    #!/usr/bin/ruby
    require 'agi'

    agi = AGI.new
    agi.answer
    agi.stream_file('batman_help_the_monkeys_are_everywhere', nil)
    begin
      # press pound to make them stop!
      r = agi.stream_file('tt-monkeys', '#')
    end while r.result != ?#
    agi.stream_file('POW', nil)
    agi.hangup

== Requirements
Gee, Batman, all you need is Ruby. You might want Asterisk[http://asterisk.org]
too.

== Installation
Get it from GitHub[http://github.com/fugalh/batphone] and put it somewhere
batty.

    sudo rake install
or
    sudo ruby setup.rb

== Details
An AGI object serves as your proxy to Asterisk. Each time you send a command to
Asterisk using AGI#send or using the metaprogrammed interface, you get an
AGI::Response back. 

== TODO
- 5xx errors span multiple lines and should be handled by the lib (probably an
  exception raised too)
- It might be nice to have convenience methods that match up with regular
  Asterisk Applications (commands), e.g. Playback, Background, etc. 
- I'm inclined to make an OpenStruct-like interface to the Asterisk
  environment, but I need to make sure there won't be any metaprogramming
  conflitcs

== License
Copyright:: Copyright (C) 2007 Hans Fugal <mailto:hans@fugal.net>.
License:: Distributed under the same terms as Ruby.

== Colophon
Holy red phones, Batman! Asterisk is about phones. Rubies are red. Batphones
are really swell red phones. 

No relation to batsman[http://eigenclass.org/], though I think he's swell too.

The image is from an
article[http://www.millionaireplayboy.com/toys/batphone.php] on building your
own physical batphone at Millionaire Playboy.