snarl-snp 0.1.1

data/GUIDE.rdoc.ja

@@ -0,0 +1,126 @@
+= SNP Connection Details with Snarl::SNP
+
+SNP のコマンド文字列（実際に Snarl の動作してるマシンのポート 9887 に TCPSocket#write で送られる文字列）は以下のようなものです。
+
+  type=SNP#?version=1.1#?action=notification#?app=Ruby-Snarl#?class=type1#?title=title#?text=type1 text!#?timeout=10\r\n
+
+data=value というペアが、区切り文字 #? で結合されて送信されます。終端は "\r\n" です。
+value には #? という文字を含むことは出来ません。"\r" を含むことも出来ません。
+Snarl::SNP のメソッドは、この長大な文字列を直接記述する代わりに、引数と内部デフォルト値から組み立てます。
+
+    snp.register('Ruby-Snarl')
+    snp.add_class('type1')
+    snp.notification('title', 'type1 text', nil, 10, 'type1')
+
+と
+    snp.request("type=SNP#?version=1.1#?action=register#?app=Ruby-Snarl\r\n")
+    snp.request("type=SNP#?version=1.1#?action=add_class#?app=Ruby-Snarl#?class=type1\r\n")
+    snp.request("type=SNP#?version=1.1#?action=notification#?app=Ruby-Snarl#?class=type1#?title=title#?text=type1 text!#?timeout=10\r\n")
+
+は、最終的に Snarl に送信された文字列は全く同じになります。
+Snarl::SNP は "\r" や "\r\n" は "\n" に置換して処理しますが、 #? を送ることは依然出来ません。エスケープの仕方を知ってる方はぜひご一報を。
+
+
+== 匿名クラスでポップアップを依頼する
+
+「アプリケーション名」を登録して、ポップアップ依頼を送ります。
+
+    require 'rubygems'
+    require 'snarl/snp'
+    Snarl::SNP.open(@host) do |snp|
+      snp.register('Ruby-Snarl')
+      snp.notification('title', 'text', nil, 10)
+    end
+    # as you like
+    # Snarl::SNP.new(@host).unregister('Ruby-Snarl')
+
+アプリケーション登録（register）だけを伴ったポップアップ依頼です。
+登録されたアプリケーションは、Snarl 本体の設定画面の「Apps」の「The following applications are registered with Snarl:」で列挙されます。SNP 経由の場合は「アプリケーション名 on 接続元アドレス」（例：「Ruby-Snarl on xxx.xxx.xxx.xxx」）と表示されます。
+これは SNP 経由で unregister するか、Snarl を再起動するまで保持されます。
+
+なお、Snarl::SNP におけるアプリケーション名は Snarl::SNP オブジェクトにつきひとつです。別名義のアプリケーションを使用したい場合は、Snarl::SNP オブジェクトを別途作成してください。
+
+=== 匿名アプリケーションポップアップ依頼
+
+アプリケーション設定が register されていない状態のとき（Snarl 再起動後など）に notification を送ると「匿名ポップアップ」として処理されます。スタイル等は反映されませんが、ポップアップは普通に行われます（これを意図的に利用するととても便利なのですが、なぜか日本語が化けるので説明では省いています）。
+
+    require 'rubygems'; require 'snarl/snp'; require 'kconv'
+    Snarl::SNP.new(@host).notification('title', 'あいうえお'.tosjis) #=> "あいぁE"
+
+「○○というアプリケーション用のポップアップ依頼だから○○アプリケーションの設定を自動で登録状態にして読み込んで使用する」というようなことはありません。
+
+=== 匿名クラスポップアップの表示を Snarl 側でカスタマイズする
+
+クラス設定を事前に SNP で送っていない場合、Snarl におけるクラスは匿名となります。本来は何らかのクラスを最低限1個、add_class で設定すべきなのですが、なくてもポップアップの動作設定はできます。
+アプリケーションを登録すると、アプリケーション名義でクラス設定をまとめることができます（○○アプリケーションのクラス設定1、のように）。
+次項のクラスつきポップアップ依頼を参考にして、<all>（他にクラス設定が何もないとき）または <other>（他の名前のクラス設定はあるが、匿名クラスを使うとき）で設定変更してください（このアプリケーションの匿名クラスポップアップ全てが影響を受けます）。これが好ましくない、またはクラスが複数あるほうが設定が使い分けられて都合がいいという場合は普通に SNP 経由でクラスを設定します。
+
+=== アプリケーションの2重登録
+
+既に同名（で、通信元が同ホスト）のアプリケーションが登録状態の場合、Snarl は「2度目以降の register」に対してエラーを返します。
+が、Snarl::SNP はこれを例外として扱いません（例外にすることもできます）。
+そもそもの登録行為自体、前回の register と今回の notification の間に Snarl が一度でも再起動されていると登録状態が解除されてしまっているという、永続性に疑問のあるてきとうなものなので、Snarl::SNP オブジェクト生成ごとに念のために register しておく、くらいの意気で構わないと思われます。
+
+  Snarl::SNP.open(@host) do |snp|
+    snp.register(app)
+    snp.add_class(class_id)
+    snp.notification(...)
+  end
+
+はセットとして毎回書いておくことをお勧めします。
+
+== unregister の罠
+
+スクリプトでは unregister がぽつんと 1個離れて「お好みで」とかコメントがついてますが、unregister は「Snarl でのアプリケーション登録状態を（クラスごと）解除する」という効果をもちます。
+register したんだから unregister もブロック内にペアで書くべき、なのですが、困ったことに Snarl は「unregister したアプリケーションは設定ウィンドウから消えて選べない」という仕様になっています。
+なので、ユーザーが「このアプリケーションの表示設定を変えたい」と思っても、スクリプト内で unregister してしまうと Snarl の設定ウィンドウにはそのアプリケーションが表示されていないという事態になってしまいます。
+
+ irb> require 'rubygems'; require 'snarl/snp'
+ irb> @host = '127.0.0.1'
+ irb> snp = Snarl::SNP.new(@host)
+ irb> # Snarl の App 欄に「Ruby-Snarl on xxx.xxx.xxx.xxx」があれば一旦 unregister
+ irb> # snp.unregister('Ruby-Snarl')
+ irb> # 以下で Snarl の App 欄に「Ruby-Snarl on xxx.xxx.xxx.xxx」が出現する
+ irb> snp.register('Ruby-Snarl')
+ irb> # 以下で App 欄から「Ruby-Snarl on xxx.xxx.xxx.xxx」が消えてしまい触れなくなる
+ irb> snp.unregister('Ruby-Snarl')
+ irb> # コマンド送信ごとに TCPSocket.open(@host){...} してるので irb はこのまま閉じてOK
+
+なので、unregister は「Snarl の設定欄から自分の設定の表示を消したい」ときにのみ、行ってください。
+正直、普段使うようなコマンドではないと思われます。
+
+=== unregister してもユーザー設定自体は消えない
+
+unregister では Snarl の設定一覧から一旦消えるだけで、アプリケーションごとに設定した項目自体は Snarl のファイルに保存されています。設定を消す場合は
+
+  ユーザーフォルダ\Application Data\full phat\snarl\etc\.snarl
+
+というファイルの中の、 [app.なんとか] の該当しそうなブロックを適当に（あるいは行単位で慎重に）削除してください。
+適当な名前でテストしまくっていると全部記録されていて物凄い量になっていたりするので気をつけましょう。適宜掃除を。
+
+== クラスつきでポップアップを依頼する
+
+「アプリケーション名」を登録し「クラス名」を設定したあとに、それらを指定してポップアップ依頼を送ります。一番正当なものです。
+
+    require 'rubygems'
+    require 'snarl/snp'
+    Snarl::SNP.open(@host) do |snp|
+      snp.register('Ruby-Snarl')
+      snp.add_class('type1')
+      snp.add_class('type2')
+      snp.notification('title', 'type1 text', nil, 10, 'type1')
+      snp.notification('title', 'type2 text', nil, 10, 'type2')
+      snp.unregister('Ruby-Snarl')
+    end
+
+アプリケーション登録（register）とクラス名追加（add_class）を伴ったポップアップ依頼です。
+
+1. Snarl::SNP#register でアプリケーション名を登録する
+2. Snarl::SNP#add_class でクラス名を使用するぶんだけ登録する（複数可能）
+3. Snarl::SNP#notification で特定クラス使用のポップアップ依頼を送る
+4. Snarl::SNP#unregister でアプリケーション名を削除する
+
+という流れになります。
+クラス名は Snarl の「App」欄の当該アプリ名選択後の「Notification classes:」に列挙されます。
+type1 と書かれた欄を選んでたとえば「Visual」にて Style と Scheme を変更すれば、'type1' とした notification が来た場合にその Style でポップアップが表示されます。
+red というクラスつきの依頼では赤っぽいポップアップを、green というクラスつきの依頼では緑っぽいポップアップを使う、といったような設定ができます。

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 kitamomonga
+
+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/README.rdoc

