Expand file tree

automaticruby

名前
 automaticruby - Ruby による汎用的な自動処理フレームワーク

書式
 ./automatic.rb

 任意のレシピを指定して起動する
 ./automatic.rb -c <recipe>

 バージョン番号を表示する
 ./automatic.rb -v

説明
 このソフトウェアは、プラガブルに機能を拡張可能な Ruby
による汎用自動処理フレームワークである。
 プラグインによってさまざまな情報を収集加工し、任意の
形で出力することができる。


============
インストール
============

 本ソフトウェアを GitHub がらダウンロードする。
 任意のレシピ (後述) を作成する。
 -c オプション付きで手動実行し、問題がなければ
 cron に登録するなどして自動化する。


==========================
ディレクトリとファイル構成
==========================
.
|
+- automatic.rb
|    実行ファイル本体
|
+- config
|   |
|   +- default.yml
|        デフォルトでロードされるレシピ
|        YAML 形式でプラグインの情報を記述する
|        automatic.rb の -c オプションの引数で
|        任意のファイル名をレシピとして指定できる
|
|   新しくレシピを書いた場合は config ディレクトリに置く
|
|
+- plugins
|   |
|   +- subscription フィードを購読するプラグイン
|   |
|   +- filter 情報をフィルタリングするプラグイン
|   |
|   +- store 情報を内部に保存するプラグイン
|   |
|   +- publish 外部に情報を送信するプラグイン
|
|   プラグインを開発した場合は plugins ディレクトリに置く
|
|
+- lib
|   |
|   +- core.rb
|   |    パイプラインと呼ばれるオブジェクトを利用し
|   |    レシピに書かれたプラグインに処理を順次受け渡す
|   |
|   +- feed_parser.rb
|   |    ターゲットとなるフィードを解析し
|   |    エントリのリンクを抽出する
|   |
|   +- log.rb
|   |    ログを出力する
|   |
|   +- hb.rb
|        はてなブックマークの API に対し
|        投稿用 XML を生成して post する
|
+- db
|   |
|   +- bookmark.db
|        StoreBookmark プラグインで収集された
|        ブックマークが保存される
|
+- utils
|   |
|   +- opml_parser.rb
|        OPML からフィードの URL を抽出する
|
+- doc
    |
    +- COPYING
    |    本ソフトウェアのライセンス
    |
    +- README.ja
         本ドキュメント


==========
レシピとは
==========

 Automatic Ruby では YAML 形式で書かれた設定ファイル
を解析し、呼び出すプラグインの情報とそれに伴う様々な
情報を読み込む。

 この YAML ファイルをレシピと呼ぶ。

 automatic.rb 起動時に -c オプションの引数にレシピの
ファイル名を指定することができる。オプションが省略
された場合は config/default.yml が呼ばれる。

[起動例]
$ automatic.rb -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:
      exclude:
        - hoge
        - fuga

  - module: StoreBookmark
    config:
      db: bookmark.db

  - module: PublishHatenaBookmark
    config:
      username: your_hatena_id
      password: your_password

このサンプルレシピの例では
1. フィードを購読し
2. 無視キーワードを含む URL を除外し
3. 情報をデータベースに保存し
4. はてなブックマークをする
という一連の処理をプラグインの組み合わせで実現している。

このように、プラグインと設定情報をレシピに記述するだけで
複数のプラグインの組み合わせにより自由な処理を実現できる。

たとえば Twitter に投稿する Publish::Twitter プラグインを
作成し上記のレシピに記述すれば、自動的に記事を Twitter に
投稿する自動処理が完成する。

Gmail に送信する Publish::Gmail プラグインを作成しレシピ
に追加すれば、フィードの記事を Gmail で読めるようになる。

他にもリンクを元にブログ記事全文を取得したり、電子書籍の
形式にして Kindle で読めるようにしたり、データベースに
ブログ記事全文を保存してローカルのアプリで読めるように
したりなど、プラグインの組み合わせ次第で無限の可能性を
実現することができる。



==================
プラグインの作り方
==================

 たとえば自動処理した何らかの情報を 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 に戻る。

 コードは以下の通りである。

  YAML.load_documents(io) {|yaml|
    @pipeline = []
    yaml['plugins'].each {|plugin|
      loader = eval(plugin['module']).new(plugin['config'], @pipeline)
      @pipeline = loader.run
    }
  }

 プラグイン間での連続した @pipeline の受け渡しにより
処理要素を直列に連結し、あるプラグインの出力が次の
プラグインの入力となるパイプライン処理を実現する。

 この機構を本フレームワークでは Automatic::Pipeline と呼ぶ。



======================
プラグインの実装ルール
======================

 プラグインのコンストラクタは YAML.load によってロード
されたハッシュの配列、及びパイプラインと呼ばれる
インスタンス変数のオブジェクトを引数に取る。

 推奨されるコンストラクタの実装例は以下の通りである。

def initialize(config, pipeline=[])
  @config = config
  @pipeline = pipeline
end

 インスタンスメソッド run が自動的に呼ばれる。
 戻り値はインスタンス変数 @pipeline に渡り、レシピで
定義された次のプラグインに引き渡される。



================
プラグインの説明
================

SubscriptionFeed
----------------
[パス]
 /plugins/subscription/feed.rb

[概要]
 フィードを購読する

[レシピ記法]
  - module: SubscriptionFeed
    config:
      feeds:
        - フィード名
        - フィード名 ...


FilterIgnore
------------
[パス]
 /plugins/filter/ignore.rb

[概要]
 NG ワードを除外する

[レシピ記法]
  - module: FilterIgnore
    config:
      exclude:
        - 無視キーワード
        - 無視キーワード ...


StoreBookmark
-------------
[パス]
 /plugins/store/bookmark.rb

[概要]
 ブックマークを保存する
 DB を参照し重複したブックマークは破棄する

[レシピ記法]
  - module: StoreBookmark
    config:
      db: ブックマークを保存する SQLite3 DB 名


PublishHatenaBookmark
---------------------
[パス]
 /plugins/publish/hatenabookmark.rb

[概要]
 はてなブックマークをする

[説明]
 はてなブックマーク API への投稿用 XML を生成し
送信する

[レシピ記法]
  - module: AutoBookmark
    config:
      username: はてな ID
      passowrd: パスワード



====================
その他のツールの説明
====================

名前
 utils/opml_parser.rb

説明
 既存の RSS Reader の OPML から登録済みフィードの
URL リストを抽出するのに使う。

$ ruby opml_parser.rb > feeds.txt


========
動作環境
========

Ruby 1.8 以降


========
注意事項
========

悪用せず、常識の範囲の利用に留めること。

本ソフトウェアでは GPLv3 ライセンスのみ許可する。
ライセンス違反の無いようにすること。