automatic 12.2.1

data/doc/ChangeLog

@@ -0,0 +1,17 @@
+=== 12.02.1 / 2012-02-25
+
+* Point release
+
+  * Big Refactoring for core.
+	* Reorganization of the namespace.
+  * A few plugins added.
+
+
+=== 12.02 / 2012-02-18
+
+* First release
+
+  * Scratch of this script.
+	* Plugin existing only for hatenabookmark.
+
+

data/doc/PLUGINS.ja

@@ -0,0 +1,205 @@
+================
+プラグインの説明
+================
+
+SubscriptionFeed
+----------------
+[パス]
+ /plugins/subscription/feed.rb
+
+[概要]
+ フィードを購読する
+
+[レシピ記法]
+  - module: SubscriptionFeed
+    config:
+      feeds:
+        - フィード名
+        - フィード名 ...
+
+
+FilterIgnore
+------------
+[パス]
+ /plugins/filter/ignore.rb
+
+[概要]
+ NG ワードを除外する
+
+[レシピ記法]
+  - module: FilterIgnore
+    config:
+      exclude:
+        - 無視キーワード
+        - 無視キーワード ...
+
+
+FilterImage
+------------
+[パス]
+ /plugins/filter/image.rb
+
+[概要]
+ パーマリンクを本文中の画像のリンクに書き換える
+ 画像のリンクが無い場合は nil にする
+
+[レシピ記法]
+  - module: FilterImage
+
+
+FilterTumblrResize
+--------------------
+[パス]
+ /plugins/filter/tumblr_resize.rb
+
+[概要]
+ パーマリンクを Tumblr の最大サイズ
+ (High Res) に書き換える
+
+[前提]
+ パーマリンクが画像リンクに書き換え済であること
+
+[レシピ記法]
+  - module: FilterTumblrResize
+
+
+StorePermalink
+--------------
+[パス]
+ /plugins/store/permalink.rb
+
+[概要]
+ パーマリンクを保存する
+ 重複したパーマリンクは破棄する
+
+[レシピ記法]
+  - module: StoreBookmark
+    config:
+      db: ブックマークを保存する SQLite3 DB 名
+
+
+StoreFullText
+-------------
+[パス]
+ /plugins/store/full_text.rb
+
+[概要]
+ フィード全文を DB に保存する
+
+ 保存した DB は以下のビューワでも閲覧できる
+ https://github.com/id774/blog_viewer
+
+[レシピ記法]
+  - module: StoreFullText
+    config:
+      db: SQLite3 DB 名
+
+
+StoreTargetLink
+--------------
+[パス]
+ /plugins/store/target_link.rb
+
+[概要]
+ リンク先のコンテンツをローカルに保存する
+
+[レシピ記法]
+  - module: StoreTargetLink
+    config:
+      path: 保存先のフォルダ
+      interval: 保存する間隔 (秒)
+
+
+PublishConsole
+------------
+[パス]
+ /plugins/publish/console.rb
+
+[概要]
+ パイプラインをコンソールに出力する
+
+[レシピ記法]
+  - module: PublishConsole
+
+
+PublishHatenaBookmark
+---------------------
+[パス]
+ /plugins/publish/hatenabookmark.rb
+
+[概要]
+ はてなブックマークをする
+
+[説明]
+ はてなブックマーク API への投稿用 XML を生成し
+送信する
+
+[レシピ記法]
+  - module: AutoBookmark
+    config:
+      username: はてな ID
+      passowrd: パスワード
+      interval: はてブする間隔 (秒)
+
+
+PublishGoogleCalendar
+---------------------
+[パス]
+ /plugins/publish/google_calendar.rb
+
+[概要]
+ Google Calendar に予定を登録する
+
+[説明]
+ item.title を当日の Google カレンダーに
+登録する
+
+[レシピ記法]
+  - module: PublishGoogleCalendar
+    config:
+      username: Google メールアドレス
+      password: パスワード
+      interval: 複数の予定の投稿間隔 (秒)
+
+
+NotifyIkachan
+-------------
+[パス]
+ /plugins/notify/ikachan.rb
+
+[概要]
+ ikachan へメッセージを送信する
+
+[説明]
+ ikachan へ HTTP 経由で POST する
+ ikachan とは: http://blog.yappo.jp/yappo/archives/000760.html
+
+[レシピ記法]
+  - module: NotifyIkachan
+    config:
+      url: http://sample.com
+      port: 4979             # ポート番号、デフォルトは 4979
+      channels: foo,bar,#baz # '#' はあってもなくても自動的につけられる、複数は','で指定
+      command: notice        # privmsg や notice など
+      interval: 5            # ポストする間隔 (秒)
+
+
+CustomFeedSVNLog
+----------------
+[パス]
+ /plugins/custom/feed_svn_log.rb
+
+[概要]
+ SVN から新しいリビジョン情報を取得する
+
+[説明]
+ target で指定された URL から SVN のコミット情報を
+ fetch_items で指定された数だけ取得する
+
+[レシピ記法]
+  - module: CustomFeedSVNLog
+    config:
+      target: http://redmine.rubyforge.org/svn
+      fetch_items: 2 # 指定されない場合は 30
+
+

