訳注

このドキュメントは http://twill.idyll.org にある

• Language reference -- the twill scripting language.

を独自に邦訳したものです。原著が含まれる twill の著作権は以下の通りです。この邦訳は、原著と同じくMIT license の下に公開するものとします。

Authors and License

The main author of twill is C. Titus Brown, titus@idyll.org. A number of people have contributed bug reports and code since the first release; they are acknowledged below.
The twill source code is Copyright (C) 2005, 2006, 2007 C. Titus Brown. twill is available under the MIT license.
pyparsing, mechanize, and BeautifulSoup are included with twill for convenience, but are under their own licenses.

twill言語リファレンス

これらのコマンドはtwillの組み込みコマンドです。'＃' 以降のすべてのテキストは、コメントとして無視されます。ただし、'＃'が引用符で囲まれた文字列中に現れる場合はコメントにはなりません。

ブラウジング

go <url> -- 指定の URL を訪れます. Pythonの関数は、リダイレクトをすべてたどり、最後の訪問したURLを返します。
back -- 以前のURLに戻ります.Pythonの関数は、もしURLがあればそのURLを返します.
reload -- 現在のURLをリロードします.Pythonの関数は、もしURLがあればそのURLを返します.
follow <link name> -- 指定されたリンクをたどります. Pythonの関数は、リダイレクトをすべてたどり、最後の訪問したURLを返します。

アサーション

code <code> -- 最後にロードされたページが、このHTTPステータスであることを確認します. 例えばcode 200が成立すれば、ページがただしくロードされていることになります。
find <regexp> -- ページに、この正規表現が含まれていることを確認します. 変数_ match__は、最初に一致したサブグループに設定されます。（サブグループが指定されていない場合、マッチした文字列全体です。）Pythonから呼び出されたときは、マッチした文字列が返されます。
notfind <regexp> -- ページにこの正規表現が含まれていないことを確認します。
url <regexp> -- 現在のURLが与えられた正規表現にマッチすることを確認します。 変数_ match__は、最初に一致したサブグループに設定されます。（サブグループが指定されていない場合、マッチした文字列全体です。）Pythonから呼び出された場合、マッチした文字列が返されます。
title <regexp> -- このページのタイトルがこの正規表現にマッチすることを確認します。変数_ match__は、最初に一致したサブグループに設定されます。（サブグループが指定されていない場合、マッチした文字列全体です。）Pythonから呼び出された場合、マッチした文字列が返されます。

表示

echo <string> -- 文字列を画面に表示します。
info -- 現在のページに関する情報を表示します。
redirect_output <filename> -- -指定したファイルにtwillからのすべての出力を追加します。
reset_output -出力を画面に表示します。
save_html [<filename>] -- 現在のページのHTMLをファイルに保存します。ファイル名が指定されていない場合、URLからファイル名が決められます。
show -- 現在のページのHTMLを表示します。 Pythonから呼び出された場合、この関数は、HTMLを含む文字列を返します。
showlinks -現在のページのすべてのリンクを表示します。Pythonから呼び出された場合、この関数を使用すると、リンクオブジェクトのリストを返します。
showforms -現在のページのすべてのフォームを表示します。Pythonから呼び出された場合、この関数は、フォームのリストを返します。
showhistory -ブラウザの履歴を表示します。Pythonから呼び出された場合、この関数は、履歴を返します。

フォーム

submit [<n>] --n番目の送信ボタンをクリックします。指定がない場合は最後にクリックした送信ボタンを使用します。なにもクリックしていないときは、フォームの最初の送信ボタンを使用します。詳しくは参照フォーム処理の詳細を参照。
formvalue <formnum> <fieldname> <value> --- 指定のフォームのフィールドに値を設定します。読み取り専用のフォームウィジェット/コントロールを操作したときは、値は変更されませんが、submitを使用するときのために記憶されることがあります。'config'コマンドで、デフォルトの動作を変更することができます。詳しくは、'config'とフォーム処理の詳細の'formvalue'コマンドを参照してください。
リストウィジェットでは、 'formvalue <formnum> <fieldname> +値'、または 'formvalue <formnum> <fieldname> -値' で、値の選択を、設定あるいは解除することができます。
fv - 'formvalue "の略称。
formaction <formnum> <action> -- にフォームアクションURLを指定されたURLに変更します。
fa - 'formaction'の略。
formclear -フォーム内のすべての値をクリアします。
formfile <formspec> <fieldspec> <filename> [ <content_type> ] -- アップロード対象のファイルを指定します。

クッキー

save_cookies <filename> -現在のクッキーをファイルに保存します。
load_cookies <filename> -ファイルからクッキーをロードします。
clear_cookies -現在のすべてのクッキーをクリアにします。
show_cookies -現在のクッキーを表示します。

デバッグ

debug <what> <level> -デバッグ/のトレースをオンまたはオフにする。

