NAME

Tripletail - Tripletail, Framework for Japanese Web Application

NAME (ja)

Tripletail - Tripletail, 日本語向けウェブアプリケーションフレームワーク

SYNOPSIS

use Tripletail qw(tl.ini);

$TL->startCgi(
    -main => \&main,
);

sub main {
    my $t = $TL->newTemplate('index.html');

    $t->flush;
}

DESCRIPTION

use

Tripletail では、ライブラリの各種設定は Ini ファイルに置かれる。

実行が開始されるスクリプトの先頭で、次のように引数として Ini ファイルの位置を渡す。するとグローバル変数 $TL がエクスポートされる。 Ini ファイル指定は必須である。

use Tripletail qw(/home/www/ini/tl.ini);

他のファイルから $TL 変数を使う場合は、そのパッケージ内で use Tripletail; のように引数無しで use する。二度目以降の use で Ini ファイルの位置を指定しようとした場合はエラーとなる。

設定ファイルの設定値のうち、一部の値を特定の CGI で変更したい場合は、 次のように2つめ以降引数に特化指定をすることが出来る。

use Tripletail qw(/home/www/ini/tl.ini golduser);

特化指定を行った場合、ライブラリ内で Ini ファイルを参照する際に、 まず「グループ名 + ":" + 特化指定値」のグループで検索を行う。 結果がなかった場合は、通常のグループ名の指定値が使用される。

また、サーバの IP やリモートの IP により使用するグループを変更することも出来る。それぞれ 「グループ名 + "@sever" + 使用するサーバのマスク値」 「グループ名 + "@remote" + 使用するリモートのマスク値」 といった書式となる。

但し、スクリプトで起動した場合、リモートの IP 指定している項目は全て無視される。 サーバの IP 指定している項目の場合、 hostname -i で取得した値でマッチされる。

使用するサーバのマスク値と、リモートのマスク値に関しては、Ini中の[HOST]グループに設定する。例えば次のようになる。

[HOST]
Debughost = 192.168.10.0/24
Testuser = 192.168.11.5 192.168.11.50
[TL@server:Debughost]
logdir = /home/tl/logs
errormail = tl@example.org
[TL@server:Debughost]
logdir = /home/tl/logs/register

マスクは空白で区切って複数個指定する事が可能。

但し、[HOST]には特化指定は利用できない。

特化指定を二種、もしくは、三種を組み合わせて利用することも出来るが、その場合の順序は「グループ名 + ":" + 特化指定値 + "@sever" + 使用するサーバのマスク値 + "@remote" + 使用するリモートのマスク値」で固定であり、その他の並びで指定することは出来ない。

特化指定は複数行うことができ、その場合は最初の方に書いたものほど優先的に使用される。

特化指定

特化指定の具体的例を示す

[HOST]
Debughost = 192.168.10.0/24
Testuser = 192.168.11.5 192.168.11.50
[TL:register@server:Debughost]
logdir = /home/tl/logs/register/debug
[TL@server:Debughost]
logdir = /home/tl/logs
errormail = tl@example.org
[TL]
logdir = /home/tl/logs
[TL:register]
logdir = /home/tl/logs/register
[Debug@remote:Testuser]
enable_debug=1

という tl.ini が存在している場合に

use Tripletail qw(/home/www/ini/tl.ini register);

で、起動した場合、次のような動作になる。

プログラムが動いているサーバが、192.168.10.0/24であり、アクセスした箇所の IP が192.168.11.5か192.168.11.50である場合

[TL]
logdir = /home/tl/logs/register/debug
errormail = tl@example.org
[Debug]
enable_debug=1

プログラムが動いているサーバが、192.168.10.0/24であり、アクセスした箇所の IP が192.168.11.5か192.168.11.50では無い場合

[TL]
logdir = /home/tl/logs/register

また、

use Tripletail qw(/home/www/ini/tl.ini);

で、起動した場合、次のような動作になる。

プログラムが動いているサーバが、192.168.10.0/24であり、アクセスした箇所の IP が192.168.11.5か192.168.11.50である場合

[TL]
logdir = /home/tl/logs/debug
errormail = tl@example.org
[Debug]
enable_debug=1

プログラムが動いているサーバが、192.168.10.0/24であり、アクセスした箇所の IP が192.168.11.5か192.168.11.50では無い場合

[TL]
logdir = /home/tl/logs

$TL とは別の名前でインポートする

以下のようにする事で $TL とは別の名前でインポートする事ができる。この例では $TL ではなく $TL2 がインポートされ、$TL の代わりに使う事ができる:

use Tripletail qw($TL2 /home/www/ini/tl.ini);

$TL2->startCgi(...);

二度目以降の use でも同様に変数名の指定が可能:

use Tripletail qw($TL2);

複数個のパッケージから Tripletail を用いる場合に、必ずしも全てのパッケージでこの変数名を揃える必要は無い。 例えばあるパッケージで $TL を用い、別のパッケージでは $TL2 を用いたとしても問題は起こらない。

携帯向け設定

以下のように、Tripletail::InputFilter::MobileHTML 入力フィルタと Tripletail::Filter::MobileHTML 出力フィルタを利用することで、 携帯絵文字を含めて扱うことができる。

use Tripletail qw(tl.ini);

# startCgi前に入力フィルタを設定する
$TL->setInputFilter('Tripletail::InputFilter::MobileHTML');
$TL->startCgi(
    -main => \&main,
);

sub main {
    # mainの最初で出力フィルタを設定する
    $TL->setContentFilter('Tripletail::Filter::MobileHTML');
    my $t = $TL->newTemplate('index.html');

    $t->flush;
}