@@ -0,0 +1,144 @@
+= snarl-snp
+
+Snarl Network Protocol(SNP) Client for Snarl. You can send messages to Snarl over 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.
+
+== Requirements
+
+- Ruby 1.8.6 or later (including 1.9.1)
+
+== Installation
+
+  gem install snarl-snp
+
+No other gems are required (only to test, WebMock is needed).
+
+== Contact
+
+ezookojo@gmail.com
+http://d.hatena.ne.jp/kitamomonga/ (in Japanese)
+
+== Short Exsamples
+
+@host is a Windows machine host which is running Snarl (LAN only).
+Set the value in advance, then copy and paste codes on irb.
+
+  @host = '192.168.0.2' # Snarl machine host
+
+When nil/undef, Snarl::SNP uses '127.0.0.1'. Default port is 9887.
+
+=== Simple Popup (anonymous application)
+
+    require 'rubygems'
+    require 'snarl/snp'
+    Snarl::SNP.show_message(@host, 'title', 'Hello, Snarl!')
+
+or
+
+    Snarl::SNP.new(@host).notification('title', 'Hello, Snarl!')
+    Snarl::SNP.open(@host){|snp| snp.notification('title', 'Hello, Snarl!')}
+
+Snarl::SNP can simply send message in this way, but you cannot change popup settings on Snarl.
+If you want to change popup settings(i.e. changing a color style), at least register an "application name".
+
+NOTE: The multibyte anonymous application messages may not work well.
+
+=== Popup Application (anonymous class)
+
+    require 'rubygems'
+    require 'snarl/snp'
+    Snarl::SNP.open(@host) do |snp|
+      snp.register('Ruby-Snarl')
+      snp.notification('title', 'text', nil, 10)
+    end
+    # if you wish
+    # Snarl::SNP.new(@host).unregister('Ruby-Snarl')
+
+"application name" is Ruby-Snarl.
+On Snarl, it's shown in "Apps" - "The following applications are registered with Snarl:" - "Ruby-Snarl on xxx.xxx.xxx.xxx".
+You can change popup settings now.
+If you want to classify messages(i.e. a green popup message, a red popup message, ...), set classes.
+
+=== Unregister Application (remove application setting from Snarl)
+
+When sending "unregister" or starting Snarl, application names are hideen from setting window.
+
+    require 'rubygems'
+    require 'snarl/snp'
+    Snarl::SNP.open(@host) do |snp|
+      snp.unregister('Ruby-Snarl')
+    end
+
+An unregister command makes the application "inactive".
+The application is removed from Snarl setting window, and Snarl users can not change their popup settings.
+If you wish to allow users to change the popup settings, you should not use unregister commands on your usual scripts.
+
+=== Popup Application (full)
+
+    require 'rubygems'
+    require 'snarl/snp'
+    Snarl::SNP.open(@host) do |snp|
+      snp.register('Ruby-Snarl')
+      snp.add_class('type1')
+      snp.add_class('type2')
+      snp.notification('title', 'type1 text', nil, 10, 'type1')
+      snp.notification('title', 'type2 text', nil, 10, 'type2')
+    end
+    # if you wish
+    # Snarl::SNP.new(@host).unregister('Ruby-Snarl')
+
+Classes are used for message classification. They are shown in "Apps" - "Notification classes:".
+If you change style of "type1" class on Snarl, all "type1" messages of application "Ruby-Snarl" pop in your way.
+
+=== Send SNP raw command strings
+
+    require 'rubygems'
+    require 'snarl/snp'
+    Snarl::SNP.open(@host) do |snp|
+      snp.request("type=SNP#?version=1.1#?action=register#?app=Ruby-Snarl\r\n")
+      snp.request("type=SNP#?version=1.1#?action=add_class#?app=Ruby-Snarl#?class=type1\r\n")
+      snp.request("type=SNP#?version=1.1#?action=add_class#?app=Ruby-Snarl#?class=type2\r\n")
+      snp.request("type=SNP#?version=1.1#?action=notification#?app=Ruby-Snarl#?class=type1#?title=title#?text=type1 text!#?timeout=10\r\n")
+      snp.request("type=SNP#?version=1.1#?action=notification#?app=Ruby-Snarl#?class=type2#?title=title#?text=type2 text!#?timeout=10\r\n")
+    end
+    # if you wish
+    Snarl::SNP.new(@host).request("type=SNP#?version=1.1#?action=unregister#?app=Ruby-Snarl\r\n")
+
+"\r\n" is must.
+Don't use "\r\n" or "\r" in message body. Use "\n" instead.
+
+=== Multibyte Popup
+
+    require 'rubygems'
+    require 'snarl/snp'
+    require 'kconv'
+    Snarl::SNP.open(@host){|snp| snp.notification('タイトル'.tosjis, '日本語'.tosjis)}
+
+Windows encoding is required.
+
+== FAQ
+
+=== My autotest/autospec shutdowns after test. Snarl got no message.
+
+Set Autotest::Snarl.host on ".autotest" file.
+
+  require 'snarl/autotest'
+  Autotest::Snarl.host = '192.168.0.1'
+
+You may set OS environment variable SNARL_HOST.
+Autotest::Snarl uses it instead of default host 127.0.0.1.
+If you use Snarl on 192.168.0.1 (and use bash as a shell),
+
+  SNARL_HOST=192.168.0.1 autotest
+
+== Copyright
+
+Copyright (c) 2010 kitamomonga (TATEWAKI Hiroyuki).
+This software is MIT license, see MIT-LICENSE file for details.
+Snarl and SNP is not mine. See http://www.fullphat.net/ .

