snarl-snp 0.1.1

data/lib/snarl/snp/action.rb

@@ -0,0 +1,138 @@
+class Snarl
+  class SNP
+    module Action
+
+      NOTIFICATION_PARAM_ORDER = [:title, :text, :icon, :timeout, :class, :action, :app]
+
+      # Sends a SNP command "register" to Snarl. For registering +app+ to Snarl setting window.
+      #   snp.register('Ruby-Snarl')
+      # +app+        :: an application name. Snarl uses it as an application ID.
+      # Snarl::SNP keeps +app+ for add_class method and notification method.
+      # +app+ default is SNP::DEFAULT_APP, 'Ruby-Snarl'.
+      # Returns SNP::Response object.
+      #
+      # Snarl sends back a casual error when +app+ is already registered.
+      # It is treated as SNP::SNPError::Casual::SNP_ERROR_ALREADY_REGISTERED.
+      def register(app=nil)
+        @app = app
+        cmds = {:action => 'register', :app => app}
+        request(Request.new(cmds))
+      end
+      alias :app= :register
+
+      # Sends a SNP command "add_class" to Snarl. For adding +classid+ class and its +classtitle+ nickname.
+      #   snp.add_class('green')
+      #   snp.add_class('red', 'failure popup')
+      # +classid+    :: classname ID on the registered application
+      # +classtitle+ :: display alias for +classname+, optional
+      # Returns SNP::Response object.
+      # Before adding a class, you should register the application.
+      #
+      # Snarl sends back a casual error when +classid+ is already added.
+      # It is treated as SNP::SNPError::Casual::SNP_ERROR_CLASS_ALREADY_EXISTS.
+      def add_class(classid, classtitle=nil)
+        # TODO: add_class(app=nil, classid, classtitle=nil)
+        # type=SNP#?version=1.0#?action=add_class#?class=t returns (107) Bad Packet
+        raise "#{self}#register(appname) required before add_class" unless @app
+        cmds = {:action => 'add_class', :app => @app, :class => classid.to_s, :title => classtitle}
+        request(Request.new(cmds))
+      end
+
+      # Sends SNP command "notification" to Snarl. For making a popup message itself.
+      #   snp.notification('title', 'text', 'icon.jpg', 10, 'classA') # 10 is timeout Integer
+      #   snp.notification(:title => 't', :text => 't', :icon => 'i.jpg', :timeout => 10, :class => 'claA')
+      # +title+   :: title of popup. String.
+      # +text+    :: text body of popup. String. linebreaks should be only "\n". "\r" confuses Snarl.
+      # +icon+    :: icon image path of popup. String/#to_s. path on Snarl machine or http URL. bmp/jpg/png/gif.
+      # +timeout+ :: display seconds of popup. Integer. if nil, DEFAULT_TIMEOUT 10. if 0, popup never closes automatically.
+      # +class+   :: classid of popup. String. It should have been added by "add_class" method when you use.
+      # notification(title, text, icon=nil, timeout=nil, classid=nil) or notification(keyword-hash).
+      #   snp.notification('title', 'text', 10)
+      #   snp.notification('title', 'text')
+      #   snp.notification('text') # title == DEFAULT_APP == 'Ruby-Snarl'
+      def notification(*keyhash)
+        # TODO: priority
+        cmds = normalize_notification_params(keyhash)
+        request(Request.new(cmds))
+      end
+      alias :notify :notification
+
+      # Sends SNP command "unregister" to Snarl. For removing +app+ from Snarl setting window.
+      #   snp.unregister('Ruby-Snarl')
+      # After this, Snarl users can not edit the settings for +app+ 's popup.
+      # If you allow users to edit settings, do not send unregister.
+      # Without sending unregister, the applications are always reseted when Snarl restarts.
+      #
+      # Snarl sends back a casual error when +app+ is not registered.
+      # It is treated as SNP::SNPError::Casual::SNP_ERROR_NOT_REGISTERED.
+      def unregister(app=nil)
+        app = app || @app
+        raise "#{self}#unregister requires appname." unless app
+        cmds = {:action => 'unregister', :app => app}
+        request(Request.new(cmds))
+      end
+
+      # Sends SNP command "hello".
+      #   irb> Snarl::SNP.new('127.0.0.1').hello
+      #   SNP/1.1/0/OK/Snarl R2.21
+      def hello
+        request(Request.new({:action => 'hello'}))
+      end
+
+      # Sends SNP command "version".
+      #   irb> Snarl::SNP.new('127.0.0.1').version
+      #   SNP/1.1/0/OK/40.15
+      def version
+        request(Request.new({:action => 'version'}))
+      end
+
+      # UTILS -----------------------------
+
+      private
+
+      def paramarray_to_hash(param_array)
+        title, text, icon, timeout, classid, action, app = param_array
+        pattern = {
+          :only_text => (param_array.size == 1),
+          :text_timeout => (param_array.size == 2) && title && text.kind_of?(Integer),
+          :title_text_timeout => (param_array.size == 3) && title && text && icon.kind_of?(Integer)
+        }
+        case
+        when pattern[:only_text] then # notify("msg")
+          {:title =>  nil, :text => title}
+        when pattern[:text_timeout] then # notify("msg", 10)
+          {:title =>  nil, :text => title, :timeout => text}
+        when pattern[:title_text_timeout] then # notify("tit", "msg", 10)
+          {:title => title, :text => text, :timeout => icon}
+        else
+          Hash[*NOTIFICATION_PARAM_ORDER.zip(param_array).flatten].delete_if{|k, v| v.nil?}
+        end
+      end
+
+      # we support for:
+      # notify(         'text')
+      # notify('title', 'text')
+      # notify(         'text', 10)
+      # notify('title', 'text', 10)
+      def normalize_notification_params(param)
+        res = Hash.new
+        if param[0].kind_of?(Hash) then
+          keyhash = param[0]
+        else
+          keyhash = paramarray_to_hash(param)
+        end
+        NOTIFICATION_PARAM_ORDER.each do |command|
+          keyhash_value = (keyhash[command.to_s] || keyhash[command])
+          res[command] =  keyhash_value if keyhash_value
+        end
+        res[:action]  = 'notification'
+        res[:app]     = @app if (res[:app].nil? && @app) # default notification
+        res[:app]     = nil if res[:app] == :anonymous # from snp.show_message
+        res[:title]   = (@title || DEFAULT_TITLE) unless res[:title]
+        res[:timeout] = (@timeout || DEFAULT_TIMEOUT) unless res[:timeout]
+        res[:icon]    = icon(res[:icon]) if res[:icon]
+        return res
+      end
+    end
+  end
+end