入力された絵文字は、 Unicode のプライベート領域にマップされる。 この文字は、 UTF-8 で4バイトの長さとなるため、DBに保存する場合などには 注意が必要となる。BLOB型など、バイナリ形式で保存すると安全である。

絵文字は出力時に各端末にあわせて変換される。 同じ携帯キャリアであれば元の絵文字に戻され、 他のキャリアであれば Unicode::Japanese の変換マップに従い変換されて出力される。

変換マップで該当する絵文字が無い場合や、PC 向けに出力した場合は「?」に変換される。

テンプレートファイルで絵文字を使う場合は、絵文字コードをバイナリで 埋め込む必要がある。 バイナリで埋め込まれた絵文字は Unicode::Japanese で自動判別される。 sjis-imode (DoCoMo)、sjis-jsky (Softbank)、sjis-au (AU) などが利用できるが、 複数の携帯キャリアの絵文字を混在させることはできない。

キャッシュの利用

Cache::Memcachedがインストールされ、 memcached サーバがある場合に、キャッシュが利用可能となる。

具体例は次の通り

INI ファイルにて、 memcached が動いているサーバを指定する。 [MemCached] servers = localhost:11211

読み込み側例（ページ全体をキャッシュ）

#まず、画面毎にキーを設定する。例のケースではtopという名称を付けている。
#ページャーなどを利用する場合、キーはページ毎に設定する必要がある点を注意する（page-1等にする）
#キーで検索を行い、キャッシュにヒットした場合、時間を比較して304でリダイレクトするか、
#メモリから読み込んで表示する
#printCacheUnlessModifiedでundefが返ってきた後は、printやflushなど出力する操作は不可なため注意する事
return if(!defined($TL->printCacheUnlessModified('top')));
#キャッシュすることを宣言する。なお、宣言はprintCacheUnlessModifiedより後で
#printより前であれば、どの時点で行ってもかまわない
$TL->setCache('top');

#実際のスクリプトを記述し、出力を行う

$TL->print('test code.');

書き込み側例（ページ全体をキャッシュ）

#書き込みを行った場合、そのデータを表示する可能性があるキャッシュを全て削除する
#削除漏れがあると、キャッシュしている内容が表示され、更新されてないように見えるので注意する事。
$TL->deleteCache('top');
$TL->deleteCache('top2');

読み込み側例（ユーザー名等一部に固有の情報を埋め込んでいる場合）

#クッキーデータの取得、クッキーに固有の情報を入れておくと高速に動作出来る
#（DB等から読み込みTripletail::Formクラスにセットしても可）
my $cookiedata = $TL->getCookie->get('TLTEST');
$cookiedata->set('<#NAME>' => $name) if(!$cookiedata->exists('name'));
$cookiedata->set('<#POINT>' => $point) if(!$cookiedata->exists('point'));

#まず、画面毎にキーを設定する。例のケースではtopという名称を付けている。
#固有情報が変更された場合、ブラウザ側のキャッシュ情報をクリアしないと情報が変わらない為、
#固有情報が変更される恐れがある場合は、304によるキャッシュは無効にする必要がある。
#
#固有の情報を置換するための情報をセットすると、キーがそのまま置換される。
#その他の条件はページ全体をキャッシュする場合と同様。
$TL->setCacheFilter($cookiedata);
return if(!defined($TL->printCacheUnlessModified('top','200')));
#キャッシュすることを宣言する。
$TL->setCache('top');

#実際のスクリプトを記述し、出力を行う
#この際、固有の情報の部分に関しては、特殊タグ（文字列）に置換する。特殊タグはどのような形でもかまわないが、
#出力文字列中の全ての同様の特殊タグが変換対象になるため、ユーザーや管理者が任意に変更出来る部分に注意する。
#（エスケープする、その特殊タグが入力された場合エラーにするetc）

$t->setAttr(
  NAME => 'raw',
  POINT => 'raw',
);

$t->expand(
  NAME => '<#NAME>',
  POINT => '<#POINT>',
);


$t->flush;

書き込み側例（ユーザー名等一部に固有の情報を埋め込んでいる場合）

#書き込みを行った場合、そのデータを表示する可能性があるキャッシュを全て削除する
#削除漏れがあると、キャッシュしている内容が必要な為注意が必要。
#必要があれば、固有の文字列を出力用にクッキーなどに書き出したりする。
$TL->getCookie->set(TLTEST => $TL->newForm('<#NAME>' => $CGI->get('name'),'<#POINT>' => 1000));

$TL->deleteCache('top');
$TL->deleteCache('top2');

実行モード

実行モードには次の三つがある。

CGI モード

CGI としてプログラムを動作させるモード。このモードでは $TL->print メソッドや "出力フィルタ" 、 "入力フィルタ" が利用可能になる。

このモードでは $TL->startCgi メソッドで "Main 関数" を呼ぶ。

FastCGI モード

FastCGI としてプログラムを動作させるモード。httpd から fcgi スクリプトとして起動 しようとすると、自動的に選ばれる。このモードではプロセスのメモリ使用量を 監視し、起動後にある一定の大きさを越えてメモリ使用量が増大すると、メモリリーク が発生しているとして自動的に終了する。また、 Ini パラメータ付きで use Tripletail したスクリプトファイルや、その Ini ファイルの最終更新時刻 も監視し、更新されていたら自動的に終了する。

このモードでは $TL->startCgi メソッドで "Main 関数" を呼ぶ。

FastCGI モードでは fork が正しく動作しない事に注意。代わりに $TL->fork メソッドを使用する。

一般スクリプトモード

