groem 0.0.4

data/.autotest

@@ -0,0 +1,24 @@
+
+require 'autotest/restart'
+
+
+Autotest.add_hook :initialize do |at|
+  at.testlib = 'minitest/spec'
+  
+# Note only unit tests are autotest'ed here
+  at.add_mapping(/^spec\/unit\/.*\.rb$/) do |filename, _|
+    filename
+  end
+  
+# To include functional and integration tests, uncomment these lines
+  at.add_mapping(/^spec\/functional\/.*\.rb$/) do |filename, _|
+    filename
+  end
+  at.add_mapping(/^spec\/integration\/.*\.rb$/) do |filename, _|
+    filename
+  end
+
+end
+
+
+

data/.gitignore

@@ -0,0 +1,3 @@
+vendor/*
+.bundle/*
+Gemfile.lock

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://gems.rubyforge.org"
+
+gemspec

data/HISTORY.markdown

@@ -0,0 +1,9 @@
+# Release history
+
+## 0.0.4
+- Take out bundler dep except for spec_helper, set up gemspec
+- Default Notification-Enabled = 'True' for registered notifications
+- Update README, add LICENSE
+
+## 0.0.3
+- Initial release

data/README.markdown

@@ -0,0 +1,185 @@
+## Groem
+### An Eventmachine-based Growl Notification Transport Protocol (GNTP) client 
+
+For documentation of the GNTP protocol, see:
+[http://www.growlforwindows.com/gfw/help/gntp.aspx](http://www.growlforwindows.com/gfw/help/gntp.aspx)
+
+and the [Growl for Windows mailing list](http://groups.google.com/group/growl-for-windows/topics?start=).
+
+Note this is very much beta.  The core functionality is fairly well tested, but the following features are not yet implemented:
+
+- Binary resources (`x-growl-resource://`) in requests, including for icons
+- Encryption
+- Subscribe requests
+
+See other limitations below.
+
+## Platforms supported
+
+Groem does not rely on any OS-specific libraries per se. It's simply an implementation of a TCP protocol.  It doesn't define any UI components, part of Growl's design is that's left to the user to decide.  But of course: you need a Growl server running that speaks GNTP... and so far as I know, to this point it's only been implemented by Growl for Windows. 
+
+## Motivation
+
+I wanted to be able to send desktop notifications on my Windows box from ruby running in cygwin. Call me crazy but I seem to enjoy hacking at Windows from cygwin...!  (But no fear, if you are running ruby on Windows it should work exactly the same.)
+
+Also, I wanted the experience of implementing a protocol in Eventmachine. 
+
+Groem is a spin-off of sorts from my project for the free and wonderful [Ruby Mendicant University (RMU)](http://blog.majesticseacreature.com/).
+
+
+## Examples of usage
+
+### Registration
+
+Growl needs a 'register' request to define application options and what notifications to expect from your app.
+
+Besides what Growl needs for registration, you can also define a **default callback** for a given notification.  This simplifies cases where *you don't care about anything except the user action* -- i.e. whether the user closed the box, clicked it, or ignored it (timed out).  Every time you send that type of notification, the same callback context, context-type and/or target URL will be used. 
+
+
+      app = Groem::App.new('Downloader', :host => 'localhost')
+      
+      app.register do
+        icon 'http://www.example.com/icon.png'
+        header 'X-Custom-Header', 'default value'
+
+        # notification with callback expected
+        notification :finished, 'Your download has finished!' do |n|
+          n.sticky = 'True'
+          n.text = 'Run it!'
+          n.icon 'path/to/local/icon.png'  #=> generate x-growl-resource (future)
+          n.callback 'process', :type => 'run'
+        end
+        
+        # notification with no callback
+        notification :started, 'Your download is starting!', 
+                     :display_name => 'Downloader working'
+        
+      end
+
+    
+### Notification
+    
+Notify returns the initial response from the server (whether request was OK or error).  Callbacks (the second response from the server, based on what the user did) are handled through a routing scheme, see below.
+
+    
+      #  trigger notify and callbacks
+      app.notify(:started, 'XYZ has started!')
+      
+      # trigger notify with 'ad-hoc' callback
+      # == with different settings than defined in app.register
+      app.notify(:started, 'ABC has started!', 
+                 :callback => {:type => 'ad-hoc', 
+                               :target => 'www.my-callback-url.com'}
+                )
+                
+      #  trigger notify and handle responses
+      app.notify(:finished, 'ABC has finished!') do |response|
+        response.ok? { # handle OK response }
+        response.error?  { # handle any ERROR response }
+        response.error?(400) { # handle ERROR 400 (not authorized) response }
+      end
+
+      # you could also do this outside of the block
+      response = app.notify(:finished, 'ABC has finished!') 
+      response.ok? { # handle OK response }
+      response.error?  { # handle any ERROR response }
+      response.error?(400) { # handle ERROR 400 (not authorized) response }
+    
+    
+### Callbacks
+
+Callback procs allow you to capture responses from the user based on what they did (close, click, timeout), plus the two standard Growl data fields that the UI can return data in -- the context and the context-type.  
+
+A given response will be routed to *all matching callback procs*, starting with the most specific.
+
+(Of course, if a callback target (URL) is specified in the request, you won't get back a second response -- Growl will open up your browser instead.)
+
+
+      app.when_close 'process' do |response|
+        # do something with close responses to process notifications
+      end
+        
+      app.when_click :context => 'process', :type => 'run' do |response|
+        # do something with click responses that have 'process' contexts of type 'run'
+      end
+        
+      app.when_click :type => 'integer' do |response|
+        # do something with click responses that have type 'integer' regardless of context
+      end
+        
+      app.when_timedout do |response|  
+        # do something with any timeout response regardless of context or type
+      end
+
+    
+## Lower-level interface
+
+If you prefer a more direct interface you can use Groem::Client, the EM connection which Groem::App is built on.  It expects the request to be passed as a hash, and will throw OK, error, and callback responses back as a three-element array roughly modeled on Rack's interface (_status_, _headers_, and _body_ -- body in this case being a hash of GNTP callback headers).  
+
+For instance,
+
+
+    regist = {'headers' => {
+                  'Application-Name' => 'SurfWriter',
+                  'Application-Icon' => 'http://www.site.org/image.jpg'
+                  },
+               'notifications' => {
+                  'Download Complete' => {
+                    'Notification-Display-Name' => 'Download completed',
+                    'Notification-Enabled' => 'True',
+                    'X-Language' => 'English',
+                    'X-Timezone' => 'PST'
+                    }
+                  }
+              }
+              
+    connect = Groem::Client.register(regist)
+    connect.when_ok { |resp|  # ... }
+    connect.errback { |resp|  # ... }
+    
+    notif = {'Application-Name' => 'SurfWriter',
+             'Notification-Name' => 'Download Complete',
+             'Notification-ID' => some_unique_id,
+             'Notification-Callback-Context' => 'myfile',
+             'Notification-Callback-Context-Type' => 'confirm'
+            }
+    
+    connect2 = Groem::Client.notify(notif)
+    connect2.when_ok { |resp|  # ... }
+    connect2.errback { |resp|  # ... }
+    connect2.when_callback { |resp| #... }
+    
+    
+For more details see `lib/groem/marshal`, and `spec/functional/client_spec`.
+
+
+## Limitations
+
+- No casting or uncasting of GNTP headers to or from ruby types is done -- everything is a string (or a symbol which gets converted to a string).  So the interface is a little clunky.
+
+- If a Growl server is not running, the client's EM loop will not exit and has to be interrupted.  In the future it would be good to timeout, perhaps after several reconnect attempts.
+
+- It has only been tested on Ruby 1.8.7 running on cygwin on WinXP.  I am planning to test on 1.9.2.
+
+
+## License
+
+Copyright (c) 2010 Eric Gjertsen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/TODO.markdown

@@ -0,0 +1,7 @@
+## Oct 12
+
+- Test/debug on ruby 1.9.2
+- Timeout or reconnect client if no server running
+- Allow casting/uncasting ruby types from/to GNTP
+- Implement binary resources
+- Implement encryption

data/groem.gemspec

@@ -0,0 +1,24 @@
+# encoding: utf-8
+
+$:.unshift File.expand_path('../lib', __FILE__)
+require 'groem/version'
+
+Gem::Specification.new do |s|
+  s.name         = "groem"
+  s.version      = Groem::VERSION
+  s.authors      = ["Eric Gjertsen"]
+  s.email        = "ericgj72@gmail.com"
+  s.homepage     = "http://github.com/ericgj/groem"
+  s.summary      = "Eventmachine-based Ruby Growl (GNTP) client"
+  s.description  = ""
+
+  s.files        = `git ls-files -c`.split("\n")
+  s.platform     = Gem::Platform::RUBY
+  s.require_path = 'lib'
+  s.rubyforge_project = ''
+  s.required_rubygems_version = '>= 1.3.6'
+  
+  s.add_runtime_dependency 'eventmachine'
+  s.add_runtime_dependency 'uuidtools'
+  s.add_development_dependency 'minitest'
+end

data/lib/groem.rb

@@ -0,0 +1,10 @@
+$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__))
+
+require 'rubygems'
+require 'lib/groem/constants'
+require 'lib/groem/marshal'
+require 'lib/groem/client'
+require 'lib/groem/response'
+require 'lib/groem/route'
+require 'lib/groem/notification'
+require 'lib/groem/app'

data/lib/groem/app.rb

@@ -0,0 +1,197 @@
+require 'eventmachine'
+
+module Groem
+
+  class App < Struct.new(:host, :port, 
+                         :environment, :headers, :notifications)
+    include Groem::Marshal::Request
+    
+    DEFAULT_HOST = 'localhost'
+    DEFAULT_PORT = 23053
+    DEFAULT_ENV = {'protocol' => 'GNTP', 'version' => '1.0',
+                   'request_method' => 'REGISTER', 'encryption_id' => 'NONE'
+                  }
+                  
+    def initialize(name, opts = {})
+      self.environment, self.headers, self.notifications = {}, {}, {}
+      self.environment = DEFAULT_ENV.merge(opts.delete(:environment) || {})
+      self.host = opts.delete(:host) || DEFAULT_HOST
+      self.port = opts.delete(:port) || DEFAULT_PORT
+      self.headers[GNTP_APPLICATION_NAME_KEY] = name
+      opts.each_pair {|opt, val| self.headers[growlify_key(opt)] = val }
+    end
+    
+    # used by Marshal::Request#dump
+    def [](key)
+      to_request[key]
+    end
+    
+    def name; self.headers[GNTP_APPLICATION_NAME_KEY]; end
+    
+    def register(&blk)
+      if blk.arity == 1
+        blk.call(self)
+      else
+        instance_eval(&blk)
+      end
+      send_register
+    end
+    
+    def notify(name, *args, &blk)
+      return unless n = self.notifications[name]
+      opts = ((Hash === args.last) ? args.pop : {})
+      title = args.shift
+      n = n.dup    # copies attributes so not overwritten
+      n.title = title ? title : self.name
+      if cb = opts.delete(:callback)
+        n.callback(cb) 
+      end
+      opts.each_pair {|k, v| n.__send__ :"#{k}=", v}
+      send_notify(n, &blk)
+    end
+    
+    def notification(name, *args)
+      n = Groem::Notification.new(name, *args)
+      yield(n) if block_given?
+      n.application_name = self.name
+      self.notifications[name] = n
+    end
+   
+    def callbacks &blk
+      if blk.arity == 1
+        blk.call(self)
+      else
+        instance_eval(&blk)
+      end      
+    end
+        
+    def header(key, value)
+      self.headers[growlify_key(key)] = value
+    end
+    
+    def icon(uri_or_file)
+      # TODO if not uri
+      header GNTP_APPLICATION_ICON_KEY, uri_or_file
+    end
+    
+    def binary(key, value_or_io)
+      #TODO
+    end
+    
+    #---- callback definition methods
+    
+    def when_register &blk
+      @register_callback = blk
+    end
+    
+    def when_register_failed &blk 
+      @register_errback = blk
+    end
+    
+    def when_click path=nil, &blk
+      when_callback GNTP_CLICK_CALLBACK_RESULT, path, &blk
+    end
+    
+    def when_close path=nil, &blk
+      when_callback GNTP_CLOSE_CALLBACK_RESULT, path, &blk
+    end
+    
+    def when_timedout path=nil, &blk
+      when_callback GNTP_TIMEDOUT_CALLBACK_RESULT, path, &blk
+    end
+    
+    def when_callback action, path=nil, &blk
+      action = growlify_action(action)
+      path = \
+        case path
+        when String
+          [path, nil]
+        when Hash
+          [path[:context], path[:type]]
+        end
+      #puts "App defined callback: #{action} #{path.inspect}"      
+      notify_callbacks[Groem::Route.new(action, path)] = blk
+    end
+    
+        
+    def to_request
+      {'environment' => self.environment, 
+       'headers' => self.headers, 
+       'notifications' => notifications_to_register
+      }
+    end
+    
+   protected
+        
+    def register_callback; @register_callback; end
+    def register_errback; @register_errback || register_callback; end
+
+    def notify_callbacks; @notify_callbacks ||= {}; end
+
+    def send_register
+      Groem::Client.response_class = Groem::Response
+      stop_after = !(EM.reactor_running?)
+      ret = nil
+      EM.run {
+        connect = Groem::Client.register(self, host, port)
+        connect.callback do |resp| 
+          EM.stop if stop_after
+        end
+        connect.errback  do |resp| 
+          register_errback.call(resp) if register_errback
+          ret = resp
+          EM.stop if stop_after
+        end
+        connect.when_ok do |resp| 
+          register_callback.call(resp) if register_callback
+          ret = resp
+        end
+      }
+      ret
+    end
+    
+    def send_notify(notif, &blk)
+      Groem::Client.response_class = Groem::Response
+      stop_after = !(EM.reactor_running?)
+      ret = nil
+      EM.run {
+        connect = Groem::Client.notify(notif, host, port)
+        connect.callback do |resp| 
+          EM.stop if stop_after
+        end
+        connect.errback do |resp| 
+          yield(resp) if block_given?
+          ret = resp
+          EM.stop if stop_after
+        end
+        connect.when_ok do |resp|
+          yield(resp) if block_given?
+          ret = resp
+        end
+        connect.when_callback do |resp|
+          route_response(resp)
+       end
+      }
+      ret
+    end
+    
+    def notifications_to_register
+      self.notifications.inject({}) do |memo, pair|
+        memo[pair[0]] = pair[1].to_register
+        memo
+      end
+    end
+        
+    def route_response(resp)
+      #puts "Response callback route: #{resp.callback_route.inspect}"
+      notify_callbacks.sort.each do |route, blk|
+        #puts "Checking against pattern: #{route.pattern.inspect} => #{route.matches?(resp.callback_route).inspect}"
+        if route.matches?(resp.callback_route)
+          blk.call(resp)
+        end
+      end
+    end
+    
+  end
+  
+end