data/lib/snarl/snp/config.rb

@@ -0,0 +1,32 @@
+
+# when config file exists, require this config
+class Snarl
+  class SNP
+    class Config
+
+      DEFAULT_HOST = '127.0.0.1'
+      DEFAULT_PORT = 9887
+      @host = nil
+      @port = nil
+
+      def self.host
+        @host || ENV['SNARL_HOST'] || DEFAULT_HOST
+      end
+      def self.host=(v)
+        @host = if v then v.to_s else nil end
+      end
+
+      def self.port
+        @port || ENV['SNARL_PORT'] || DEFAULT_PORT
+      end
+      def self.port=(v)
+        @port = if v then v.to_i else nil end
+      end
+
+      def self.reset
+        self.host = nil
+        self.port = nil
+      end
+    end
+  end
+end

data/lib/snarl/snp/error.rb

@@ -0,0 +1,76 @@
+class Snarl
+  class SNP
+    module Error
+      class SNPError < StandardError
+        def initialize(response, request=nil) # request is String or Request
+          @response, @request = response, request
+        end
+        attr_accessor :request, :response
+        def code ; @response.code ; end
+        def message ; "(#{code}) #{@response.message}" ; end
+        def ok? ; @response.ok? ; end
+      end
+
+      class Casual < SNPError ; end
+
+      class SNP_OK < Casual ; end
+      # (0) OK
+
+      class SNP_ERROR_NOT_REGISTERED < Casual ; end
+      # (202) The application hasn't been registered.
+
+      class SNP_ERROR_ALREADY_REGISTERED < Casual ; end
+      # (203) The application is already registered.
+
+      class SNP_ERROR_CLASS_ALREADY_EXISTS < Casual ; end
+      # (204) Class is already registered.
+
+      class Fatal < SNPError ; end
+
+      class SNP_ERROR_FAILED < Fatal ; end
+      # (101) An internal error occurred - usually this represents a fault within Snarl itself.
+
+      class SNP_ERROR_UNKNOWN_COMMAND < Fatal ; end
+      # (102) An unknown action was specified.
+
+      class SNP_ERROR_TIMED_OUT < Fatal ; end
+      # (103) The command sending (or subsequent reply) timed out.
+
+      class SNP_ERROR_BAD_PACKET < Fatal ; end
+      # (107) The command packet is wrongly formed.
+
+      class SNP_ERROR_NOT_RUNNING < Fatal ; end
+      # (201) Incoming network notification handling has been disabled by the user.
+
+      class RUBYSNARL_UNKNOWN_RESPONSE < Fatal ; end
+      # (???) Snarl returns unknown return code.
+
+      CODE_TO_OBJ = {
+        '0' => SNP_OK,
+        '101'  => SNP_ERROR_FAILED,
+        '102' => SNP_ERROR_UNKNOWN_COMMAND,
+        '103' => SNP_ERROR_TIMED_OUT,
+        '107' => SNP_ERROR_BAD_PACKET,
+        '201' => SNP_ERROR_NOT_RUNNING,
+        '202' => SNP_ERROR_NOT_REGISTERED,
+        '203' => SNP_ERROR_ALREADY_REGISTERED,
+        '204' => SNP_ERROR_CLASS_ALREADY_EXISTS
+      }
+
+      def self.klass(response, request=nil)
+        if klass = Error::CODE_TO_OBJ[response.to_s] then
+          klass
+        elsif response.kind_of?(Error::SNPError)
+          response
+        else
+          Error::RUBYSNARL_UNKNOWN_RESPONSE
+        end
+      end
+
+      def self.raise(response, request)
+        Error.klass.new(response, request)
+      end
+
+    end
+  end
+end