CGI でない一般のスクリプトとしてプログラムを動作させるモード。 CGI モード特有の機能は利用出来ない。

このモードでは $TL->trapError メソッドで "Main 関数" を呼ぶ。

出力フィルタ

$TL->print や $template->flush で出力される内容は、 Tripletail::Filter によって加工される。出力の先頭に HTTP ヘッダを 付加するのも出力フィルタである。

入力フィルタ

$ENV{QUERY_STRING} その他の CGI のリクエスト情報は、 Tripletail::InputFilter が読み取り、 Tripletail::Form オブジェクトを生成する。得られたリクエスト情報は $CGI オブジェクトか $TL->CGI メソッドで取得出来る。

Main 関数

リクエスト一回毎に呼ばれる関数。この関数の中で CGI プログラムは入出力を行う。 "FastCGI モード" 以外では一度のプロセスの起動で一度しか呼ばれない。

フック

$TL->setHook メソッドを用いてフックを掛ける事が出来る。

init

"startCgi" もしくは "trapError" が呼ばれ、最初に "Main 関数" が 呼ばれる前。 FastCGI の場合は最初の1回だけ呼ばれる。

initRequest

"startCgi" 利用時は、リクエストを受け取った直後、フォームがデコードされる前に呼ばれる。 リクエストごとに呼び出される。

"trapError" 利用時は "postRequest" フックの前に呼び出される。

preRequest

"startCgi" 利用時は、フォームをデコードした後、"Main 関数" が呼ばれる前に呼ばれる。 リクエストごとに呼び出される。 ただし、フォームのデコード処理に失敗した場合、"preRequest"" in " は実行されずにリクエスト処理が終了する。

"trapError" 利用時は "initRequest" フックの後、"Main 関数" が呼ばれる前に呼ばれる。

postRequest

"startCgi" 利用時は、"Main 関数" の処理を終えた後、コンテンツの出力を行ってから呼び出される。 リクエストごとに呼び出される。 ただし、フォームのデコード処理に失敗した場合、"postRequest" は実行されずにリクエスト処理が終了する。

"trapError" 利用時は "Main 関数" が呼ばれた後に呼び出される。

term

最後に "Main 関数" が呼ばれた後。termフック呼出し後に "startCgi" もしくは "trapError" が終了する。 FastCGI の場合は最後の1回だけ呼ばれる。

METHODS

よく使うもの

startCgi

$TL->startCgi(
  -main    => \&Main,    # メイン関数
  -DB      => 'DB',      # Tripletail::DB を使う場合，ini のグループ名を指定
  -MongoDB => 'MongoDB', # Tripletail::MongoDB を使う場合，ini のグループ名を指定
  -Session => 'Session', # Tripletail::Session を使う場合、ini のグループ名を指定
);

CGI を実行する為の環境を整えた上で、 "Main 関数" を実行する。 "Main 関数" がdie した場合は、エラー表示 HTML が出力される。

DB は、次のように配列へのリファレンスを渡す事で、複数指定可能。 MongoDB も同様。

$TL->startCgi(
  -main => \&Main,
  -DB   => ['DB1', 'DB2'],
);

Session は、次のように配列へのリファレンスを渡す事で、複数指定可能。

$TL->startCgi(
  -main    => \&Main,
  -DB      => 'DB',
  -Session => ['Session1', 'Session2'],
);

通常のスクリプトを書く場合は "trapError" を参照.

CGI

$TL->CGI
$CGI

リクエストを受け取った Tripletail::Form オブジェクトを返す。 また、このオブジェクトは startCgi メソッドの呼び出し元パッケージに export される。

このメソッドがundefでない値を返すのは、 "preRequest" フックが呼ばれる 直前から "postRequest" フックが呼ばれた直後までである。

dispatch

$result = $TL->dispatch($value, %params)

$params{default} = $scalar.
$params{onerror} = \&error.
$params{args}    = \@args.

'Do' と $value を繋げた関数名の関数を呼び出す。 $valueがundefの場合、 default を指定していた場合、default に設定される。 $value は大文字で始まらなければならない。

args 引数が指定されていた場合、関数にその内容を渡す。 指定されていなければ関数は引数なしで呼び出される。 (0.44以降)

onerror が未設定で関数が存在しなければ undef、存在すれば1を返す。

onerror が設定されていた場合、関数が存在しなければ onerror で設定された関数が呼び出される。

例:
package Foo;

sub main {
    my $what = 'Foo';
    $TL->dispatch($what, default => 'Foo', onerror => \&DoError);
}

sub DoFoo {
    ...
}

sub DoError {
    ...
}

print

$TL->print($str)

コンテンツデータを出力する。"startCgi" から呼ばれた "Main 関数" 内 のみで使用できる。ヘッダは出力できない。

フィルタによってはバッファリングされる場合もあるが、 基本的にはバッファリングされない。

location

$TL->location('http://example.org/')

CGI モードの時、指定されたURLへリダイレクトする。 このメソッドはあらゆる出力の前に呼ばなくてはならない。

また、出力フィルタが Tripletail::Filter::HTML か Tripletail::Filter::MobileHTML の場合のみ利用できる。

eval

$TL->eval(sub {
              # Statements which may throw...
            });
if ($@) {
    ....
}

引数として与えられたサブルーチンを実行するが、その実行中は Tripletail によるエラー処理を無効にする。サブルーチンが正常な動作の範囲内として die する事が判っている場合に、エラー処理のコストを減らし、且つ $@ が書き換えられる事を防ぐために使用する。

変換処理

escapeTag

$result = $TL->escapeTag($value)

