goohub – CLI filter for Google Calendar

Summary

goohubは，Google Calendarとの認証を行い，予定の取得や送信を行うCLIツールである． また，Google Calendar上の予定をユーザが指定したルールによって予定を書き換え，特定のメディア(Google Calendar, Slack, メール)に送信する機能をもつ．

Requirements

• Ruby 2.1.5 ~
• bundler 1.15.14 ~

Rubyとbundlerのインストールについては，以下を参考にすること．

• Rubyのインストール方法
• bundler のインストール方法

$ gem install bundler
$ bundler -v # check bundler version

Installation and Setup

1. Clone code

   $ git clone git@github.com:kjtbw/goohub.git
       

2. Install gems

   $ bundle install --path vendor/bundle
       

3. Initialize

   $ bundle exec ruby exe/goohub init
       

   この際，GoogleCalendarAPIの， client_id と， client_secret が必要になる．

   1. client_id と， client_secret の入手方法に関するドキュメント
   2. Google API console
4. Check goohub version

   $ bundle exec ruby exe/goohub version
       

5. Authorize

   $ bundle exec ruby exe/goohub auth
       

6. Check authorize

   $ bundle exec ruby exe/goohub calendars
       

   認証に成功した場合，GoogleCalendarで閲覧できるカレンダの一覧が表示される．

7. Write Settings

   $ cp settings.yml.sample settings.yml
   $ vim settings.yml
       

   settings.ymlでは，以下の項目を設定する．

項目名	種別	説明
db_path	必須	goohubのDB(json形式)を配置する場所を記述する．
exec_funnel	任意(funnelを利用する場合は必須)	実行するfunnel(ルール)の名前
slack_incoming_webhook_url	任意(予定の共有先でSlackを指定する場合は必須)	Slackの incoming_webhook で用いるURL，詳細は 公式のドキュメント を見ること
mail_address	任意(予定の共有先でメールアドレスを指定する場合は必須)	アクションで予定を共有したいメールアドレス
mail_password	任意(予定の共有先でメールアドレスを指定する場合は必須)	アクションで予定を共有したいメールアドレスのパスワード

Usage

Command Name	Description
goohub auth	GoogleCalendarAPIの認証を行う．
goohub calendars	カレンダの一覧を表示する．
goohub configuration	現在の設定を確認する．
goohub events CALENDAR_ID START_MONTH ( END_MONTH )	CALINDAR_IDのカレンダについて，START_MONTHからEND_MONTHまでの期間の予定を取得する．
goohub get_event CALENDAR_ID EVENT_ID	CALENDAR_IDのカレンダ上のEVENT_IDの予定を取得する．
goohub help [COMMAND]	COMMANDという名前のコマンドの詳細を表示する．
goohub init	初期設定を行う．
goohub post_event CALENDAR_ID TITLE START END	CALENDAR_IDのカレンダに予定を追加する．(予定名:TITLE, 開始日時:START, 終了日時:END)
goohub version	goohubのバージョンを表示する．
goohub read TYPE	TYPE(funnels, filters, actions, outlets)で指定した種類のDBを読む
goohub write TYPE NAME QUERY	TYPE(funnels, filters, actions, outlets)で指定した種類について，DBに追記する．
goohub share CALENDAR_ID EVENT_ID	CALENDAR_ID上のEVENT_IDの予定を，settings.ymlの`exec_funnel`で指定したfunnelに従って，共有する．
goohub server CALENDAR_ID START_MONTH (END_MONTH)	CALENDAR_ID上の，START_MONTHからEND_MONTHの期間について，まだDBに登録されていない予定を出力する
goohub sinatra	GUIシステム用のHTTPサーバをlocalhost:4567に立てる．

なお， sinatra コマンドで立てたHTTPサーバのAPIは，wiki に示す．

以下のコマンドで，コマンドの一覧を確認できる．

bundle exec ruby exe/goohub

以下のコマンドで，コマンドの詳細を確認できる．

$ bundle exec ruby exe/goohub help [COMMAND]

About Rules(funnels, filters, actions, and outlets)

Summary

goohubは，Google Calendar上の予定をユーザが指定したルールによって予定を書き換え，特定のメディア(Google Calendar, Slack, メール)に送信する機能がある． この機能では，ユーザが指定するルールを以下のデータ構造で定義する．

variable name	summary
funnels	以下のfilters, actions, outletsを指定する識別子をもつ．
filters	どの予定を編集するかを表す
actions	予定をどのように書き換えるかを表す
outlets	予定を公開するアプリケーションの種類を表す