data/lib/snarl/snp/request.rb

@@ -0,0 +1,83 @@
+class Snarl
+  class SNP
+    class Request
+      PROTOCOL_NAME = "SNP"
+      PROTOCOL_VERSION ="1.0"
+
+      SNP_ACTIONS = {
+        'register'     => %w(type version action app),
+        'add_class'    => %w(type version action app class title),
+        'notification' => %w(type version action app class title text timeout icon priority),
+        'unregister'   => %w(type version action app),
+        'hello'        => %w(type version action),
+        'version'      => %w(type version action),
+      }
+
+      # You have to send non-ascii messages by "Windows" encoding.
+      ENCODING = 'cp932'
+
+      SNP_SEPARATOR = '#?'
+      SNP_TERMINAL_STRING = "\r\n"
+      SNP_HEADER = {'type' => PROTOCOL_NAME, 'version' => PROTOCOL_VERSION}
+
+      # make SNP request string from command hash and is Request object.
+      def initialize(cmd_hash={})
+        @commands = {}.update(cmd_hash)
+      end
+
+      attr_reader :commands
+
+      # Adds command key and value to Request
+      def []=(cmdkey, value) ; @commands[cmdkey] = value ; end # TODO: normalize
+      # Returns command value for command key
+      def [](cmdkey)        ; @commands[cmdkey]     ; end
+
+      # Returns Request query string with SNP_TERMINAL_STRING "\r\n"
+      def to_str ; query + SNP_TERMINAL_STRING ; end # FIXME: include "\r\n"?
+      alias :to_s :to_str
+      # Returns Request query string. has no SNP_TERMINAL_STRING "\r\n".
+      def inspect ; query ; end
+      def action ; @commands['action'] ; end
+
+      private
+
+      def order_command_pair
+        action = @commands['action']
+        @commands.to_a.sort_by{|pair| SNP_ACTIONS[action].index(pair[0])}
+      end
+
+      def query
+        normalize
+        order_command_pair.map{|pair| pair.join('=')}.join(SNP_SEPARATOR)
+      end
+
+      # normalize item pairs
+      # - symbol keys and upcase KEYS are normalized into downcased string keys.
+      # - query should not have any "\r". use "\n"
+      # - when value is nil, delete the item pair.
+      def normalize
+        norm_commands = Hash[*@commands.map{|k, v| [crlf2lf(k).downcase, crlf2lf(v)]}.flatten]
+        action = normalize_action(norm_commands['action'])
+        norm_commands['action'] = action
+        @commands = SNP_HEADER.dup
+        available_commands_in(action).each do |cmd|
+          @commands[cmd] = norm_commands[cmd] if norm_commands[cmd]
+        end
+      end
+
+      def normalize_action(action_type)
+        action_type.downcase.gsub(/-/){'_'}.sub(/\Aaddclass\Z/){'add_class'}
+      end
+
+      def available_commands_in(action)
+        SNP_ACTIONS[action] || {}
+      end
+
+      def crlf2lf(s)
+        s ? s.to_s.gsub(/\r\n/){"\n"}.gsub(/\r/){"\n"} : s
+      end
+
+    end
+  end
+end
+