&<>"' の文字をエスケープ処理した文字列を返す。

unescapeTag

$result = $TL->unescapeTag($value)

&<>"'&#??;&#x??; にエスケープ処理された文字を元に戻した文字列を返す。

escapeJs

$result = $TL->escapeJs($value)

'"\ の文字を \ を付けてエスケープし，'\r' '\n' について '\\r' '\\n' に置き換える。

unescapeJs

$result = $TL->unescapeJs($value)

escapeJs した文字列を元に戻す。

escapeJsString

$result = $TL->escapeJsString($value)

JavaScriptの文字列コードになるようにエスケープする。 その際には、html内にJavaScriptを埋め込んだ際に終端と誤認される「</script>」「-->」を考慮する。 例えば、

$TL->escapeJsString("ab\"cd </script> def")

を評価すると、

'"ab\"cd </scr"+"ipt> def"'

が得られる。

unescapeJsString

$result = $TL->unescapeJsString($value)

escapeJsString した文字列を元に戻す。

encodeURL

$result = $TL->encodeURL($value)

文字列をURLエンコードした結果を返す。

decodeURL

$result = decodeURL($value)

URLエンコードを解除し元に戻した文字列を返す。

escapeSqlLike

$result = $TL->escapeSqlLike($value)

% _ \ の文字を \ でエスケープ処理した文字列を返す。

unescapeSqlLike

$result = $TL->unescapeSqlLike($value)

\% \_ \\ にエスケープ処理された文字を元に戻した文字列を返す。

charconv

$str = $TL->charconv($str, $from, $to);

$str = $TL->charconv($str, 'auto' => 'UTF-8');

文字コード変換を行う。 基本的に Unicode::Japanese を利用するが、サポートしていない 文字コードの場合は Encode を使用する。

$from が省略された場合は 'auto' に、 $to が省略された場合は 'UTF-8' になる。

指定できる文字コードは、 UTF-8，Shift_JIS，EUC-JP，ISO-2022-JP のほか、 Unicode::Japanese、Encode がサポートしているものが使用できる。

parsePeriod

$TL->parsePeriod('10hour 30min')

時間指定文字列を秒数に変換する。小数点が発生した場合は切り捨てる。 "度量衡" を参照。

parseQuantity

$TL->parseQuantity('100mi 50ki')

量指定文字列を元の数に変換する。 "度量衡" を参照。

インスタンス生成取得

getDB

$DB = $TL->getDB($group)

Tripletail::DB オブジェクトを取得。

newDB

$DB = $TL->newDB($group)

Tripletail::DB オブジェクトを作成。

getMongoDB

$DB = $TL->getMongoDB($group)

Tripletail::MongoDB オブジェクトを取得。

newMongoDB

$DB = $TL->newMongoDB($group)

Tripletail::MongoDB オブジェクトを作成。

newForm

Tripletail::Form オブジェクトを作成。

newTemplate

Tripletail::Template オブジェクトを作成。

getSession

Tripletail::Session オブジェクトを取得。

newValidator

Tripletail::Validator オブジェクトを生成。

newValue

Tripletail::Value オブジェクトを作成。

newDateTime

Tripletail::DateTime オブジェクトを作成。

newPager

Tripletail::Pager オブジェクトを作成。

newCsv

Tripletail::CSV オブジェクトを取得。

getCsv

Tripletail::CSV オブジェクトを取得。 互換用なので、newCsv の利用を推奨。

newTagCheck

Tripletail::TagCheck オブジェクトを作成。

newHtmlFilter

Tripletail::HtmlFilter オブジェクトを作成。

newHtmlMail

Tripletail::HtmlMail オブジェクトを作成。

newMail

Tripletail::Mail オブジェクトを作成。

newIni

Tripletail::Ini オブジェクトを作成。

getCookie

Tripletail::Cookie オブジェクトを取得。

getRawCookie

Tripletail::RawCookie オブジェクトを取得。

newSendmail

Tripletail::Sendmail オブジェクトを作成。

newSerializer

Tripletail::Serializer オブジェクトを作成。

newSMIME

Crypt::SMIME オブジェクトを作成。

getFileSentinel

Tripletail::FileSentinel オブジェクトを取得。

getMemorySentinel

Tripletail::MemorySentinel オブジェクトを取得。

newMemCached

Tripletail::MemCached オブジェクトを生成。

その他

INI

$TL->INI

use Tripletail qw(filename.ini); で読み込まれた Tripletail::Ini を返す。

trapError

$TL->trapError(
  -main    => \&Main,    # メイン関数
  -DB      => 'DB',      # Tripletail::DB を使う場合，ini のグループ名を指定
  -MongoDB => 'MongoDB', # Tripletail::MongoDB を使う場合，ini のグループ名を指定
);

環境を整え、 "Main 関数" を実行する。 "Main 関数" がdie した場合は、エラー内容が標準エラーへ出力される。

"startCgi" と同様に、DB や MongoDB には配列へのリファレンスを渡す事も出来る。

fork

if (my $pid = $TL->fork) {
    # parent
}
else {
    # child
}

FastCGI 環境を考慮しながら fork を実行する。 FastCGI 環境でない場合は通 常通りに fork する。fork に失敗した場合は die する。

通常は perl 組込み関数である fork を使用しても問題無いが、 FastCGI 環境 では正常に動作しない為、Tripletail アプリケーションは常に fork でなく $TL->fork を使用する事が推奨される。

log

$TL->log($group => $log)

ログを記録する。グループとログデータの２つを受け取る。

第一引数のグループは省略可能。 ログデータがリファレンスだったときは Data::Dumper によってダンプされる。

