Tripletail - Tripletail, Framework for Japanese Web Application

# 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`

tlでは、ライブラリの各種設定は 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/regist

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

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

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

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

## 特化指定

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

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

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

      use Tripletail qw(/home/www/ini/tl.ini regist);
    で、起動した場合、次のような動作になる。

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

      [TL]
      logdir = /home/tl/logs/regist/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/regist

      use Tripletail qw(/home/www/ini/tl.ini regist);
    で、起動した場合、次のような動作になる。

プログラムが動いているサーバが、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

## 携帯向け設定

以下のように、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" は実行されずにリクエスト処理が終了する。

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

postRequest

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

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

term

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

## METHODS

### よく使うもの

#### `startCgi`

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

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

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

      $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, default => $default, onerror => \&Error)

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

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 の場合のみ利用できる。

### 変換処理

#### `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 した文字列を元に戻す。

#### `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 オブジェクトを作成。

#### `newForm`

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

#### `newTemplate`

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

#### `getSession`

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

#### `newValidator`

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

#### `newValue`

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

#### `newDateTime`

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

#### `newPager`

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

#### `getCsv`

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

#### `newTagCheck`

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

#### `newHtmlFilter`

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

#### `newHtmlMail`

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

#### `newMail`

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

#### `newIni`

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

#### `getCookie`

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

#### `getRawCookie`

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

#### `newSendmail`

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

#### `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',   # DBを使う場合，iniのグループ名を指定
      );

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

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

#### `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' である。

  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。

  バッファリングしない場合、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 画面になります)

## 度量衡

### 時間指定

各種タイムアウト時間，セッションの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. All Rights Reserved.

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/

Tripletail - Tripletail, Framework for Japanese Web Application

# INDEX

- 10進数系
- 2進数系
- AUTHOR INFORMATION
- CGI
- CGIモード
- Crypt::SMIME
- DESCRIPTION
- FastCGIモード
- INI
- Ini パラメータ
- METHODS
- Main関数
- NAME
- NAME (ja)
- SAMPLE
- SEE ALSO
- SYNOPSIS
- Tripletail::Cookie
- Tripletail::DB
- Tripletail::Debug
- Tripletail::FileSentinel
- Tripletail::Filter
- Tripletail::Form
- Tripletail::HtmlFilter
- Tripletail::HtmlMail
- Tripletail::Ini
- Tripletail::InputFilter
- Tripletail::Mail
- Tripletail::MemorySentinel
- Tripletail::Pager
- Tripletail::RawCookie
- Tripletail::Sendmail
- Tripletail::Session
- Tripletail::TagCheck
- Tripletail::Template
- Tripletail::Validator
- Tripletail::Value
- allow_mutable_input_cgi_object
- charconv
- compat_no_trap_for_cgi_internal_error
- decodeURL
- deleteCache
- die
- diewithprint
- dispatch
- dump
- encodeURL
- error
- errorlog
- errormail
- errormailtype
- errortemplate
- errortemplatecharset
- escapeJs
- escapeSqlLike
- escapeTag
- fault_handler
- fcgilog
- file-update
- filelog
- fork
- getContentFilter
- getCookie
- getCsv
- getDB
- getDebug
- getFileSentinel
- getInputFilter
- getLogHeader
- getMemorySentinel
- getRawCookie
- getSession
- init
- initRequest
- location
- log
- logdir
- maxfilesize
- maxrequestcount
- maxrequestsize
- memory-leak
- memorylog
- newDB
- newDateTime
- newError
- newForm
- newHtmlFilter
- newHtmlMail
- newIni
- newMail
- newMemCached
- newPager
- newSMIME
- newSendmail
- newTagCheck
- newTemplate
- newValidator
- newValue
- none
- outputbuffering
- parsePeriod
- parseQuantity
- postRequest
- preRequest
- print
- printCacheUnlessModified
- readFile
- readTextFile
- removeContentFilter
- removeHook
- removeInputFilter
- sendError
- setCache
- setCacheFilter
- setContentFilter
- setHook
- setInputFilter
- stackallow
- stacktrace
- startCgi
- tempdir
- term
- trap
- trapError
- unescapeJs
- unescapeSqlLike
- unescapeTag
- use
- watch
- writeFile
- writeTextFile
- その他
- よく使うもの
- インスタンス生成取得
- キャッシュの利用
- フック
- 一般スクリプトモード
- 入力フィルタ
- 出力フィルタ
- 変換処理
- 実行モード
- 度量衡
- 携帯向け設定
- 数値のみ
- 数値＋ 'Ei'
- 数値＋ 'Gi'
- 数値＋ 'Ki'
- 数値＋ 'Mi'
- 数値＋ 'Pi'
- 数値＋ 'Ti'
- 数値＋ 'day' or 'days'
- 数値＋ 'e'
- 数値＋ 'g'
- 数値＋ 'hour' or 'hours'
- 数値＋ 'k'
- 数値＋ 'm'
- 数値＋ 'min' or 'minute' or 'minutes'
- 数値＋ 'mon' or 'month' or 'months'
- 数値＋ 'p'
- 数値＋ 'sec' or 'second' or 'seconds'
- 数値＋ 't'
- 数値＋ 'year' or 'years'
- 時間指定
- 書き込み側例（ページ全体をキャッシュ）
- 書き込み側例（ユーザー名等一部に固有の情報を埋め込んでいる場合）
- 特化指定
- 読み込み側例（ページ全体をキャッシュ）
- 読み込み側例（ユーザー名等一部に固有の情報を埋め込んでいる場合）
- 量指定

Tripletail - Tripletail, Framework for Japanese Web Application