automaticruby

名前

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

書式

$ automatic

任意のレシピを指定して起動する

$ automatic -c <recipe>

バージョン番号を表示する

$ automatic -v

説明

このソフトウェアは、プラガブルに機能を拡張可能な Ruby

による汎用自動処理フレームワークである。

プラグインによってさまざまな情報を収集加工し、任意の

形で出力することができる。

============

インストール

============

[安定版]

$ gem install automatic

$ automatic scaffold

(ホームディレクトリに ~/.automatic を生成する)

$ automatic -c ~/.automatic/config/example/feed2console.yml

(ブログのフィードを入力しターミナルに出力する)

[開発版]

$ git clone git://github.com/automaticruby/automaticruby.git

$ cd automaticruby

$ bundle install --path vendor/gems

$ bin/automatic scaffold

$ bin/automatic -c ~/.automatic/config/example/feed2console.yml

(上記に同じ)

============

実行してみる

============

任意のレシピ (後述) を作成する。

$ automatic -c your_recipe.yml

-c オプション付きで手動実行し、問題がなければ

cron に登録するなどして自動化する。

単純なファイル名を -c の引数に指定した場合 ~/.automatic/config

にある同名のファイルがあれば優先的に読み込まれる。無い場合は指定通りの

パスにあるファイルが読み込まれる。

~/.automatic/db が存在する場合、データベースを生成するタイプの

プラグインはこのディレクトリにファイルを保存する。

~/.automatic/plugins が存在する場合、本体付属のプラグインと

同様にそれらも読み込まれる。

試しに実行するなら以下を実行すると良い。

$ automatic -c ~/.automatic/config/example/feed2console.yml

これは、ブログのフィードを単純にコンソール出力するだけの

簡単なレシピである。

本ソフトウェアの動作確認に使うことができる。

==========

レシピとは

==========

Automatic Ruby では YAML 形式で書かれた設定ファイル

を解析し、呼び出すプラグインの情報とそれに伴う様々な

情報を読み込む。

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

automatic.rb 起動時に -c オプションの引数にレシピの

ファイル名を指定することができる。

[起動例]

$ automatic -c your_recipe.yml

================

レシピの記述方法

================

レシピには暗黙的な命名規則がある。

[書式]

plugins:

- module: プラグイン名

config:

変数

以下はレシピのサンプルとなる YAML ファイルである。

plugins:

- module: SubscriptionFeed

config:

feeds:

- http://reretlet.tumblr.com/rss

- module: StorePermalink

config:

db: tumblr.db

- module: FilterImage

- module: FilterTumblrResize

- module: StoreFile

config:

path: /Users/yourname/Desktop/

interval: 1

このサンプルレシピの例では

1. Subscription Feed で Tumblr のフィードを購読し

2. StorePermalink でパーマリンクをデータベースに保存し

3 FilterImage と FilterTumblrResize で画像の URL を指定して

4. StoreFile で Tumblr の画像をダウンロードする

という一連の処理をプラグインの組み合わせで実現している。

以下に別の例を示す。

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. Subscription Feed でフィードを購読し

2. FilterIgnore で無視キーワードを含む URL を除外し

3. StorePermalink でパーマリンクをデータベースに保存し

4. PublishHatenaBookmark ではてなブックマークをする

という一連の処理をプラグインの組み合わせで実現している。

このように、プラグインと設定情報をレシピに記述するだけで

複数のプラグインの組み合わせ次第で無限の可能性を実現する

ことができる。

==========================

ディレクトリとファイル構成

==========================

.

|

+- bin

| |

| +- automatic

| 実行ファイル本体

|

+- config

| YAML 形式でプラグインの情報を記述する

| automatic.rb の -c オプションの引数で

| 任意のファイル名をレシピとして指定できる

|

| 新しくレシピを書いた場合は config ディレクトリに置く

|

|

+- plugins

| |

| +- subscription

| | フィードを購読するプラグイン

| |

| +- customfeed

| | カスタムフィードを生成するプラグイン

| |

| +- filter

| | 情報をフィルタリングするプラグイン

| |

| +- store

| | 情報を内部に保存するプラグイン

| |

| +- notify

| | 情報を通知するプラグイン

| |

| +- publish

| 外部に情報を送信するプラグイン

|

| プラグインを開発した場合は plugins ディレクトリに置く

|

|

+- lib

| |

| +- automatic.rb

| | Automatic モジュールの定義をする

| |

| +- automatic

| |

| +- environment.rb

| | 環境情報を読み込む

| |

| +- pipeline.rb

| | パイプラインと呼ばれるオブジェクトを利用し

| | レシピに書かれたプラグインに処理を順次受け渡す

| |

| +- feed_parser.rb

| | フィードを解析する

| |

| +- log.rb

| | ログを出力する

| |

| +- recipe.rb

| レシピを読み込む

|

+- db

| ~/.automatic/db が無い場合、ここにデータベースが

| 保存される

|

+- assets

| json ファイルなどプラグインの中で適宜必要とされる

| ファイルが格納される

| ~/.automatic/assets がある場合はそちらが優先される

|

+- script