data/README.rdoc.ja

@@ -0,0 +1,166 @@
+-*- coding: utf-8 -*-
+
+= Snarl-SNP
+
+snarl/snp（snarl-snp）は、Snarl を LAN 越しに操作するための SNP プロトコルクライアントを提供します。
+Ruby スクリプトの結果（の30字くらい）を Snarl に送ることができます。
+
+Snarl は Windows で動作する、Growl っぽい通知ポップアップを行うソフトウェアです。
+http://www.fullphat.net/
+
+SNP は Snarl Networking Protocol です。SNP1.1 は文書化されていませんが、1.0 は以下の場所にあります。
+http://www.fullphat.net/dev/snp/index.htm
+
+== Requirements
+
+- Ruby 1.8.6 or later (including 1.9.1)
+
+今のところ必要な追加ライブラリはありません。
+
+== Installation
+
+  gem install snarl-snp
+
+内部では Rubygems を使用してないので、lib/snarl/snp.rb と lib/snarl/snp/ だけあればたぶん動きます。
+
+== Contact
+
+ezookojo@gmail.com
+きたももんががきたん。
+http://d.hatena.ne.jp/kitamomonga/
+
+== License
+
+MIT License です。使用改変配布商用等を無制限に許可し、ソフトウェアに関する責任は全く負わないものとします。
+正確には MIT-LICENSE ファイルを http://sourceforge.jp/projects/opensource/wiki/licenses%2FMIT_license などを参考に読んでください。
+
+== Usage
+
+  require 'rubygems'
+  require 'snarl/snp'
+  require 'kconv' # on Ruby 1.8
+  
+  Snalr::SNP.open(Snarlが動いてるホスト) do |snp|
+    snp.register(設定区別用アプリケーション名)
+    snp.notification(メッセージ.tosjis) # toutf8かもしれない
+  end
+  # メッセージ表示をメッセージ種別ごとに分けたい場合は add_class(種別用クラス名) でクラスを追加したあとでクラス指定つきの notification をする
+  # こちらの環境では日本語文字は Shift_JIS にする必要があるが世間様では UTF-8 で通るらしい（たぶんWindowsのバージョン依存）
+
+== Short Exsamples
+
+@host は Snarl の動作している Windows マシンのホスト名か IP アドレスです（TCPSocket.open で使えるもの）。Snarl 本体の仕様上、LAN 内限定です。
+irb 上でコピペするときに便利なように、対象ホストは @host としか書いてません。事前に設定しておいてください。
+
+  @host = '192.168.0.2' # Snarl machine host
+
+Snarl が動作しているマシン上でスクリプトを動作させる場合は無設定の nil か "127.0.0.1" で OK です。
+何らかの理由で接続できない場合は Errno::ECONNREFUSED が出ます。
+
+=== Popup Application (anonymous class)
+
+    require 'rubygems'
+    require 'snarl/snp'
+    Snarl::SNP.open(@host) do |snp|
+      snp.register('Ruby-Snarl')
+      snp.notification('title', 'text', nil, 10)
+    end
+    # if you wish
+    # Snarl::SNP.new(@host).unregister('Ruby-Snarl')
+
+Snarl の設定画面では「Ruby-Snarl」と名づけられます。
+ポップアップメッセージは「title」「text」という2行で、標準アイコンつきで10秒表示されます。
+
+=== Unregister Application (remove application setting from Snarl)
+
+    require 'rubygems'
+    require 'snarl/snp'
+    Snarl::SNP.open(@host) do |snp|
+      snp.unregister('Ruby-Snarl')
+    end
+
+unregister は Snarl のポップアップ動作設定画面からアプリケーションを一旦削除します。
+register -> unregister という流れ的には使うべきっぽいんですが意外と不便なので多用しないことをお勧めします。
+設定された内容自体は Snarl のユーザーファイルに保存されており、register コマンドが来たときに再度ロードされます。
+
+アプリケーションは Snarl を再起動すると画面からは一旦消えます（unregister と同じ動作）。設定完全消去はファイルを編集します。
+
+=== Popup Application (full)
+
+    require 'rubygems'
+    require 'snarl/snp'
+    Snarl::SNP.open(@host) do |snp|
+      snp.register('Ruby-Snarl')
+      snp.add_class('type1')
+      snp.add_class('type2')
+      snp.notification('title', 'type1 text', nil, 10, 'type1')
+      snp.notification(:title => 'title', :text => 'type2 text', :icon => nil, :timeout => 7, :class => 'type2')
+    end
+    # if you wish
+    # Snarl::SNP.new(@host).unregister('Ruby-Snarl')
+
+add_class でクラス名を指定することも出来ます（Ruby の Class オブジェクトとは無関係です）。
+Snarl の設定画面では「Ruby-Snarl の中のクラス type1」という区分で、ポップアップスタイル等を変更できます。
+メッセージごとにウィンドウの色などを変えたいときに便利です。
+クラス名の設定は notification の第 5 引数になりますが、若干長いのでキーワード引数指定の活用などもどうぞ。
+
+=== Send SNP raw command strings
+
+    require 'rubygems'
+    require 'snarl/snp'
+    Snarl::SNP.open(@host) do |snp|
+      snp.request("type=SNP#?version=1.1#?action=register#?app=Ruby-Snarl\r\n")
+      snp.request("type=SNP#?version=1.1#?action=add_class#?app=Ruby-Snarl#?class=type1\r\n")
+      snp.request("type=SNP#?version=1.1#?action=add_class#?app=Ruby-Snarl#?class=type2\r\n")
+      snp.request("type=SNP#?version=1.1#?action=notification#?app=Ruby-Snarl#?class=type1#?title=title#?text=type1 text!#?timeout=10\r\n")
+      snp.request("type=SNP#?version=1.1#?action=notification#?app=Ruby-Snarl#?class=type2#?title=title#?text=type2 text!#?timeout=10\r\n")
+    end
+    # if you wish
+    # Snarl::SNP.new(@host).request("type=SNP#?version=1.1#?action=unregister#?app=Ruby-Snarl\r\n")
+
+本来の SNP のコマンドを直接送ります。デバッグ用途などお好みで。Fatal なエラーはふつうに例外になります。
+終端の \r\n は必須です。自動で付加することはありません。本文に \r が入っていると Snarl がそこでコマンド文字列を切ってしまうので改行は \n だけにしてください。なお、notification などでは内部処理されて取り除かれています。
+
+=== Multibyte Popup
+
+    require 'rubygems'
+    require 'snarl/snp'
+    require 'kconv'
+    Snarl::SNP.open(@host){|snp| snp.notification('タイトル'.tosjis, '日本語'.tosjis)}
+
+対象の Snarl が動作している Windows で使用されているエンコーディングに変換して文字列を送ってください。
+
+== FAQ
+
+=== autotest または autospec がポップアップを出さずに普通に終了してしまう
+
+Snarl::SNP が接続できなくてエラーを返しているのだと思われます。
+ホームディレクトリなどにある .autotest ファイルに Autotest::Snarl.host = '192.168.0.2' などと書いてください。
+
+  require 'snarl/autotest'
+  Autotest::Snarl.host = '192.168.0.2'
+
+autotest コマンドを環境変数 SNARL_HOST つきで起動しても構いません。Linux 上の bash だと
+
+  SNARL_HOST=192.168.0.1 autotest
+
+などとすることでうまくいきます。
+
+=== Snarl::SNP.show_message で日本語が化ける
+
+化ける場合は SNP か Snarl の仕様かもしれません。適当に register してから notification(title, text) を使ってください。
+app コマンドの指定がない notification アクションはなぜか日本語が化けます。
+事前に register されている場合、メッセージが ascii 文字だけの場合は問題ありません。
+
+show_message のウリは「Snarlの設定ファイルを汚さない匿名アプリケーションメッセージ」ですが、無論 register してしまうと Snarl に記録されます。
+引数なしで register とだけ書くとデフォルトの Snarl::SNP::DEFAULT_APP が使用されますので、アプリケーション名をいちいち考えるのが煩雑な雑多なメッセージの場合はこれで代用するとやや簡便です。
+
+  Snarl::SNP.open(@host) do |snp|
+    snp.register
+    snp.notification('ごはんが炊けたよ')
+  end
+
+=== SNP.open はいつ TCP ソケットを使用している？
+
+SNP コマンドを送る瞬間だけ TCPSocket.open(@host, @port){|s| s.write(cmdstr)} してます。
+ブロックつき open なのに、効率とかなにそれって感じでいちいちセッション切ってます。