snarl-snp 0.1.1 → 0.2.0

data/README.rdoc

@@ -1,13 +1,13 @@
 = snarl-snp
 
-Snarl Network Protocol(SNP) Client for Snarl. You can send messages to Snarl over LAN.
+Snarl Network Protocol(SNP) Client for Snarl. You can send messages to Snarl on LAN.
 
 Snarl is a popup-message application on Windows. Alike Growl.
 http://www.fullphat.net/
 SNP 1.0 documentation is here.
 http://www.fullphat.net/dev/snp/index.htm
 
-If you are able to read Japanese, please read README.rdoc.ja.
+If you are able to read Japanese, please read doc-ja/README.rdoc.ja.
 
 == Requirements
 
@@ -17,7 +17,7 @@ If you are able to read Japanese, please read README.rdoc.ja.
 
   gem install snarl-snp
 
-No other gems are required (only to test, WebMock is needed).
+No other gems are required.
 
 == Contact
 
@@ -33,6 +33,65 @@ Set the value in advance, then copy and paste codes on irb.
 
 When nil/undef, Snarl::SNP uses '127.0.0.1'. Default port is 9887.
 
+=== SNP with YAML
+
+0.2.0 feature. It maybe seems to be easy.
+
+    require 'rubygems'
+    require 'snarl/snp'
+    Snarl::SNP.load(<<YAML)
+    host       : #{@host}
+    app        : Ruby-Snarl
+    title      : popup title
+    text       : hello!
+    timeout    : 5
+    unregister : false
+    YAML
+
+    require 'rubygems'
+    require 'snarl/snp'
+    yaml = <<YAML
+    host  : #{@host}
+    app   : Ruby-Snarl
+    class :
+       - [class1, name1]
+       - [class2, name2]
+    YAML
+    Snarl::SNP.load(yaml) do |snp|
+      snp.notification(:title => 'title', :text => 'text', :class => 'class1')
+    end
+
+    require 'rubygems'
+    require 'snarl/snp'
+    Snarl::SNP.load(<<YAML)
+    host  : #{@host}
+    app   : Ruby-Snarl
+    class :
+       - [class1, name1]
+       - [class2, name2]
+    notification :
+       title : title
+       text  : text
+       class : class1
+    logfile : $stdout
+    YAML
+
+    require 'rubygems'
+    require 'snarl/snp'
+    Snarl::SNP.load(<<YAML)
+    host  : #{@host}
+    app   : Ruby-Snarl
+    notification :
+      -
+       title : 1st post!
+       text  : message1
+      -
+       title : 2nd post!
+       text  : message2
+    YAML
+
+For YAML details, see YAML.rdoc.
+
 === Simple Popup (anonymous application)
 
     require 'rubygems'
@@ -120,7 +179,30 @@ Don't use "\r\n" or "\r" in message body. Use "\n" instead.
     require 'kconv'
     Snarl::SNP.open(@host){|snp| snp.notification('タイトル'.tosjis, '日本語'.tosjis)}
 