ログにはヘッダが付けられ、ヘッダは「時刻(epoch値の16進数8桁表現) プロセス ID の16進数4桁表現 FastCGI のリクエスト回数の16進数4桁表現 [グループ]」の形で付けられる。

setContentFilter

$TL->setContentFilter($classname, %option)
$TL->setContentFilter([$classname, $priority], %option)
$TL->setContentFilter('Tripletail::Filter::HTML', charset => 'Shift_JIS')
$TL->setContentFilter(
    'Tripletail::Filter::CSV', charset => 'Shift_JIS', filename => 'テストデータ.csv')

"出力フィルタ" を設定する。 全ての出力の前に実行する必要がある。 ２番目の書式では、プライオリティを指定して独自のコンテンツフィルタを 追加できる。省略時は優先度は1000となる。小さい優先度のフィルタが先に、 大きい優先度のフィルタが後に呼ばれる。同一優先度のフィルタが既に セットされているときは、以前のフィルタ設定は解除される。

返される値は、指定された Tripletail::Filter のサブクラスのインスタンスである。

設定したフィルタは、"preRequest" 実行後のタイミングで保存され、 "postRequest" のタイミングで元に戻される。従って、"Main 関数"内 で setContentFilter を実行した場合、その変更は次回リクエスト時に持ち越 されない。

getContentFilter

$TL->getContentFilter($priority)

指定されたプライオリティのフィルタを取得する。省略時は1000となる。

removeContentFilter

$TL->removeContentFilter($priority)

指定されたプライオリティのフィルタを削除する。省略時は1000となる。 フィルタが１つもない場合は、致命的エラーとなり出力関数は使用できなくなる。

getLogHeader

my $logid = $TL->getLogHeader

ログを記録するときのヘッダと同じ形式の文字列を生成する。 「時刻(epoch値の16進数8桁表現) プロセス ID の16進数4桁表現 FastCGI のリクエスト回数の16進数4桁表現」の形の文字列が返される。

setHook

$TL->setHook($type, $priority, \&func)

指定タイプの指定プライオリティのフックを設定する。 既に同一タイプで同一プライオリティのフックが設定されていた場合、 古いフックの設定は解除される。

type は、"init", "term", "initRequest", "preRequest", "postRequest" の４種類が存在する。

なお、1万の整数倍のプライオリティは Tripletail 内部で使用される。アプリ ケーション側で不用意に用いるとフックを上書きしてしまう可能性があるので 注意する。

removeHook

$TL->removeHook($type, $priority)

指定タイプの指定プライオリティのフックを削除する。

setInputFilter

$TL->setInputFilter($classname, %option)
$TL->setInputFilter([$classname, $priority], %option)

"入力フィルタ" を設定する。 "startCgi" の前に実行する必要がある。

返される値は、指定された Tripletail::InputFilter のサブクラスのインスタンスである。

getInputFilter

$TL->getInputFilter($priority)

removeInputFilter

$TL->removeInputFilter($priority)

sendError

$TL->sendError(title => "タイトル", error => "エラー")

ini で指定されたアドレスにエラーメールを送る。 設定が無い場合は何もしない。

readFile

$data = $TL->readFile($fpath);

ファイルを読み込む。文字コード変換をしない。 ファイルロック処理は行わないので、使用の際には注意が必要。

readTextFile

$data = $TL->readTextFile($fpath, $coding);

ファイルを読み込み、 UTF-8 に変換する。 ファイルロック処理は行わないので、使用の際には注意が必要。

$coding が省略された場合は 'auto' となる。

writeFile

$TL->writeFile($fpath, $fdata, $fmode);

ファイルにデータを書き込む。文字コード変換をしない。 ファイルロック処理は行わないので、使用の際には注意が必要。

$fmode が0ならば、上書きモード。 $fmode が1ならば、追加モード。

省略された場合は上書きモードとなる。

writeTextFile

$TL->writeTextFile($fpath, $fdata, $fmode, $coding);

ファイルにデータを書き込む。$fdata を UTF-8 と見なし、指定された文字コードへ変換を行う。 ファイルロック処理は行わないので、使用の際には注意が必要。

$fmode が0ならば、上書きモード。 $fmode が1ならば、追加モード。

省略された場合は上書きモードとなる。

$coding が省略された場合、 UTF-8 として扱う。

watch

$TL->watch(sdata => \$sdata, $reclevel);
$TL->watch(adata => \@adata, $reclevel);
$TL->watch(hdata => \%hdata, $reclevel);

指定したスカラー、配列、ハッシュデータの更新をウォッチし、ログに出力する。 第1引数で変数名を、第2引数で対象変数へのリファレンスを渡す。

第2引数はウォッチ対象の変数に、リファレンスが渡された場合に、 そのリファレンスの先を何段階ウォッチするかを指定する。デフォルトは0。

スカラー、配列、ハッシュ以外のリファレンスが代入された場合はエラーとなる。

また、再帰的にウォッチする場合、変数名は親の変数名を利用して自動的に設定される。

dump

$TL->dump(\$data);
$TL->dump(\$data, $level);
$TL->dump(DATA => \$data);
$TL->dump(DATA => \$data, $level);

第2引数に変数へのリファレンスを渡すと，その内容を Data::Dumper でダンプし、 第1引数のグループ名で $TL->log を呼び出す。

第1引数のグループ名は省略可能。

第3引数で、リファレンスをどのくらいの深さまで追うかを指定することが出来る。 指定しなければ全て表示される。

setCacheFilter