最初の引数は、'http'、'equiv-refresh'、'commands' のいずれかです。'http'ではHTTPヘッダーの表示、'equiv-refresh' はHTTP EQUIV-REFRESHヘッダをテストするか、'commands'は twill コマンドの表示を変更します。二番目の引数は、'0'がオフ、'1'がオンです。

変数の扱い

setglobal <name> <value>の -変数<name>を値<value>でグローバル辞書にセットします。値は '$name'で参照することができます。
setlocal <name><value> -変数<name>を値<value>でローカル辞書にセットします。値は '$name'で参照することができます。
ローカル辞書はファイル固別のものですが、グローバル辞書はモジュール全体ですべてのコマンドに使用されます。ローカル変数は、グローバル変数を上書きします。
文字列中で${var}のように変数を使用することができます。例えば

setglobal a 1setglobal b 2 fv thisform thatfield "${a}${b}"

その他のコマンド

tidy_ok - このページを'tidy'コマンドで処理して、エラーや警告がなかったことを確認します。 （ tidyはかなり厳密なので、おそらく警告がでるでしょう!）
exit [<code>] -指定された整数コードで終了したかどうかチェックします。'code' のがない場合はデフォルト値 0 でチェックします。
run <command> -指定されたPythonのコマンドを実行します。
runfile <file1> [<file2>... ] -指定されたファイルを実行します。
agent -ブラウザの"User-agent"文字列を設定します。
sleep [<seconds>] -指定された秒数だけスリープします。デフォルトは1秒。
reset_browser -ブラウザをリセットします。
extend_with <module> - Pythonモジュールからコマンドをimportします。これはPythonでのfrom <module> import *のように動作します。extmoduleの関数fnが、コマンドfnとして使用できるようになります。examples/extend_example.py参照してください。
getinput <prompt> -キーボード入力を取得し__ input__に保存します。Pythonから呼び出された場合、この関数は、入力値を返します。
getPasswordに <prompt> - エコーなしでキーボード入力を取得し__password__に保存します。Pythonから呼び出された場合、この関数は、入力値を返します。
add_auth <realm> <uri> <user> <password> -指定されたrealm/uri の組に対する、HTTP基本認証情報を追加します。 例:

add_auth IdyllStuff http://www.idyll.org/ titus test

http://www.idyll.org/でレルム"IdyllStuff" からの認証要求に、ユーザ名 "titus"、パスワード "test"を返すようにします。'with_default_realm' オプションがTrueに設定されている場合、 'realm' を無視します。
config [<key> [<value>]] - オプションの表示または設定をします。
add_extra_headers <name> <value> - HTTPリクエストに追加するHTTPヘッダーを指定します。
show_extra_headers -HTTPリクエストに追加するヘッダを表示します。
clear_extra_headers -add_extra_headers で指定した追加ヘッダーをクリアします。

特殊な変数

__input__ -最後に実行したgetinputの結果。
__match__ -最後に実行したfind 、title 、URLでマッチしたテキスト。
__password__ - 最後に実行したgetPasswordの値。
__url__ -現在のURL。

フォーム処理の詳細

formvalue（またはfv）とsubmitコマンドには暗黙の依存関係があります。状況によっては、formvalueがどのフォームフィールドを指定したのか、あるいはどのフォームのsubmitフィールドが"クリック"されたのか、フィールド名に基づいて選択するつもりかを正確に判断することは、悩ましいことです。

ここではformvalueとsubmitがどのように働くかを擬似コードで示します。（関数twill.commands.browser.get_form）

for each form on page: 

  if 指定の正規表現パタンがフォームの名前とマッチした, フォームを選択する 

if フォームの名前がない, 整数に変換してみる & 変換結果をN とすれば、N - 1 が、ページ上のフォームのリストの添字となる (たとえば、フォーム 1 はページにある最初のフォーム).

ここではformvalueとsubmitがどのようにフォームフィールドを扱うのかを擬似コードで示します（関数twill.commands.browser.get_form_field）

現在のフォームから、コントロール名がfieldnameと完全に一致するものを検索します; 

ひとつだけマッチしたとき（ユニーク）、これを選択します。 

マッチしなかった場合、フィールド名が数値に変換できるときは、インデックスとして使用します。 

マッチしなかった場合は、現在のフォームから正規表現でfieldnameに一致するコントロール名を検索します;ひとつだけマッチしたとき（ユニーク）、これを選択します。 

*なお*一致がなければ、submitボタンの値と完全一致するものを探します。 

ひとつだけマッチしたとき（ユニーク）、これを選択します。

submitに関する擬似コードは次のとおりです。

フォームがまだformvalueによって選択されて_いない_場合:  ページ上のフォームがひとつだけであれば、それを選択します。  そうでないときは、failです。 フィールドが、明示的に名前で指定されていない場合:  submitボタンがformvalueを指定して"クリック"された場合は、それを使用します。 

  さもなくば、フォーム上の最初のsubmitボタンを使用します。

そうでなければ:  formvalueと同じ規則を使用してフィールドを見つけます 

最後に、ボタンが選択されている場合は、それを使用してsubmitします。そうでない場合は、ボタンを使用せずにsubmitします。