また，各変数について，条件の記述にはDSLを用いる． DSLの文法は，wiki に記述してある．

Usage

1. Make your funnels, filters, actions, and outlets

   　$ bundle exec ruby exe/goohub write funnels <name> <filter_name> --action-name=<action_name> --outlet-name=<outlet_name>
   　$ bundle exec ruby exe/goohub write filters <name> <condition>
   　$ bundle exec ruby exe/goohub write actions <name> <modifier>
   　$ bundle exec ruby exe/goohub write outlets <name> <informant>
       

2. Set exec_funnel in settings.yml

   exec_funnel:
      - <your_funnel_name>
       

3. Check your funnels

   $ bundle exec ruby exe/goohub share CALENDAR_ID EVENT_ID
       

   コマンドが成功すれば，funnelで指定した予定共有が行われる．

Automatic execution of funnel

server_test.sh を用いることで，カレンダの更新に合わせて自動でfunnelを適用できる． server_test.sh は以下のように用いる．

$ chmod +x server_test.sh
$ ./server_test.sh -h # server_test.shの詳細を確認
$ ./server_test.sh -ep CALENDAR_ID

このプログラムを実行することで，CALENDAR_IDで指定したカレンダについて，予定の更新があれば，更新された予定にfunnelを適用できる．

About GUI

goohubの操作をGUIで行うためのシステムとして，goohub-guiがある． goohub-guiを利用することで，ルール(funnel, filter, action, outlet)の作成，ルールの閲覧，カレンダの閲覧をGUI から行える． goohub-guiの詳細について，goohub-guiのREADME に示す．

For Developers

goohubのディレクトリ構成を以下に示す．

.
├── Gemfile
├── Gemfile.lock
├── LICENSE.txt
├── README.org
├── Rakefile
├── attic
│   ├── er.png
│   └── er.uml
├── bin
│   ├── console
│   └── setup
├── db
├── exe
│   └── goohub
├── goohub.gemspec
├── lib
│   ├── goohub
│   │   ├── action.rb
│   │   ├── client.rb
│   │   ├── command
│   │   ├── command.rb
│   │   ├── config.rb
│   │   ├── datastore
│   │   ├── datastore.rb
│   │   ├── date_frame.rb
│   │   ├── expression.rb
│   │   ├── filter.rb
│   │   ├── funnel.rb
│   │   ├── outlet.rb
│   │   ├── parser.rb
│   │   ├── resource
│   │   ├── resource.rb
│   │   ├── templates
│   │   └── version.rb
│   └── goohub.rb
├── server_test.sh
├── settings.yml.sample
├── spec
│   ├── goohub_spec.rb
│   └── spec_helper.rb
├── tests
│   ├── action_test.sh
│   ├── dsl
│   │   ├── dsl_test.rb
│   │   ├── expression.rb
│   │   └── parser.rb
│   ├── filter_test.sh
│   └── server_test.sh

各ファイルやディレクトリの説明を以下に示す．

ディレクトリ/ファイル名	説明
Gemfile	gemの一覧
Gemfile.lock	依存関係もすべて含めたgemの一覧
LICENSE.txt	ライセンスに関する文書
READEM.org	このファイル
Rakefile	Rakeの処理をかいたファイル
attic/	雑多なファイル(現在はER図)置き場
db/	goohubのDB(json形式)置き場
exe/	実行ファイル置き場
goohub.gemspec	gem goohub に関する情報が書かれたファイル
lib/	goohubのライブラリ置き場，クラス定義や，コマンドに関する記述はここ
server_test.sh	goohubをサーバ化するスクリプト
settings.yml.sample	設定ファイルのサンプル
tests/	テスト用のスクリプト置き場

開発者は，基本的に， lib 以下に，クラスやコマンドを追記する形で開発すると考えられる． いかに， lib 以下の詳細な説明を示す．

ディレクトリ/ファイル名	説明
lib/goohub.rb	クラスのloadを行う，クラスを追加した場合は，このファイルを更新すること
lib/goohub/	クラスやコマンドの定義がされたファイル置き場
lib/goohub/*.rb	クラスの定義がされたファイル
lib/goohub/command/	コマンドの定義がされたファイル置き場
lib/goohub/datastore/	DBに関するクラスの定義がされたファイル置き場
lib/goohub/resource/	resource(calendar, event)の定義がされたファイル置き場
lib/goohub/templetes/	設定ファイルのテンプレートの定義がされたファイル置き場

また，各コマンドにおいて，Google カレンダーとの認証を行なったオブジェクトは， @client なので，これを利用すると，簡単に Googel Calendar API を利用できる．