data/doc/README.ja

@@ -0,0 +1,449 @@
+automaticruby
+
+名前
+ automaticruby - Ruby による汎用的な自動処理フレームワーク
+
+書式
+$ bin/automatic
+
+ 任意のレシピを指定して起動する
+$ bin/automatic -c <recipe>
+
+ バージョン番号を表示する
+$ bin/automatic -v
+
+説明
+ このソフトウェアは、プラガブルに機能を拡張可能な Ruby
+による汎用自動処理フレームワークである。
+ プラグインによってさまざまな情報を収集加工し、任意の
+形で出力することができる。
+
+
+============
+インストール
+============
+
+ 本ソフトウェアを GitHub がらダウンロードする。
+$ git clone git://github.com/id774/automaticruby.git
+
+
+ ruby 1.9 の場合
+$ script/bootstrap
+
+ ruby 1.8 の場合
+ Gemfile にある必要な gem を手動でインストールする
+
+
+ 任意のレシピ (後述) を作成する。
+$ bin/automatic -c your_recipe.yml
+
+ -c オプション付きで手動実行し、問題がなければ
+ cron に登録するなどして自動化する。
+
+
+============
+実行してみる
+============
+
+ 試しに実行するなら config/feed2console.yml
+を利用すると良い。
+
+$ bin/automatic -c config/feed2console.yml
+
+ これは、ブログのフィードを単純にコンソール出力するだけの
+簡単なレシピである。
+ 本ソフトウェアの動作確認に使うことができる。
+
+
+==========================
+ディレクトリとファイル構成
+==========================
+.
+|
++- bin
+|   |
+|   +- automatic
+|        実行ファイル本体
+|
++- config
+|   |
+|   +- default.yml
+|        デフォルトでロードされるレシピ
+|        YAML 形式でプラグインの情報を記述する
+|        automatic.rb の -c オプションの引数で
+|        任意のファイル名をレシピとして指定できる
+|
+|   新しくレシピを書いた場合は config ディレクトリに置く
+|
+|
++- plugins
+|   |
+|   +- subscription フィードを購読するプラグイン
+|   |
+|   +- filter 情報をフィルタリングするプラグイン
+|   |
+|   +- store 情報を内部に保存するプラグイン
+|   |
+|   +- publish 外部に情報を送信するプラグイン
+|
+|   プラグインを開発した場合は plugins ディレクトリに置く
+|
+|
++- lib
+|   |
+|   +- automatic.rb
+|   |    Automatic モジュールの定義をする
+|   |
+|   +- automatic
+|   |   |
+|   |   +- environment.rb
+|   |   |    環境情報を読み込む
+|   |   |
+|   |   +- pipeline.rb
+|   |   |    パイプラインと呼ばれるオブジェクトを利用し
+|   |   |    レシピに書かれたプラグインに処理を順次受け渡す
+|   |   |
+|   |   +- feed_parser.rb
+|   |   |    フィードを解析する
+|   |   |
+|   |   +- log.rb
+|   |   |    ログを出力する
+|   |   |
+|   |   +- recipe.rb
+|   |        レシピを読み込む
+|   |
+|   +- config
+|
++- db
+|   |
+|   +- permalink.db
+|        Store::Permalink プラグインで収集された
+|        ブックマークが保存される
+|
++- script
+|   |
+|   +- bootstrap
+|        bundle install 等の環境設定をおこなう
+|        (ruby 1.9 以上のみ)
+|
++- utils
+|    補助的なツールのためのディレクトリ
+|
++- spec
+|    ユニットテスト用ディレクトリ
+|
++- test
+|   |
+|   +- integration
+|        インテグレーションテスト用ディレクトリ
+|
++- vendor
+|   |
+|   +- gems
+|        bundle install された gem パッケージ
+|
++- doc
+    |
+    +- COPYING
+    |    本ソフトウェアのライセンス
+    |
+    +- PLUGINS.ja
+    |    プラグインについてのドキュメント
+    |
+    +- README.ja
+         本ドキュメント
+
+
+==========
+レシピとは
+==========
+
+ Automatic Ruby では YAML 形式で書かれた設定ファイル
+を解析し、呼び出すプラグインの情報とそれに伴う様々な
+情報を読み込む。
+
+ この YAML ファイルをレシピと呼ぶ。
+
+ automatic.rb 起動時に -c オプションの引数にレシピの
+ファイル名を指定することができる。オプションが省略
+された場合は config/default.yml が呼ばれる。
+
+[起動例]
+$ bin/automatic -c ~/recipes/your_recipe.yml
+
+
+================
+レシピの記述方法
+================
+
+ レシピには暗黙的な命名規則がある。
+ 以下はレシピのサンプルとなる YAML ファイルである。
+
+global:
+  timezone: Asia/Tokyo
+  cache:
+    base: /tmp
+  log:
+    level: info
+
+plugins:
+  - module: SubscriptionFeed
+    config:
+      feeds:
+        - http://example.com/rss2
+        - http://hogefuga.com/feed
+
+  - module: FilterIgnore
+    config:
+      link:
+        - hoge
+        - fuga
+
+  - module: StorePermalink
+    config:
+      db: permalink.db
+
+  - module: PublishHatenaBookmark
+    config:
+      username: your_hatena_id
+      password: your_password
+      interval: 5
+
+このサンプルレシピの例では
+1. フィードを購読し
+2. 無視キーワードを含む URL を除外し
+3. パーマリンクをデータベースに保存し
+4. はてなブックマークをする
+という一連の処理をプラグインの組み合わせで実現している。
+
+このように、プラグインと設定情報をレシピに記述するだけで
+複数のプラグインの組み合わせにより自由な処理を実現できる。
+
+たとえば Twitter に投稿する Publish::Twitter プラグインを
+作成し上記のレシピに記述すれば、自動的に記事を Twitter に
+投稿する自動処理が完成する。
+
+Gmail に送信する Publish::Gmail プラグインを作成しレシピ
+に追加すれば、フィードの記事を Gmail で読めるようになる。
+
+他にもリンクを元にブログ記事全文を取得したり、電子書籍の
+形式にして Kindle で読めるようにしたり、データベースに
+ブログ記事全文を保存してローカルのアプリで読めるように
+したりなど、プラグインの組み合わせ次第で無限の可能性を
+実現することができる。
+
+
+
+==============
+開発に参加する
+==============
+
+リポジトリ
+https://github.com/id774/automaticruby
+
+課題
+https://github.com/id774/automaticruby/issues
+
+CI
+http://id774.net/jenkins/
+
+
+プラグインを新しく作ったり、あるいはフレームワークを
+改善してくれるなら、以下の手順で開発に参加できる。
+
+1. GitHub でリポジトリをフォークする。
+2. プラグインを新しく作ったりする。
+3. Pull Request を送信する。
+
+なんらかの貢献があった場合、少しの修正を迅速におこなうために
+コミット権を配布する。
+
+
+================
+コーディング規約
+================
+
+2 タブ (ソフトタブ)
+末尾のスペースは除去
+名前空間は既存のコードを参照
+{} は do end より推奨される
+RDoc ヘッダはファイルの作者によって書かれる
+RSPec でテストを書く
+カバレッジ 100% を目指す
+
+
+==================
+プラグインの作り方
+==================
+
+ たとえば自動処理した何らかの情報を Twitter に投稿したい。
+
+ このようなときは Publish::Twitter プラグインを作れば良い。
+
+ 実装方法については後述するが、基本的には Twitter の API に
+投稿するだけの簡単な Ruby スクリプトを作るだけである。
+
+ レシピはこのようになるだろう。
+
+  - module: PublishTwitter
+    config:
+      username: your_mail_address
+      password: your_password
+
+ この場合、ファイルを plugins/publish 配下に置き、クラス名
+はレシピで指定した PublishTwitter とする。あとは後述する
+Automatic::Pipeline の機能により自動的に処理される。
+
+
+========================
+Automatic::Pipeline とは
+========================
+
+ 本フレームワークはレシピを YAML で解析し、プラグインを
+順次読み込む。このとき pipeline がインスタンス生成時の
+引数として渡され、戻り値は pipeline に戻る。
+
+ コードは以下の通りである。
+
+ pipeline = []
+ recipe.each_plugin { |plugin|
+   load_plugin(plugin.module)
+   klass = Automatic::Plugin.const_get(plugin.module)
+   pipeline = klass.new(plugin.config, pipeline).run
+ }
+
+ プラグイン間での連続した pipeline の受け渡しにより
+処理要素を直列に連結し、あるプラグインの出力が次の
+プラグインの入力となるパイプライン処理を実現する。
+
+ この機構を本フレームワークでは Automatic::Pipeline と呼ぶ。
+
+
+====================
+プラグインの実装規約
+====================
+
+ プラグインのコンストラクタは YAML.load によってロード
+されたハッシュの配列、及びパイプラインと呼ばれる
+インスタンス変数のオブジェクトを引数に取る。
+
+ 推奨されるコンストラクタの実装例は以下の通りである。
+
+def initialize(config, pipeline=[])
+  @config = config
+  @pipeline = pipeline
+end
+
+ インスタンスメソッド run が自動的に呼ばれる。
+ 戻り値はインスタンス変数 @pipeline に渡り、レシピで
+定義された次のプラグインに引き渡される。
+
+
+==============
+ユニットテスト
+==============
+
+ ユニットテストは RSpec でおこなう。
+
+ プラグインのテストは、引数となるパイプラインを渡し
+戻り値を検査する。
+
+
+========================
+継続的インテグレーション
+========================
+
+ CI は Jenkins でおこなう。
+ http://id774.net/jenkins/
+
+
+========
+結合試験
+========
+
+ test/integration 配下に複数のレシピを結合して
+テストをおこなうためのレシピを置く。
+
+
+
+================
+プラグインの説明
+================
+
+doc/PLUGINS.ja を参照
+
+
+
+====================
+その他のツールの説明
+====================
+
+utils の下にはフィードを扱うための補助的なツールが
+置かれる。内容は以下のとおりである。
+
+
+名前
+ utils/opml_parser.rb
+
+説明
+ 既存の RSS Reader の OPML から登録済みフィードの
+URL リストを抽出するのに使う。
+
+$ ruby opml_parser.rb > feeds.txt
+
+
+名前
+ utils/auto_discovery.rb
+
+説明
+ 引数に指定した URL から購読対象のフィードを
+オートディスカバリで抽出する。
+
+$ ruby auto_discovery.rb "https://twitter.com/twitt"
+["https://twitter.com/statuses/user_timeline/4441691.rss",
+ "https://twitter.com/favorites/4441691.rss"]
+
+
+
+========
+更新履歴
+========
+
+doc/ChangeLog を参照
+
+
+====
+TODO
+====
+
+ GitHub の issues を参照
+ https://github.com/id774/automaticruby/issues
+
+
+========
+動作環境
+========
+
+Ruby 1.8 以降
+
+
+以下の gem パッケージに依存
+
+sqlite3
+activesupport
+hashie
+activerecord
+gcalapi
+xml-simple
+
+詳細は Gemfile を参照
+
+
+========
+注意事項
+========
+
+過剰なスクレイピング等を避け、常識の範囲の利用に留める。
+本ソフトウェアは GPLv3 ライセンスである。
+
+