-Windows encoding is required.
+Windows encoding is required. Windows 2000 is Shift_JIS (CP932), XP is UTF-8, maybe.
+
+== SNP on command line
+
+bin/snarl_snp is available.
+
+    snarl_snp -H host -a app -t title -m message
+
+    snarl_snp --yaml=./snp.yml
+
+and so on.
+
+[-H host, --host=host] the hostname/address which Snarl is running (default, 127.0.0.1). -h shows help. "H"ost. Sorry.
+[-p port, --port=port] the port number which Snarl uses (default, 9887)
+[-a app, --app=app] the application name you use on Snarl (default, nothing). It's read in SNP#register(app)
+[-c class, --class=class] the classname you use on Snarl (default, nothing). It's read in SNP#add_class and notification
+[-t title, --title=title] the title string of popup (default 'Ruby-Snarl').
+[-m msg, --text=msg] the popup message body.
+[-s sec, --timeout=sec] popups automatically close in sec (default 10 sec.). -t is not for timeout but title.
+[--icon=icon_path] popup message icon path (default, default style's icon). URL or filepath on Snarl machine. JPG/PNG/GIF
+[--sticky] makes popup "sticky" (default, closes in timeout sec). this is equal to "--timeout=0".
+[-u, --unregister] removes app from Snarl setting window (default, false). note: users cannot change app's setting.
+[--verbose] shows SNP logs to stdout (default, false)
+[-y yamlpath, --yaml=yamlpath] the YAML file path for "automatic SNP" (default, nothing)
 
 == FAQ
 

data/Rakefile

@@ -5,13 +5,12 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
     gem.name = "snarl-snp"
-    gem.summary = %Q{Snarl Network Protocol Client. You can notify to Snarl over LAN.}
-    gem.description = %Q{Snarl Network Protocol Client. Snarl is the notification program for Windows. You can send notification messages to Snarl with SNP over LAN.}
+    gem.summary = %Q{Snarl Network Protocol Client. You can notify to Snarl on LAN.}
+    gem.description = %Q{Snarl Network Protocol Client. Snarl is the notification program for Windows. You can send notification messages to Snarl with SNP on LAN.}
     gem.email = "ezookojo@gmail.com"
     gem.homepage = "http://github.com/kitamomonga/snarl-snp"
     gem.authors = ["kitamomonga"]
     gem.add_development_dependency "rspec", ">= 1.2.9"
-    gem.add_development_dependency "webmock"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new
@@ -43,5 +42,7 @@ Rake::RDocTask.new do |rdoc|
   rdoc.title = "snarl-snp #{version}"
   rdoc.rdoc_files.include('README.rdoc*')
   rdoc.rdoc_files.include('GUIDE.rdoc*')
+  rdoc.rdoc_files.include('YAML.rdoc*')
   rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.include('doc-ja/**/*rdoc.ja')
 end

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/YAML.rdoc

@@ -0,0 +1,197 @@
+= YAML for Snarl::SNP.load(yaml)
+
+NOTE: YAML is linehead-space-sensitive. When you run samples, remove 4 white spaces from each line head.
+
+- Values from YAML are always overwriten by Snarl::SNP methods' arguments.
+
+    snp = Snarl::SNP.load(<<YAML)
+    title : yaml title!
+    YAML
+    snp.notification(:title => 'new title') #=> "new title"
+
+- nil value / empty value / undef key are considerd as 'it is not set on yaml'.
+
+    - class : nil
+    - class : []
+    (there is no 'class')
+
+== text and title
+
+If
+- there is "text : ..." field or "title : ..." field
+and
+- there is no "notification : ..." field,
+Snarl::SNP.load(yaml) makes notification massage with "text :", "title :", "timeout :", "icon :" and "class :".
+
+=== host
+
+    host : 192.168.0.2
+
+The hostname/address of Snarl Machine. (This is used as TCPSocket.open(host)).
+If nothing is set on yaml and methods arguments, last 'host' value is 127.0.0.1.
+
+=== port
+
+    port : 9887
+
+The port number which Snarl uses. 9887. (This is used as TCPSocket.open(host, port)).
+If nothing is set on yaml and methods arguments, last 'port' value is 9887.
+
+=== app, name, register
+
+    app : Ruby-Snarl
+
+The application name. This is shown on Snarl setting window. (This is used as Snarl::SNP#register(app))
+If nothing is set on yaml and methods arguments, last 'app' value is nil. "anonymous application message".
+
+=== class, add_class
+
+    class :
+      - [classname1, classtitle1]
+      - [classname2, classtitle2]
+
+The classname and classtitle alias.
+The classname is used for classifing your message.
+The classtitle is shown on Snarl setting window(it is optional. if nil, classname is shown).
+(This is used as SNP#add_class(classname1, classtitle1) and SNP#notification(:text => text, :class => classname1))
+If nothing is set on yaml and methods arguments, last 'class' value is nil. "anonymous class message".
+
+    class : classname1
+
+    class : [classname1, classname2, classname3]
+
+    class :
+      - [classname1, classtitle1]
+or
+    class : [[classname1, classtitle1]]
+
+=== title
+
+    title : message title
+
+The title of popup messages.
+If there is no "notification : ..." field, SNP#notification makes message with this value as title.
+When "notification : ..." has no 'title' key, SNP#notification uses this value as notification title.
+If nothing is set on yaml and methods arguments, last 'title' value is Ruby-Snarl.
+
+=== text, message
+
+    text : hello, Ruby!
+
+The body of popup messages.
+If there is no "notification : ..." field, SNP#notification makes message with this value as body text.
+When "notification : ..." has no 'text' key, SNP#notification uses this value as notification body.
+If nothing is set on yaml and methods arguments, last 'body' value is nil. empty body message.
+
+=== timeout, sec
+
+    timeout : 30
+
+The "timeout" seconds of popups. After this seconds, popups are automatically closed.
+If SNP#notification makes message for lack of "notification : ..." field, SNP#notification uses this value as timeout.
+When "notification : ..." has no 'timeout' key, SNP#notification uses this value as notification timeout.
+"timeout : 0" makes popups "sticky". popups never close by time.
+If nothing is set on yaml and methods arguments, last 'timeout' value is 10.
+
+=== sticky
+
+    sticky : true
+
+makes popups "sticky". It is same to "timeout : 0". It is mainly for snarl_snp command. Do not use.
+If nothing is set on yaml, sticky is false.
+
+=== icon
+
+    icon : http://exsample.com/good.png
+
+The icon path of popups. The popup has this images as icon.
+If SNP#notification makes message for lack of "notification : ..." field, SNP#notification uses this value as icon.
+When "notification : ..." has no 'icon' key, SNP#notification uses this value as notification icon.
+
+The value is URL or filepath. The filepath should be accessable an absolute/relative path on Snarl machine.
+Image types are Jpeg, PNG, GIF, and so on.
+If nothing is set on yaml and methods arguments, last 'icon' value is nil. The icon will be a style's default icon.
+
+=== notification
+
+    notifitation : [title, text, icon.jpg, 9, classname]
+or
+    notifitation :
+      title   : title
+      text    : text
+      icon    : icon.jpg
+      timeout :  9
+      class   : classname
+or
+    notifitation :
+      -
+        title : 1st message
+        text  : one
+      -
+        title : 2nd message
+        text  : two
+      - { title : 3rd message, title : three }
+
+The popup messages. This is for Snarl::SNP#notification(params). params is Array or Hash above.
+
+If notification field has no key of 'title', 'text', 'icon', 'timeout', and top fields has same name one, SNP#notification uses top fields' value as its arguments.
+
+    # actually same message
+    notifitation :
+      title   : title
+      text    : text
+      timeout :  9
+
+    title   : title
+    timeout :  9
+    notifitation :
+      text    : text
+
+If there is no "notifitation : " field (and no "title : " and "text :" field), Snarl::SNP.load(yaml) sends no notifitation message.
+
+=== unregister
+
+    unregister : true
+
+removes application from Snarl setting window.
+If true, application is removed from Snarl settings after closing Snarl::SNP.load(yaml){...} block,
+and users are not able to change application settings.
+
+=== logfile
+
+    logfile : $stdout
+
+SNP logs are put to this path's file. Logger.new(logfile).
+YAML value is always String, but '$stdout' and '$stderr' are treated as Ruby's $stdout IO and $stderr IO.
+If you set "logfile : $stdout", SNP logs are printed to standard output.
+If you set "logfile : $stderr", SNP logs are printed to standard error.
+
+If nothing is set on yaml and methods arguments, last 'logfile' value is nil. No log messages are printed.
+
+=== loglevel
+
+    loglevel : INFO
+
+The loglevel for logger output. "logfile : " field is required. (or, SNP.load(yaml, logger) is also ok)
+The values are DEBUG, INFO, WARN, ERROR, FATAL (they are not case-sensitive) or 0, 1, 2, 3, 4.
+
+ERROR (or 3) :: Snarl error, TCPSocket connection fail
+INFO (or 1)  :: ERROR, and SNP response code
+DEBUG (or 0) :: INFO, and sent string to Snarl
+
+If loglevel is nil/unset (and there is any logger), loglevel is DEBUG. All logs are printed.
+
+=== iconset
+
+    iconset :
+      ok   : ./green.jpg
+      fail : ./red.jpg
+    notification :
+      title : Good!
+      text  : no errors.
+      icon  : ok
+
+The icons for notification.
+It works as "icon : ./green.jpg", and
+     snp.notification(:title => title, :text => text, :icon => iconset['ok'])
+.

data/bin/snarl_snp

@@ -0,0 +1,112 @@
+#!/usr/local/bin/ruby
+require 'optparse'
+require 'yaml'
+$LOAD_PATH.unshift(File.join(File.dirname(File.expand_path(__FILE__)), '/../lib/'))
+require 'snarl/snp'
+
+class SNPBin
+
+  BINCMD_OPTION = {
+    "host" => {
+      :opt => ['-H host',  '--host=host'],
+      :help => "the host address to send notification message. if you run on Snarl machine, set 'localhost' or '127.0.0.1'.  Default: localhost"
+    },
+    "port" => {
+      :opt => ['-p port',  '--port=port'],
+      :help => "the port to send notification message. SNP default is 9887.  Default: 9887"
+    },
+    "app"  => {
+      :opt => ['-a app',   '--app=app'],
+      :help => "the name of your messaging program. this is shown on Snarl Setting window until unregister.  Default: (nothing, anonymous application)"
+    },
+    "class" => {
+      :opt => ['-c class', '--class=class',],
+      :help => "the class type of message. same classed message is treated as a 'same class' message.  Default:(nothing, anonymous class)"
+    },
+    "title" => {
+      :opt => ['-t title', '--title=title'],
+      :help => "the notification message title.  Default: Ruby-Snarl" # default maybe
+    },
+    "timeout" => {
+      :opt => ['-s sec', '-d sec', '--span=sec', '--timeout=sec', '--duration=sec'],
+      :help => "the popup duration time(seccond). when sec=0, popup is sticky (never automatically closed).  Default: 10"
+    },
+    "sticky" => {
+      :opt => ['--sticky'],
+      :help => "make notification message 'sticky'. the message popup never closes automatically. -s sec option are ignored."
+    },
+    "icon" => {
+      :opt => ['--icon=url_or_path'],
+      :help => "the icon path for notification message. http URL or absolute path or relative path (relative to Snarl work dir). image type are JPEG, GIF, PNG.  Default: (nothing, default icon of Snarl style)"
+    },
+    "text" => {
+      :opt => ['-m message_text', '--message=message_text', '--text=message_text'],
+      :help => "the notification message text."
+    },
+    # "notification" => ['-n notification_subcmd_set'] # TODO:
+    "unregister" => {
+      :opt => ['-u', '--unregister'],
+      :help => "unregister application on Snarl setting after notification.  Default (unset)"
+    },
+    "verbose" => {
+      :opt => ['--verbose'],
+      :help => "print SNP log to stdout"
+    },
+    "yaml" => {
+      :opt => ['-y yaml_or_path', '--yaml=yaml_or_path', '--config=yaml_or_path'],
+      :help => "read and set paramater from YAML file or YAML string. for yaml details, see YAML.rdoc"
+    },
+  }
+  # --yaml #=> YAML String / --config #=> YAML path
+  # --silent / --quiet / --verbose
+
+  def initialize
+    @argv_option = {}
+    @config = {}
+  end
+
+  attr_reader :argv_option, :config
+
+  def parse_argv
+    OptionParser.new do |opt|
+      BINCMD_OPTION.each do |name, data|
+        instance_eval "opt.on(*(#{data[:opt].inspect} << \"#{data[:help]}\")){|v| @argv_option[\"#{name}\"] = v}"
+      end
+      opt.parse!(ARGV)
+    end
+  end
+
+  def merge_yaml_from_argvopt
+    if @argv_option['yaml'] then
+      @config.update(YAML.load(File.open(@argv_option['yaml']){|f| f.read}))
+      @argv_option.delete('yaml')
+    end
+  end
+  def merge_all_argvopt_to_config
+    @config.update(@argv_option)
+  end
+  def pick_logger
+    if @argv_option['verbose'] then
+      require 'logger'
+      @logger = Logger.new($stdout)
+      @argv_option.delete('verbose')
+    else
+      @logger = nil
+    end
+  end
+
+  def exec_snplib
+    # oh reconvert to yaml
+    Snarl::SNP.load(@config.to_yaml, @logger)
+  end
+
+  def run
+    parse_argv
+    merge_yaml_from_argvopt
+    pick_logger
+    merge_all_argvopt_to_config
+    exec_snplib
+  end
+end
+
+SNPBin.new.run unless defined?(TEST_SNARL_SNP_BIN_SPEC)