$TL->setCacheFilter($form)
$TL->setCacheFilter($form, $charset)
$TL->setCacheFilter($hashref)
$TL->setCacheFilter($hashref, $charset)

"printCacheUnlessModified" と "setCache" を利用する際に使用する。 第1引数で渡された Tripletail::Form オブジェクトのキーが出力文字列中に存在している場合、値に置換する。

Tripletail::Formオブジェクトの代わりにハッシュのリファレンスを渡すことも出来る。 ハッシュのリファレンスを渡した場合は、$TL->newForm($hashref) した結果のフォームオブジェクトを追加する。

第2引数は、第1引数で指定した文字列を UTF-8 から変換する際の文字コードを指定する。 省略可能。

使用可能なコードは次の通り。 UTF-8 ，Shift_JIS，EUC-JP，ISO-2022-JP

デフォルトはShift_JIS。

printCacheUnlessModified

$bool = $TL->printCacheUnlessModified($key, $status)

第1引数で割り当てられたキーがメモリ上にキャッシュされているかを調べる。 利用するには、 memcached が必須となる。

第2引数が304の場合、304レスポンスを送る動作を行う。200の場合、200レスポンスを送る動作を行う。 省略可能。

デフォルトは304。

この関数は次のような動作を行っている。

1. memcached からキーに割り当てられたキャッシュデータを読み込む。 データが無ければ、1を返す。

2.キャッシュデータの保存された時間と前回アクセスされた時間を比較し、 キャッシュデータが新しければキャッシュデータを出力し、undefを返す。

3.アクセスされた時間が新しければ、304レスポンスを出力し、undefを返す。 （第2引数が304の場合。200の場合はキャッシュデータを出力する）

この関数からundefを返された場合、以後出力を行う操作を行ってはならない。

setCache

$TL->setCache($key, $priority)

第1引数で割り当てられたキーに対して出力される内容をメモリ上にキャッシュする。 また、Last-Modified ヘッダを出力する。 printCacheUnlessModified より後で実行する必要がある。 利用するには、 memcached が必須となる。

第2引数には、Tripletail::Filter::MemCachedへの優先度を記述する。省略可能。 デフォルトは1500。

Tripletail::Filter::MemCachedは必ず最後に実行する必要性があるため、 1500以上の優先度で設定するフィルタが他にある場合は手動で設定する必要がある。

deleteCache

$TL->deleteCache($key)

第1引数で割り当てられたキーのキャッシュを削除する。 利用するには、 memcached が必須となる。

なお、setCacheの後にdeleteCacheを実行しても、setCacheでのメモリへの書き込みは、 処理の最後に行われるので、deleteCacheは反映されない。

本関数の使い方としては、キャッシュの内容を含んでいるデータを更新した場合に 該当するキャッシュを削除するように使用する。 それにより、次回アクセス時に最新の情報が出力される。

getDebug

newError

内部用メソッド。

Ini パラメータ

グループ名は常に TL でなければならない。

例:

[TL]
logdir = /home/www/cgilog/
errortemplate = /home/www/error.html
errortemplatecharset = Shift_JIS

maxrequestsize

maxrequestsize = 16M 500K

最大リクエストサイズ。但しファイルアップロードの分を除く。デフォルトは8M。

maxfilesize

maxfilesize = 100M

一回のPOSTでアップロード可能なファイルサイズの合計。デフォルトは8M。ファ イルのサイズは maxrequestsize とは別にカウントされ、ファイルでないもの については maxrequestsize の値が使われる。

fault_handler

fault_handler = Name::Of::Handler

startCgi での最大リクエストサイズ若しくは アップロード可能なファイルサイズを超えたときに 例外ハンドラとする関数名。 モジュールは必要なら自動でロードされる。

# [TL]
# fault_handler = MyApp::FaultHandler
package MyApp;
sub FaultHandler
{
  my $pkg = shift;
  my $err = shift;
  my $status = ref($err) && $err->{http_status_line};
  $status ||= '500 Internal Server Error';
  
  print "Status: $status\r\n";
  print "Content-Type: text/plain; charset=utf-8\r\n";
  print "\r\n";
  print "error: $err\n";
}

(http_status_line は 0.42 以降でサポート)

logdir

logdir = /home/www/cgilog/

ログの出力ディレクトリ。

tempdir

tempdir = /tmp

一時ファイルを置くディレクトリ。このパラメータの指定が無い時、アップロー ドされたファイルは全てメモリ上に置かれるが、指定があった場合は指定され たディレクトリに一時ファイルとして置かれる。一時ファイルを作る際には、 ファイルを open した直後に unlink する為、アプリケーション側でファイル ハンドルを閉じたりプロセスを終了したりすると、作られた一時ファイルは直 ちに自動で削除される。

errormail

errormail = null@example.org%Sendmail

sendErrorや、エラー発生時にメールを送る先を指定する。 アカウント名@ドメイン名%inigroup 、の形式で指定する。 inigroup に Tripletail::Sendmail クラスで使用する inigroup を指定する。 inigroup が省略されると 'Sendmail' が使われる。

errormailtype

errormailtype = error file-update memory-leak

どのような事象が発生した時に errormail で指定された先にメールを送るか。 以下の項目をスペース区切りで任意の数だけ指定する。 デフォルトは 'error memory-leak' である。

errormail_subject_len

errormail_subject_len = 80

エラー発生時に送られるメールの表題の最大長。長過ぎるとメール送信に失敗 する場合がある。デフォルトは 80 バイト。

error

エラーが発生した時にメールを送る。 メールの内容にはスタックトレース等が含まれる。

file-update

Tripletail::FileSentinel が監視対象のファイルの更新を検出した時にメールを送る。 メールの内容には更新されたファイルやその更新時刻が含まれる。