| |

| +- build

| CI で実施する結合試験をおこなう

|

+- spec

| ユニットテスト用ディレクトリ

|

+- test

| |

| +- fixtures

| | テストでロードされるフィクスチャ

| |

| +- integration

| インテグレーションテスト用ディレクトリ

|

+- vendor

| |

| +- gems

| bundle install された gem パッケージ

|

+- doc

|

+- COPYING

| 本ソフトウェアのライセンス

|

+- ChangeLog

| 更新履歴

|

+- PLUGINS.ja

| プラグインについてのドキュメント

|

+- README.ja

本ドキュメント

==============

開発に参加する

==============

リポジトリ

https://github.com/automaticruby/automaticruby

課題

https://github.com/automaticruby/automaticruby/issues

RubyForge

http://rubyforge.org/projects/automatic/

RubyGems.org

https://rubygems.org/gems/automatic

CI

http://jenkins.id774.net/jenkins/

プラグインを新しく作ったり、あるいはフレームワークを

改善してくれるなら、以下の手順で開発に参加できる。

1. GitHub でリポジトリをフォークする。

2. プラグインを新しく作ったりする。

3. Pull Request を送信する。

なんらかの貢献があった場合、少しの修正を迅速におこなうために

コミット権を配布する。

================

コーディング規約

================

コーディング規約は 1 ファイルの中で完結するべきである

末尾のスペースは除去

{} は 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|

mod = plugin.module

load_plugin(mod)

klass = Automatic::Plugin.const_get(mod)

pipeline = klass.new(plugin.config, pipeline).run

}

プラグイン間での連続した pipeline の受け渡しにより

処理要素を直列に連結し、あるプラグインの出力が次の

プラグインの入力となるパイプライン処理を実現する。

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

pipeline の中身はフィードの配列である。

====================

プラグインの実装規約

====================

プラグインのコンストラクタは YAML.load によってロード

されたハッシュの配列、及びパイプラインと呼ばれる

インスタンス変数のオブジェクトを引数に取る。

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

def initialize(config, pipeline=[])

@config = config

@pipeline = pipeline

end

インスタンスメソッド run が自動的に呼ばれる。

戻り値はインスタンス変数 @pipeline に渡り、レシピで

定義された次のプラグインに引き渡される。

複数のプラグインを組み合わせるとき @pipeline の

データフォーマットが一致している必要がある。

たとえば先行するプラグインが RSS フィードを返す場合は

RSS フィードを処理する。 HTML を返す場合は HTML を処理

するコードを記述する必要がある。

==============

ユニットテスト

==============

ユニットテストは RSpec でおこなう。

プラグインのテストは、引数となるパイプラインを渡し

戻り値を検査する。

========

結合試験

========

test/integration 配下に複数のプラグインを結合して

テストをおこなうためのレシピを置く。

リポジトリにチェックインする前に必ず ruby 1.9 で

以下のコマンドを実施し、テストビルドを実施する。

$ script/build

これによりすべての RSpec によるテスト、及び

結合試験が実施される。途中で失敗することなくすべて

のテストが成功したことを確認した上でリポジトリに

チェックインする。さもなくば CI が失敗するだろう。

========================

継続的インテグレーション

========================

CI は Jenkins でおこなう。

http://jenkins.id774.net/jenkins/

================

プラグインの説明

================

doc/PLUGINS.ja を参照

============

サブコマンド

============

automatic コマンドから補助的なツールをサブコマンド経由で実行できる。

[書式]

$ automatic

ヘルプ及びサブコマンドの一覧を表示する

$ automatic scaffold

ホームディレクトリに ~/.automatic ディレクトリを生成する。

この操作により ~/.automatic の下に plugins, db, config, assets

ディレクトリが生成される。

これらは本体のそれぞれのディレクトリよりも優先される。

$ automatic unscaffold

ホームディレクトリの ~/.automatic ディレクトリを削除する。

$ automatic autodiscovery <url>

対象の URL をオートディスカバリで探知しフィードの URL を返す。

(例)

$ automatic autodiscovery http://blog.id774.net/post

["http://blog.id774.net/post/feed/", "http://blog.id774.net/post/comments/feed/"]

$ automatic opmlparser <opml path>

OPML ファイルを解析し URL を出力する。

(例)

$ automatic opmlparser opml.xml > feeds.txt

$ automatic feedparser <url>

フィードを解析して内容を返す。

$ automatic inspect <url>

対象の URL をオートディスカバリで探知する。

さらに最初のフィードの URL を解析して内容を返す。

目的のサイトのフィードを購読可能かどうか検証するのに使う。

$ automatic log <level> <message>

Automatic Ruby のログ形式でメッセージを出力する。

========

更新履歴

========

doc/ChangeLog を参照

====

TODO

====

GitHub の issues を参照

https://github.com/automaticruby/automaticruby/issues

========

動作環境

========

Ruby 1.9 以降

Gemfile に記述された gem パッケージに依存

========

注意事項

========

過剰なスクレイピング等を避け、常識の範囲の利用に留める。

本ソフトウェアは GPLv3 ライセンスである。