Thor はじめに Getting Started

始めるにあたり, thorについて知らなければならない2,3のことがある. 例えば, タスクをロードするためのファイル命名規則や, 通常はコマンドラインで thor コマンドによってあなたのスクリプトを呼び出すことである (これは他にも方法がある)

There are a few things that you need to know about thor to get started. For example, it uses a file name convention to load tasks, and you typically call your scripts via the thor command line, though this is not the only option.

ファイル名 File Names

thorタスクをひとつ作るには, 最初に, 拡張子 .thor をもつファイル (Thorfile というファイルでもよい) がひとつ必要となる. このファイルには, thorが提供する機能を含んだ任意の標準のRubyコードを, 入れることができる. thor コマンドライン・ツールが実行されると, もろもろの .thor ファイルを探し, ロードして, あなたが作成したタスク群が使用できるようになる.

To create a thor task, the first thing you need is a file ending with the .thor extension (a file named Thorfile works as well). This file can contain any standard ruby code, including the functionality provided by thor. When the thor command line tool is run, it will look for .thor files and load them up, making your tasks available.

シンプルな例 A Simple Example

test.thor というファイルを作って, 以下のコードを書く:
Create a file named test.thor and place the following code in it

class Test < Thor
  desc "example", "an example task"
  def example
    puts "I'm a thor task!"
  end
end

あなたは一旦これを作りさえすれば, コマンドラインから thor list を実行することで, 以下のような出力が得られる:

Once you have this created, you can run thor list from the command line and you should see the following output:

test
----
thor test:example  # an example task

さあ, コマンドラインから thor test:example を実行しよう. I'm a thor task! という出力が得られるはずだ.

Now run thor test:example from the command line. You should see I'm a thor task! output to the command line.

サンプルを深く理解する Breaking Down The Sample

このタスクには, 何が起きているかを理解するために試せる, 5,6個のパーツがある.

There are several parts of this task that can be examined to understand what is happening.

最初に, クラス名はタスクの名前空間として使われる. Thorは クラス名を名前空間に変えるために, もろもろのRuby標準命名規則を使う. 例えば, あなたがクラス名を FooBar に変えた場合, タスクはこのとき foo_bar:example としてリストされる.

First, the class name is used as the namespace for the task. Thor uses some standard ruby conventions to turn the class name into a namespace. If you change the class name to FooBar, for example, your task would now be listed as foo_bar:example.

次に, desc メソッドが使われているが, これはわれわれが作成しようとしているタスクを記述するのためのものだ. descメソッドには ふたつのパラメータ が ある. 第1のパラメータは 定義するタスク(メソッド)の名称を明示するためのもので, 任意のパラメータ群をそのメソッドに与えられる. 第2のパラメータは プレーンテキストで, このタスクが何をするものなのか説明するためのものだ.

Next, the desc method call is used to describe the task that we are creating. There are two parameters to the desc method. The first parameter should state the name of the task (the method) and any parameters that are provided to the method. The second option should be a plain text description of what this task does.

最後は, example メソッドそのものだ. Thorはこのメソッド名を実際のタスク名として使用する. それゆえ, exampleメソッドを widget にリネームした場合, タスクは test:widget としてリストされることになる.

Last, the example method itself. Thor uses this method name as the actual task name. Therefore, when you rename the example method to widget, you end up with a task listing of test:widget.

タスクのパラメータ Task Parameters

以下のthorタスクは, パラメータをひとつメソッドに加えることによって, タスクにパラメータをひとつ定義する:
The following thor task defines one parameter on the task by adding a parameter to the method:

class Test < Thor
  desc "example FILE", "an example task that does something with a file"
  def example(file)
    puts "You supplied the file: #{file}"
  end
end

descの第1パラメータを’FILE’という語を含むものにアップデートしたことに, 注意してほしい. 前述のように, タスクの記述にはタスク・パラメータを任意に含めてよい. これはエンドユーザが使いやすいようにヘルプ・テキストを提供するものだ.

Note that the description has been updated to include the word ‘FILE’ in the first parameter. As stated previously, you should include the name of any required task parameters in the task description. This is used to produce help text that is useful to the end user.