data/lib/snarl/snp/response.rb

@@ -0,0 +1,36 @@
+class Snarl
+  class SNP
+    class Response
+      ResponseParseRegexp = /\ASNP\/[\d\.]+\/(\d+)\/(.+?)\Z/
+      def initialize(s)
+        if s.respond_to?(:get) then
+          @response = s.get
+        else
+          @response = s
+        end
+        parse_response
+      end
+
+      attr_reader :code, :message, :infomation, :response
+      attr_accessor :request
+      alias :status :code
+
+      def parse_response
+        if  ResponseParseRegexp =~ @response.chomp then
+          @code = $1
+          @message, @infomation= $2.split(/\//)
+        else
+          raise Snarl::SNP::Error::RUBYSNARL_UNKNOWN_RESPONSE.new(self, nil)
+        end
+        raise error.new(self, nil) unless ok?
+      end
+
+      def error ; Error.klass(self.code) ; end
+
+      def to_s    ; code ; end # puts response #=> "0"
+      def inspect ; @response.chomp ; end # p response #=> "SNP/1.1/0/OK/456"
+
+      def ok? ; code.to_i.zero? ; end
+    end
+  end
+end

data/lib/snarl/snp/snp.rb

@@ -0,0 +1,142 @@
+class Snarl # conpat for ruby-snarl
+
+  class SNP
+
+    include Action
+
+    # default "timeout command" value. popup disappers in 10 seconds.
+    DEFAULT_TIMEOUT = 10
+
+    # default title for "non-title" notification
+    DEFAULT_TITLE = 'Ruby-Snarl'
+
+    # Snarl::SNP.new('127.0.0.1', 9887)
+    def initialize(host=nil, port=nil, verbose=false)
+      @host = host
+      @port = port
+      @verbose = verbose
+      @logger = nil
+      @app = nil
+      @timeout = nil
+      @iconset = {}
+      @title = nil
+    end
+
+    # When you set it true, all unimportant SNP errors raise.
+    # Default is false, Snarl::SNP::Error::Casual are disabled.
+    attr_accessor :verbose
+
+    # a value of SNP command "app".
+    attr_reader :app
+
+    attr_accessor :title
+
+    # a value of SNP command "timeout".
+    attr_accessor :timeout
+
+    # set Logger object. It is used when sending request and getting response.
+    def logger=(logger)
+      @logger = (logger.kind_of?(Class) ? logger.new($stdout) : logger)
+    end
+
+    # send Snarl::SNP::Request/Hash/String and get Snarl::SNP::Response fron Snarl.
+    # When the response "fatal" response, raise errors.
+    # When method +verbose+ returns true, "casual" errors also raises.
+    def request(req)
+      req = Request.new(req) if req.kind_of?(Hash)
+      debug(req)
+      begin
+        action = req.kind_of?(Request) ? req.action : '(string)'
+        res = get_response(req)
+        info("#{action}: #{res.inspect}")
+      rescue Error::Casual => ex
+        info("#{action}: (ignored) #{ex.message}")
+        raise if verbose
+      rescue Error::Fatal => ex
+        info("#{action}: #{ex.message}")
+        raise
+      end
+      return res
+    end
+
+    # SHORTCUT METHODS ----------------
+
+    # add_classes('type1', 'type2', 'type3')
+    # add_classes(['type1', desc1], ['type2', desc2], ['type3', desc3])
+    def add_classes(*classes)
+      classes.each do |classpair|
+        classpair = [classpair, nil] if classpair.kind_of?(String)
+        add_class(*classpair)
+      end
+    end
+
+    # returns icon path if SNP knows. optional.
+    def icon(s)
+      if @iconset.has_key?(s) then @iconset[s] else s end
+    end
+
+    # set icons pair. quite optional.
+    #   snp.iconset(:red => 'red.jpg')
+    #   snp.notification('title', 'text', :red) #=> sends "icon=red.jpg"
+    #   snp.notification('title', 'text', 'blue') #=> sends "icon=blue"
+    def iconset(icons)
+      @iconset = icons
+    end
+    alias :icons :iconset
+
+    def ping
+      notification(DEFAULT_TITLE, 'Ruby Snarl-SNP Ping Message', 3, nil)
+    end
+
+    alias :message :notification
+
+    def snarl_hello
+      hello.infomation
+    end
+
+    def snarl_version
+      version.infomation
+    end
+
+    #   Snarl::SNP.open(host, port){|snp| snp.register ... }
+    # "ensure block" is empty. TCPSocket is closed per access.
+    def self.open(host=nil, port=nil, verbose=false, &block)
+      client = new(host, port, verbose)
+      yield(client) # socket always closed in TCPSocket#open{...}
+      client
+    end
+
+    # send message only. app is "anonymous".
+    #   Snarl::SNP.show_message(host, 9887, title, text, tomeout, icon)
+    #   Snarl::SNP.show_message(host, title, text, tomeout, icon)
+    def self.show_message(host, port, title=nil, text=nil, timeout=nil, icon=nil)
+      # TODO: (host, title, text, 10)
+      if port.kind_of?(String) && icon.nil? then
+        port, title, text, timeout, icon = nil, port, title, text, timeout
+      end
+      new(host, port).notification(:title => title, :text => text, :timeout => timeout, :icon => icon)
+    end
+
+    def self.ping(host=nil, port=nil)
+      new(host, port).ping
+    end
+    # ----------------- SHORTCUT METHODS
+
+    private
+
+    def get_response(req)
+      host = @host || Config.host
+      port = @port || Config.port
+      TCPSocket.open(host, port) do |s|
+        s.write(req)
+        res = Response.new(s.gets)
+        res.request = req
+        res
+      end
+    end
+
+    def info(m); @logger.info(m) if @logger; end
+    def debug(m); @logger.debug(m) if @logger; end
+
+  end
+end