memory-leak

Tripletail::MemorySentinel がメモリリークの可能性を検出した時にメールを送る。 メールの内容にはメモリの使用状況が含まれる。

errorlog

errorlog = 1

エラー発生時にログに情報を残すかどうかを指定する。 1 が指定されればエラー情報を残す。 2 が指定されれば、エラー情報に加え、 CGI のリクエスト内容も残す（startCgi内でのエラーのみ）。 3 が指定されれば、ローカル変数内容を含んだ詳細なエラー情報に加えて（但し PadWalker が必要）、 CGI のリクエスト内容も残す。 0 であれば情報を残さない。 デフォルトは 1。

fcgilog

fcgilog = 1

FCGI 関連の動作をログに記録するかどうかを指定する。 1 が指定されれば記録する。 0 であれば記録しない。 デフォルトは 0。

memorylog

memorylog = full

リクエスト毎にメモリ消費状況をログに残すかどうかを指定する。 'leak', 'full' のどちらかから選ぶ。 'leak' の場合は、メモリリークが検出された場合のみログに残す。 'full' の場合は、メモリリークの検出とは無関係に、リクエスト毎にログに残す。 デフォルトは 'leak' 。

filelog

filelog = full

ファイルの更新の監視状況をログに残すかどうかを指定する。 'update', 'full' のどちらかから選ぶ。 'update' の場合は、ファイルが更新された場合のみログに残す。 'full' の場合は、ファイルの監視を開始した際にもログに残す。 デフォルトは 'update'。

trap

trap = die

エラー処理の種類。'none', 'die'，'diewithprint' から選ぶ。デフォルトは'die'。

none

エラートラップを一切しない。

die

"Main 関数" がdie した場合にエラー表示。それ以外の場所ではトラップしない。warnは見逃す。

diewithprint

"Main 関数" がdie した場合にエラー表示。"Main 関数" 以外でdie した場合は、ヘッダと共にエラー内容をテキストで表示する。warnは見逃す。

stacktrace

stacktrace = full

エラー発生時に表示するスタックトレースの種類。'none' の場合は、スタック トレースを一切表示しない。'onlystack' の場合は、スタックトレースのみを 表示する。'full' の場合は、スタックトレースに加えてソースコード本体並び に各フレームに於けるローカル変数の一覧をも表示する。デフォルトは 'onlystack'。

但しローカル変数一覧を表示するには PadWalker がインストールされてい なければならない。

注意: 'full' の状態では、stackallow で許された全てのユーザーが、 ブラウザから全てのソースコード及び ini ファイルの中身を読む事が出来る点に注意すること。

stackallow

stackallow = 192.168.0.0/24

stacktrace の値が 'none' でない場合であっても、stackallow で指定された ネットマスクに該当しない IP からの接続である場合には、スタックトレース を表示しない。マスクは空白で区切って複数個指定する事が可能。 デフォルトは全て禁止。

maxrequestcount

maxrequestcount = 100

FastCGI モード時に、1つのプロセスで何回まで処理を行うかを設定する。 0を設定すれば回数によってプロセスが終了することはない。 デフォルトは0。

errortemplate

errortemplate = /home/www/error.html

エラー発生時に、通常のエラー表示ではなく、指定された テンプレートファイルを表示する。

errortemplatecharset

errortemplatecharset = Shift_JIS

errortemplate指定時に、エラーメッセージを返す際の charset を指定する。

UTF-8 ， Shift_JIS ， EUC-JP ， ISO-2022-JP が指定できる。デフォルトは UTF-8 。

outputbuffering

outputbuffering = 0

startCgi メソッド中で出力をバッファリングするかどうか。 0 だとバッファリングを行わず、 1 だとバッファリングを行う。 デフォルトは0。

バッファリングしない場合、print した内容はすぐに表示されるが、少しでも表示を行った後にエラーが発生した場合は、エラーテンプレートが綺麗に表示されない。

バッファリングを行った場合、print した内容はリクエスト終了時まで表示されないが、処理中にエラーが発生した場合、出力内容は破棄され、エラーテンプレートの内容に差し替えられる。 また、Content-Length ヘッダが付与される。

Tripletail::Filter::MobileHTML を利用した場合、outputbuffering は1にセットされる。

allow_mutable_input_cgi_object

allow_mutable_input_cgi_object = 1

非推奨. 互換のためのパラメータ. (0.40以降)

$TL-CGI> で返される CGI 入力値を保持しているオブジェクトの const 化を行わないようにする.

compat_no_trap_for_cgi_internal_error

compat_no_trap_for_cgi_internal_error = 1

互換のためのパラメータ. (0.42以降)

CGI モード動作時の startCgi 外のエラーに対する エラー画面の表示を抑制する. (httpd による通常の Internal Server Error 画面になります)

compat_form_getfilename_returns_fullpath

互換のためのパラメータ. (0.45以降)

1 (真)を設定することで $form-getFileName|Tripletail::Form/getFileName> が フルパスを返す振る舞いに戻す。 デフォルト値は偽で, getFileName はベース名部分のみを返す.

新しいコードではフルパスが欲しいときには $form-getFullFileName|Tripletail::Form/getFullFileName> を推奨。

command_add_processname

command_add_processname = 1

FastCGI で処理する際に、プロセス名に各種情報を表示するかを指定します。(0.46以降)

0 だとプロセス名を変更しません。 1 だとプロセス名を変更します。 デフォルトは0です。

1 にすると「perl リクエスト処理回数 (処理内容) スクリプト名」となります。