thor help test:example を実行してtest:exampleタスクのヘルプテキストを見てみると, 以下のような出力を見れるだろう:

Run thor help test:example to see the help text for the test:example task and you will see the following output:

Usage:
  thor test:example FILE

an example task that does something with a file

これはそのタスクにFILEパラメータが必要であることを示す.
This indicated the requirement of a FILE parameter for the task.

今 thor test:example my_file.rb でタスク自体を実行した場合, You supplied the file: my_file.rb と目にするはずだ.
Now when you run the task itself, with thor test:example my_file.rb you should see You supplied the file: my_file.rb.

もしファイル名を与えずにスクリプトを実行すれば, ひとつ与える必要があるという "example" was called incorrectly. Call as "thor test:example FILE". のメッセージを目にするだろう.
If you run the script without a file supplied, you’ll see a message saying you need to supply one: "example" was called incorrectly. Call as "thor test:example FILE".

タスクのオプション Options For A Task

Thorはまた, ひとつのタスクに対して, もろもろの名前付けしたオプションを与えることもできる. いくつかのメソッドがこれを行っており, より詳細については [[method options]] のWikiページを参照してほしい.
Thor also lets you provide named options for a task. There are several methods of doing this, and more detail can be found on the [[method options]] wiki page.

あなたのtest.thorファイルに以下を書いてみよ:
Put the following into your test.thor file:

class Test < Thor
  desc "example FILE", "an example task"
  method_option :delete, :aliases => "-d", :desc => "Delete the file after parsing it"
  def example(file)
    puts "You supplied the file: #{file}"
    delete_file = options[:delete]
    if delete_file
      puts "You specified that you would like to delete #{file}"
    else
      puts "You do not want to delete #{file}"
    end
  end
end

この例では, 5,6個のパラメータとともに method_option がひとつ指定されている. 第1のパラメータはオプションのフルネームだ. これはコマンドライン上で —オプションひとつに変換される. このケースでは --delete だ. :aliases オプションは, このオプションのために, ひとつかそれ以上の省略形のエイリアス群を提供する. このケースでは -d が省略形として提供される. 最後に :desc でこのオプションの説明を与えた.

In this example, a method_option has been supplied with several parameters. The first parameter is the full name of the option. this is translated into a — option on the command line. In this case, --delete. The :aliases option allows you to provide one or more short-hand aliases for the option. In this case, -d has been provided as a short-hand alias. And last, a description of the option has been provided.

thor help test:example を実行すると, 以下の出力がみれる:
Run thor help test:example and you will see the following output:

Usage:
  thor test:example FILE

Options:
  -d, [--delete=DELETE]  # Delete the file after parsing it

an example task

今, このタスクを —delete オプション有りでも無しでも実行できる.
Now you can run the task with or without the delete option.

thor test:example my_file.rb を実行すると, 以下のようになる:
Run thor test:example my_file.rb, you will see this output:

You supplied the file: my_file.rb
You do not want to delete my_file.rb

thor test:example my_file.rb --delete もしくは thor test:example my_file.rb -d で実行してみると:
Run thor test:example my_file.rb --delete or thor test:example my_file.rb -d and you will see:

You supplied the file: my_file.rb
You specified that you would like to delete my_file.rb

作成したタスク・メソッドひとつにつき, 多くのメソッド・オプションを必要なだけ指定できる. これらをメソッド名に対して積み上げていくだけで, タスク内に現れるだろう.

You can specify as many method options as you need, for a given task method. Just keep piling them on to the method name and they will show up in the task.

ハサミを持って突っ走る Running With Scissors

ここでの諸例は単純で不自然だったが, 今はなにかしら, 実際のthorタスクの機能を使ってみることができるだろう. thorのさまざまなオプションや能力のドキュメントについては, 他のwikiページ (訳注: githubにあるThorのWikiのこと. この訳文群のこと) もチェックしてみること.
Though the examples here are simple and contrived, you should be able to get started with some real functionality for your thor tasks, now. Be sure to check the other wiki pages for documentation on the various options and capabilities of thor.

​