仕事でRuby on Railsを使っていて、Rakeタスクもよく使っている中で、
実行例もコマンドで確認できるようにした話です。
Rakeタスクとは
Rubyで書かれたコードをタスクとして作成しておき、必要に応じて呼び出し実行できる機能です。
実行コマンド忘れる問題
Rakeタスクの種類が増えてくると、Rakeコマンドで実行する際に、正しいコマンド名や引数の渡し方などを毎回忘れてしまうという問題が出てきました。
namespace :hoge do
# 実行例： bundle exec rake 'hoge:fuga[1, 10, 20, 30]'
desc 'ほげほげする'
task :fuga, %i[hoge_id] => :environment do |_, args|
# 処理
end
end
こんな感じでコード内にコメントで実行例が記述されていたりはしたのですが、毎回Rakeファイルのコードを探すのが煩わしく、実行例もCLI上で確認したいという気持ちが湧いてきました。
そういえばdescって何のためにあるの？
新しくRakeタスクを書くときは、なんとなく他に習って何をするタスクかをdescに記述していたのですが、
コード上で直接読む以外に活用したことがありませんでした。
何かしら用途があるだろうとRakeコマンドのヘルプを表示させてみるとこんなオプションを発見しました。
-D, --describe [PATTERN] Describe the tasks (matching optional PATTERN), then exit.
つまり
bundle exec rake -D hoge
というコマンドを打つと
rake hoge:fuga[hoge_id]
ほげする
というように[PATTERN]名が部分一致したタスクについて、タスク名とともにdescで添えた説明の一覧が表示されます。
他にも-Tオプションでdescを記述しているタスク一覧を表示できたりします。
descに実行例も書けばコマンドで確認できるじゃん！
ということでdescに実行例も書けば-Dオプションで表示させられることがわかりました。
descを複数行表示させるには?
タスク自体の説明と実行例など、複数行で表示させるにはどうするのが良いのでしょうか。
試み1: descを複数書く -> 🙅
namespace :hoge do
desc 'ほげほげする'
desc "実行例： bundle exec rake 'hoge:fuga[1, 10, 20, 30]'"
task :fuga, %i[hoge_id] => :environment do |_, args|
# 処理
end
end
実行結果
rake hoge:fuga[hoge_id]
実行例: bundle exec rake 'hoge:fuga[1, 10, 20, 30]'
こんな感じで2つ以上descを記述した場合は後に書いたdescで上書きされてしまいます。
試み2: 改行コード\nでつなぐ -> 🤔
namespace :hoge do
desc "ほげほげする\n実行例： bundle exec rake 'hoge:fuga[1, 10, 20, 30]'"
task :fuga, %i[hoge_id] => :environment do |_, args|
# 処理
end
end
実行結果
rake hoge:fuga[hoge_id]
ほげする
実行例: bundle exec rake 'hoge:fuga[1, 10, 20, 30]'
これならうまくいきます。けどコードは読みにくくなりますね。
試み3: ヒアドキュメントを使う -> 🙆
Rubyには複数行の文字列を定義する方法として、ヒアドキュメントという記述方法があります。
namespace :hoge do
desc <<~DESC
ほげする
実行例: bundle exec rake 'hoge:fuga[1, 10, 20, 30]'
DESC
task :fuga, %i[hoge_id] => :environment do |_, args|
# 処理
end
end
実行結果
rake hoge:fuga[hoge_id]
ほげする
実行例: bundle exec rake 'hoge:fuga[1, 10, 20, 30]'
開始ラベルを<<~識別子とすることで、最もインデントが少ない行を基準に、
全ての行の先頭から空白を取り除いてくれます。
これによりコード上のインデントを無視できます。
これならコードも読みやすく、説明を追加したいときも拡張しやすいですね！