処理内容には、FastCGI 時に fcgi run、fcgi wait が表示されます。 また、$TL-dispatch> を使用した際は、分岐先のコマンドが追加されます。

プロセス名は、起動時のプロセス名の長さより長くすることが出来ないため、 起動時の状況によっては全て表示されないことがあります。

度量衡

時間指定

各種タイムアウト時間，セッションのexpiresなど、 時間間隔は以下の指定が可能とする。 数値化には "parsePeriod" を使用する.

単位は大文字小文字を区別しない。

数値のみ

秒数での指定を表す。

数値＋ 'sec' or 'second' or 'seconds'

秒での指定を表す。[×1]

数値＋ 'min' or 'minute' or 'minutes'

分での指定を表す。[×60]

数値＋ 'hour' or 'hours'

時間での指定を表す。[×3600]

数値＋ 'day' or 'days'

日数での指定を表す。[×24*3600]

数値＋ 'mon' or 'month' or 'months'

月での指定を表す。１月＝30.436875日として計算する。 [×30.436875*24*3600]

数値＋ 'year' or 'years'

年での指定を表す。１年＝365.2425日として計算する。 [×365.2425*24*3600]

量指定

メモリサイズ、文字列サイズ等、大きさを指定する場合には、 以下の指定が可能とする。英字の大文字小文字は同一視する。

数値化には "parseQuantity" を使用する.

10進数系

数値のみ

そのままの数を表す。

数値＋ 'k'

数値×1000の指定を表す。[×1,000]

数値＋ 'm'

数値×1000^2の指定を表す。[×1,000,000=×1,000^2]

数値＋ 'g'

数値×1000^3の指定を表す。[×1,000,000,000=×1,000^3]

数値＋ 't'

数値×1000^4の指定を表す。[×1,000,000,000,000=×1,000^4]

数値＋ 'p'

数値×1000^5の指定を表す。[×1,000,000,000,000,000=×1,000^5]

数値＋ 'e'

数値×1000^6の指定を表す。[×1,000,000,000,000,000,000=×1,000^6]

2進数系

数値＋ 'Ki'

数値×1024の指定を表す。[×1024=2^10]

数値＋ 'Mi'

数値×1024^2の指定を表す。[×1024^2=2^20]

数値＋ 'Gi'

数値×1024^3の指定を表す。[×1024^3=2^30]

数値＋ 'Ti'

数値×1024^4の指定を表す。[×1024^4=2^40]

数値＋ 'Pi'

数値×1024^5の指定を表す。[×1024^5=2^50]

数値＋ 'Ei'

数値×1024^6の指定を表す。[×1024^6=2^60]

SAMPLE

perldoc -u Tripletail |  podselect -sections SAMPLE | sed -e '1,4d' -e 's/^ //'


# master configurations.
#
[TL]
logdir=/home/project/logs/error
errormail=errors@your.address
errorlog=2
trap=diewithprint
stackallow=0.0.0.0/0

[TL:SmallDebug]
stacktrace=onlystack
outputbuffering=1

[TL:Debug]
stacktrace=full
outputbuffering=1

[TL:FullDebug]
stacktrace=full
outputbuffering=1
stackallow=0.0.0.0/0

# database configrations.
#
[DB]
type=mysql
namequery=1
tracelevel=0
AllTransaction=DBALL
defaultset=AllTransaction
[DBALL]
dbname=
user=
password=
#host=

[DB:SmallDebug]

[DB:Debug]

[DB:FullDebug]
tracelevel=2

# debug configrations.
#
[Debug]
enable_debug=0

[Debug:SmallDebug]
enable_debug=1

[Debug:Debug]
enable_debug=1
request_logging=1
content_logging=1
warn_logging=1
db_profile=1
popup_type=single
template_popup=0
request_popup=1
db_popup=0
log_popup=1
warn_popup=1

[Debug:FullDebug]
enable_debug=1
request_logging=1
content_logging=0
warn_logging=1
db_profile=1
popup_type=single
template_popup=1
request_popup=1
db_popup=1
log_popup=1
warn_popup=1
location_debug=1

# misc.
#
[SecureCookie]
path=/
secure=1

[Session]
mode=https
securecookie=SecureCookie
timeout=30min
updateinterval=10min
dbgroup=DB
dbset=AllTransaction

# user data.
# you can read this data:
# $val = $TL->INI->get(UserData=>'roses');
#
[UserData]
roses=red
violets=blue
sugar=sweet

SEE ALSO

Tripletail::Cookie

Tripletail::DB

Tripletail::Debug

CGI 向けデバッグ機能。

リクエストや応答のログ記録、デバッグ情報のポップアップ表示、他。

Tripletail::Filter

Tripletail::FileSentinel

Tripletail::Form

Tripletail::HtmlFilter

Tripletail::HtmlMail

Tripletail::Ini

Tripletail::InputFilter

Tripletail::Mail

Tripletail::MemorySentinel

Tripletail::Pager

Tripletail::RawCookie

Tripletail::Sendmail

Crypt::SMIME

Tripletail::TagCheck

Tripletail::Template

Tripletail::Session

Tripletail::Value

Tripletail::Validator

AUTHOR INFORMATION

Copyright 2006 YMIRLINK Inc.

This framework is free software; you can redistribute it and/or modify it under the same terms as Perl itself

このフレームワークはフリーソフトウェアです。あなたは Perl と同じライセンスの 元で再配布及び変更を行うことが出来ます。

Address bug reports and comments to: tl@tripletail.jp

HP : http://tripletail.jp/

cpanm Tripletail

perl -MCPAN -e shell
install Tripletail