adammck-rubysms 0.8.1

data/README.rdoc

@@ -0,0 +1,50 @@
+RubySMS is a Ruby library (not a framework, although it's coming dangerously close)
+which aims to make developing and deploying SMS applications easy. The sending and
+receiving of "real" SMS is handled by RubyGSM[http://github.com/adammck/rubygsm],
+but RubySMS also provides a couple of ways to interact with "mock" SMS via a web
+interface (the HTTP Backend) and GTK GUI (the DRB backend).
+
+RubySMS was initially developed in Malawi by {The UNICEF Innovation Team}[http://unicefinnovation.org/about.php]
+and a group from Columbia University's {SIPA}[http://sipa.columbia.edu/] as the technical foundation of the 
+{RapidSMS Child Malnutrition Survelliance}[http://netsquared.org/projects/child-malnutrition-surveillance-and-famine-response]
+(see {the source code}[http://github.com/adammck/columbawawi]) entry to the {USAID Development 2.0 Challenge}[http://netsquared.org/usaid]... 
+which[http://globaldevelopmentcommons.net/node/876]
+we[http://unicef.org/infobycountry/usa_47068.html]
+won[http://sipa.columbia.edu/news_events/announcements/sipanews10.html].
+
+
+=== Sample Application
+
+  require "rubygems"
+  require "rubysms"
+
+  class DemoApp < SMS::App
+    def incoming(msg)
+      msg.respond("Wow, that was easy!")
+    end
+  end
+
+  DemoApp.serve!
+
+
+=== Installing
+RubySMS is distributed via GitHub[http://github.com/adammck/rubysms], which you must
+add as a Gem source before installing:
+
+  $ sudo gem sources -a http://gems.github.com
+
+Then install the Gem, which will automatically pull in the dependencies:
+
+  $ sudo gem install adammck-rubysms
+
+
+=== Dependencies
+If you'd prefer to run RubySMS from the trunk, you'll need to install the following
+Gems manually (otherwise, the HTTP backend will explode on startup. Remind me to fix
+that some time).
+
+  $ sudo gem install rack mongrel
+
+If you'd like to send real SMS via a GSM modem, you'll also need RubyGSM:
+
+  $ sudo gem install adammck-rubygsm

data/bin/rubysms-drb-client

@@ -0,0 +1,168 @@
+#!/usr/bin/env ruby
+
+require "libglade2.rb"
+require "drb.rb"
+
+SERVER_PORT = "1370"
+
+class SmsGui
+	include GetText
+	attr :glade
+	
+	def initialize
+		
+		# if this file is a symlink (which is probably is, since rubygems
+		# automatically symlinks bin files into /usr/bin), find the original
+		# source file, so we can find the glade src relatively
+		this_file = File.symlink?(__FILE__) ? \
+			File.readlink(__FILE__) : __FILE__
+		
+		# find and load up the glade src for the gui
+		glade_src = File.expand_path(File.dirname(this_file) + "/../lib/drb-client.glade")
+		@glade = GladeXML.new(glade_src) do |handler|
+			method(handler)
+		end
+		
+		# for storing outgoing
+		# messages for recall
+		@history = []
+		@hist_pos = 0
+		
+		# fetch references to the gtk widgets
+		@source = @glade.get_widget("entry_source")
+		@entry = @glade.get_widget("entry_message")
+		@log = @glade.get_widget("textview_log")
+		@lb = @log.buffer
+		
+		# create a text mark to keep at the end of
+		# the log, so we can keep scrolling to it
+		@lb.create_mark("end", @lb.end_iter, true)
+		
+		# create colors for incoming and outgoing messages
+		@lb.create_tag("incoming", "family"=>"monospace", "foreground"=>"#AA0000")
+		@lb.create_tag("outgoing", "family"=>"monospace", "foreground"=>"#0000AA")
+		@lb.create_tag("error", "family"=>"monospace", "foreground"=>"#FFFFFF", "background"=>"#FF0000")
+		
+		# prepopulate the source phone number with six digits
+		@src = (1111 + rand(8888)).to_s
+		@source.text = @src
+		
+		# fire up drb, to send outgoing messages to rubysms
+		@injector = DRbObject.new_with_uri("druby://localhost:#{SERVER_PORT}")
+		puts "Connected to RubySMS at: #{@injector.__drburi}"
+		
+		# start listening for incoming messages from rubysms
+		@drb = DRb.start_service("druby://localhost:#{SERVER_PORT}#{@src}", self)
+		puts "Started DRb client at: #{@drb.uri}"
+		
+		# display the GUI
+		@glade.get_widget("window").show
+		@entry.grab_focus
+	end
+	
+	
+	# user closed the window,
+	# so terminate the program
+	def on_quit
+		Gtk.main_quit
+	end
+	
+	
+	# user clicked "send", or pressed
+	# enter while in the entry field
+	def on_button_send_clicked
+		msg = @entry.text
+		
+		# do nothing if the message is blank
+		return nil if msg.empty?
+		log ">> #{msg}", "incoming"
+
+		begin
+			# attempt to send the message
+			# to rubysms via drb, as if it
+			# were a real incoming sms
+			@injector.incoming(@src, msg)
+			
+			@hist_pos = 0
+			@history.push(msg)
+			@entry.text = ""
+		
+		# couldn't connect!
+		rescue DRb::DRbConnError
+			log("Connection to RubySMS failed!", "error")
+			#log("Tried URI: #{@injector.__drburi}", "error")
+		rescue => err
+			log(err.message, "error")
+			log("  " + err.backtrace.join("\n  "), "error")
+		end
+	end
+	
+	def on_entry_message_key_press(widget, event)
+		if event.keyval == 65362 # up arrow
+			if @hist_pos > -@history.length
+				@hist_pos -= 1
+				@entry.text = @history[@hist_pos]
+				@entry.grab_focus
+			end
+			
+			# prevent default event,
+			# which bumps the focus
+			# upwards to the log
+			return true
+		end
+		
+		if event.keyval == 65364 # down arrow
+			if @hist_pos < -1
+				@hist_pos += 1
+				@entry.text = @history[@hist_pos]
+				@entry.grab_focus
+			end
+			
+			# prevent default
+			return true
+		end
+		
+		# any other key resets
+		# the position in history
+		@hist_pos = 0
+		return false
+	end
+	
+	
+	def log(msg, tag)
+		# prepend a newline, unless this
+		# is the first entry (to avoid a
+		# one-line gap at the top)
+		msg = "\n" + msg\
+			if @lb.char_count > 0
+		
+		# add a single entry to the message log
+		# (using the colors defined in #initialize)
+		@lb.insert(@lb.end_iter, msg, tag)
+		
+		# scroll to the end of the *previous*
+		# message, to bring the top of this
+		# message into view, in case it is long
+		@log.scroll_to_mark(@lb.get_mark("end"), 0, true, 1, 0)
+		
+		# update the position of the end marker,
+		# which we will scroll to (above), when
+		# the next message is logged
+		@lb.move_mark(@lb.get_mark("end"), @lb.end_iter)
+		@lb.end_iter.line_offset = 0
+	end
+	
+	
+	def incoming(msg)
+		# we received a message! do nothing
+		# except add it to the message log
+		msg.gsub!(/\n/, "\n   ")
+		log "<< #{msg}", "outgoing"
+	end
+end
+
+
+# initialize, and block
+# until GTK terminates
+gui = SmsGui.new
+Gtk.main

data/lib/drb-client.glade

@@ -0,0 +1,90 @@
+<?xml version="1.0"?>
+<glade-interface>
+  <!--<requires-version lib="gtk+" version="2.12"/>-->
+  <widget class="GtkWindow" id="window">
+    <property name="border_width">6</property>
+    <property name="title" translatable="yes">RubySMS Virtual Device</property>
+    <property name="default_width">500</property>
+    <property name="default_height">300</property>
+    <property name="icon_name">mail-send-receive</property>
+    <signal name="delete_event" handler="on_quit"/>
+    <child>
+      <widget class="GtkVBox" id="vbox1">
+        <property name="visible">True</property>
+        <property name="spacing">6</property>
+        <child>
+          <widget class="GtkScrolledWindow" id="scrolledwindow1">
+            <property name="visible">True</property>
+            <property name="can_focus">True</property>
+            <property name="hscrollbar_policy">GTK_POLICY_AUTOMATIC</property>
+            <property name="shadow_type">GTK_SHADOW_IN</property>
+            <child>
+              <widget class="GtkTextView" id="textview_log">
+                <property name="visible">True</property>
+                <property name="can_focus">True</property>
+                <property name="events"></property>
+                <property name="editable">False</property>
+              </widget>
+            </child>
+          </widget>
+        </child>
+        <child>
+          <widget class="GtkTable" id="table2">
+            <property name="visible">True</property>
+            <property name="n_columns">3</property>
+            <property name="column_spacing">6</property>
+            <child>
+              <widget class="GtkEntry" id="entry_message">
+                <property name="visible">True</property>
+                <property name="can_focus">True</property>
+                <property name="has_tooltip">True</property>
+                <property name="tooltip" translatable="yes">Message text</property>
+                <property name="activates_default">True</property>
+                <signal name="key_press_event" handler="on_entry_message_key_press"/>
+                <accelerator key="T" signal="grab-focus" modifiers="GDK_MOD1_MASK"/>
+              </widget>
+              <packing>
+                <property name="left_attach">1</property>
+                <property name="right_attach">2</property>
+                <property name="y_options">GTK_FILL</property>
+              </packing>
+            </child>
+            <child>
+              <widget class="GtkButton" id="button_send">
+                <property name="visible">True</property>
+                <property name="can_focus">True</property>
+                <property name="can_default">True</property>
+                <property name="has_default">True</property>
+                <property name="receives_default">True</property>
+                <property name="label" translatable="yes">Send SMS</property>
+                <property name="response_id">0</property>
+                <signal name="clicked" handler="on_button_send_clicked"/>
+              </widget>
+              <packing>
+                <property name="left_attach">2</property>
+                <property name="right_attach">3</property>
+                <property name="x_options">GTK_FILL</property>
+              </packing>
+            </child>
+            <child>
+              <widget class="GtkEntry" id="entry_source">
+                <property name="width_request">60</property>
+                <property name="visible">True</property>
+                <property name="can_focus">True</property>
+                <property name="tooltip" translatable="yes">DRb TCP/IP Port</property>
+                <property name="editable">False</property>
+              </widget>
+              <packing>
+                <property name="x_options">GTK_FILL</property>
+              </packing>
+            </child>
+          </widget>
+          <packing>
+            <property name="expand">False</property>
+            <property name="position">1</property>
+          </packing>
+        </child>
+      </widget>
+    </child>
+  </widget>
+</glade-interface>

data/lib/rubysms.rb

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+#:title:RubySMS
+#--
+# vim: noet
+#++
+
+
+# during development, it's important to EXPLODE
+# as early as possible when something goes wrong
+Thread.abort_on_exception = true
+Thread.current["name"] = "main"
+
+
+# everything (should) live
+# in this tidy namespace
+module SMS
+	
+	# store this directory name; everything
+	# inside here is considered to be part
+	# of the rubysms framework, so can be
+	# ignored in application backtraces
+	Root = File.dirname(__FILE__)
+end
+
+
+# load all supporting files
+dir = SMS::Root + "/rubysms"
+require "#{dir}/logger.rb"
+require "#{dir}/router.rb"
+require "#{dir}/thing.rb"
+require "#{dir}/application.rb"
+require "#{dir}/backend.rb"
+require "#{dir}/errors.rb"
+require "#{dir}/person.rb"
+
+
+# message classes
+require "#{dir}/message/incoming.rb"
+require "#{dir}/message/outgoing.rb"

data/lib/rubysms/application.rb

@@ -0,0 +1,207 @@
+#!/usr/bin/env ruby
+# vim: noet
+
+module SMS
+	class App < Thing
+		
+		# Creates and starts a router to serve only
+		# this application. Handy during development.
+		#
+		# This method accepts an arbitrary number of
+		# backends, each of which can be provided in
+		# numerous ways. This is kind of hard to wrap
+		# one's head around, but makes us super flexible.
+		# TODO: this magic will all be moved to the
+		#       router, one day, so multiple apps
+		#       can take advantage of it.
+		#
+		#   # start the default backends
+		#   # (one http, and one drb)
+		#   App.serve!
+		# 
+		#   # just the http backend
+		#   App.serve!(:HTTP)
+		#   
+		#   # the http backend... with configuration option(s)!
+		#   # (in this case, a port). it's got to be an array,
+		#   # so we know that we're referring to one single
+		#   # backend here, not two "HTTP" and "8080" backends
+		#   App.serve!([:HTTP, 8080])
+		#   
+		#   # two GSM backends on separate ports
+		#   App.serve!([:GSM, "/dev/ttyS0"], [:GSM, "/dev/ttyS1"])
+		#
+		# You may notice that these arguments resemble the
+		# config options from the Malawi RapidSMS project...
+		# this is not a co-incidence.
+		def self.serve!(*backends)
+			
+			# if no backends were explicitly requested,
+			# default to the HTTP + DRB offline backends
+			backends = [:HTTP, :DRB] if\
+				backends.empty?
+			
+			# create a router, and attach each new backend
+			# in turn. because ruby's *splat operator is so
+			# clever, each _backend_ can be provided in many
+			# ways - see this method's docstring.
+			router = SMS::Router.new
+			backends.each do |backend|
+				router.add_backend(*backend)
+			end
+			
+			router.add_app(self.new)
+			router.serve_forever
+		end
+		
+		def incoming(msg)
+			if services = self.class.instance_variable_get(:@services)
+				
+				# duplicate the message text before hacking it
+				# into pieces, so we don't alter the original
+				text = msg.text.dup
+				
+				# lock threads while handling this message, so we don't have
+				# to worry about being interrupted by other incoming messages
+				# (in theory, this shouldn't be a problem, but it turns out
+				# to be a frequent source of bugs)
+				Thread.exclusive do
+					services.each do |service|
+						method, pattern, priority = *service
+						
+						# if the pattern is a string, then assume that
+						# it's a case-insensitive simple trigger - it's
+						# a common enough use-case to warrant an exception
+						if pattern.is_a?(String)
+							pattern = /\A#{pattern}\Z/i
+						end
+						
+						# if this pattern looks like a regex,
+						# attempt to match the incoming message
+						if pattern.respond_to?(:match)
+							if m = pattern.match(text)
+								
+								# we have a match! attempt to
+								# dispatch it to the receiver
+								dispatch_to(method, msg, m.captures)
+							
+								# the method accepted the text, but it may not be interested
+								# in the whole message. so crop off just the part that matched
+								text.sub!(pattern, "")
+							
+								# stop processing if we have
+								# dealt with all of the text
+								return true unless text =~ /\S/
+							
+								# there is text remaining, so
+								# (re-)start iterating services
+								# (jumps back to services.each)
+								retry
+							end
+				
+						# the special :anything pattern can be used
+						# as a default service. once this is hit, we
+						# are done processing the entire message
+						elsif pattern == :anything
+							dispatch_to(method, msg, [text])
+							return true
+						
+						# we don't understand what this pattern
+						# is, or how it ended up in @services.
+						# no big deal, but log it anyway, since
+						# it indicates that *something* is awry
+						else
+							log "Invalid pattern: #{pattern.inspect}", :warn
+						end
+					end#each
+					
+					
+				end#exclusive
+			end#if
+		end
+		
+		def message(msg)
+			if msg.is_a? Symbol
+				begin
+					self.class.const_get(:Messages)[msg]
+			
+				# something went wrong, but i don't
+				# particularly care what, right now.
+				# log it, and carry on regardless
+				rescue StandardError
+					log "Invalid message #{msg.inspect} for #{self.class}", :warn
+					"<#{msg}>"
+				end
+			else
+				msg
+			end
+		end
+		
+		def assemble(*parts)
+			
+			# the last element can be an array,
+			# which contains arguments to sprintf
+			args = parts[-1].is_a?(Array)? parts.pop : []
+			
+			# resolve each remaining part
+			# via self#messge, which can
+			# (should?) be overloaded
+			parts.collect do |msg|
+				message(msg)
+			end.join("") % args
+		end
+		
+		private
+		
+		def dispatch_to(meth_str, msg, captures)
+			log_dispatch(meth_str, captures)
+			
+			begin
+				err_line = __LINE__ + 1
+				send(meth_str, msg, *captures)
+				
+			rescue ArgumentError => err
+				
+				# if the line above (where we dispatch to the receiving
+				# method) caused the error, we'll log a more useful message
+				if (err.backtrace[0] =~ /^#{__FILE__}:#{err_line}/)
+					wanted = (method(meth_str).arity - 1)
+					problem = (captures.length > wanted) ? "Too many" : "Not enough"
+					log "#{problem} captures (wanted #{wanted}, got #{captures.length})", :warn
+					
+				else
+					raise
+				end
+			end
+		end
+		
+		# Adds a log message detailing which method is being
+		# invoked, with which arguments (if any)
+		def log_dispatch(method, args=[])
+			meth_str = self.class.to_s + "#" + method.to_s
+			meth_str += " #{args.inspect}" unless args.empty?
+			log "Dispatching to: #{meth_str}"
+		end
+		
+		class << self
+			def serve(regex)
+				@serve = regex
+			end
+		
+			def method_added(meth)
+				if @serve
+					@services = []\
+						unless @services
+					
+					# add this method, along with the last stored
+					# regex, to the map of services for this app.
+					# the default 'incoming' method will iterate
+					# the regexen, and redirect the message to
+					# the method linked here
+					@services.push([meth, @serve])
+					@serve = nil
+				end
+			end
+		end
+	end # App
+end # SMS