File-Log-1.05 > File::Log

## POD DOCUMENTATION ##

名前

File::Log - シンプルなオブジェクト指向のログ出力機能

概要

 use File::Log;

 # 全てのパラメータを含む完全な形式
 my $log = File::Log->new({
   debug           => 4,                   # デバッグレベルの設定
   logFileName     => 'myLogFile.log',     # ログファイル名の指定
   logFileMode     => '>',                 # '>>' で追加、 '>' で上書き指定
   dateTimeStamp   => 1,                   # ログデータエントリに時刻を追加
   stderrRedirect  => 1,                   # ログファイルにSTDERRをリダイレクト
   defaultFile     => 1,                   # ログファイルを既定値のファイルハンドルにする
   logFileDateTime => 1,                   # ログファイル名にタイムスタンプを付加
   appName         => 'myApplicationName', # アプリケーションの名前
   PIDstamp        => 1,                   # ログデータにプロセスIDを付加
   storeExpText    => 1,                   # 内部的な全ての例外テキストを格納
   msgprepend      => '',                  # 各メッセージ先頭に追加するテキスト
   say             => 1,                   # Aaleem Jiwa からの要求で、msg() と exp() 
                                           # メソッドはperl6の say コマンドのように振る舞う
                                           # (既定値はoff)が、 単にsay()メソッドを使った方が
                                           # 良い。
 });

 # 最小のインスタンス、ログファイル名はアプリケーションベース
 my $log = File::Log->new();

 # 標準的な使い方、デバッグレベルとログファイル名を指定(configファイルから指定)
 my $log = Log->new(debug => $debugLevel, logFileName => $logFileName,);

 # debug >= 2 の時にメッセージをログファイルに出力
 $log->msg(2, "Add this to the log file if debug >= 2 \n");

 # debug >= 2 の時にメッセージをログファイルに出力(perl6の流儀で)
 $log->say(2, "Add this to the log file if debug >= 2");

 # 例外(error)メッセージをログファイルに出力
 $log->exp("Something went wrong\n");

 # ログファイルをクローズ(終了時のオプション)
 $log->close();

 # デバッグレベルを変更し、古い値を取得
 $oldDebugValue     = $log->debugValue($newDebugValue);

 $currentDebugValue = $log->debugValue();

 # 全ての例外テキストを取得(そのため、全てのエラーで何か(たとえばメールの発信)ができる)
 $allExceptions     = $log->getExpText();

 $numberErrors      = $log->expCnt();        # $log->exp が何回呼ばれたか

説明

File::Log は、ファイルにデータをロギングするためのメソッドを提供するクラスである。 ログシステムの設定を変更するために、いくつかのパラメータを渡すことができる。

必要なモジュール

Carp (confess が必要), FindBin と Symbol;

メソッド

クラスメソッドはなく、以下のオブジェクトメソッドのみである。 プライベートなクラスメソッドは下線 '_' で始まり、Private として 扱われる。

new

<File::Log オブジェクトを生成するために呼ばれる。以下の、オプションの名前が付いた パラメータは無名ハッシュ(anonymous hash)を経由してコンストラクタに渡すことが できる。

debug

デバッグレベルを設定するのに使われる。既定値は 9 である。デバッグレベルは データがログに書き込まれるか否かを決定する、他のメソッドで使われる。 msgexp メソッドを参照のこと。

logFileName

ログを書き込むファイルの名前とパス名を定義する。もしも定義されていなければ、 appNameに'.log'を付加したものが使用される。もしもappNameがコンストラクタ中に 定義されていなければ、BinFindがアプリケーションの名前を定義するのに使われる。

logFileMode

ログファイルを、追加モードか上書きモードかにするかを決めるのに使う。 既定値は追加である。有効な値は、'>' が上書きモード、'>>'が追加モードである。

dateTimeStamp

もしも真ならば(既定値は偽)、msgexp メソッドにおいて、日付と時刻が 各々のエントリのデータの前に付加され、ログに書き込まれる。

stderrRedirect

もしも真ならば、(既定値は真)、STDERRがログファイルにリダイレクトされる。

defaultFile

もしも真ならば(既定値は偽)、選択されたログファイルは既定の出力ファイルになる。

logFileDateTime

もしも真ならば(既定値は偽)、ログファイルの、'.log' の前に、日付と時刻が付加 されたファイル名になる。日付と時刻の形式は、 _YYYYMMDD-HHMMSS である。

appName

もしもlogFileNameが未定義ならば、appNameはログファイル名のベースとして使用 される。もしもappNameが未定義ならば、FindBinモジュールが、アプリケーション の名前を決めるのに使われ、appNameハッシュ値に格納される。

PIDstamp

もしも真ならば(既定値は偽)、プロセスIDがmsgexp メソッドにおいて、 ログに書かれるデータの前に付加される。これは、同じログファイルに複数のプロ セスが書き込む場合に便利である。

storeExpText

もしも真ならば(既定値は偽)、expメソッドで書かれるデータは、getExpText メソッドであとで検索されるために内部に保存される。保存されたデータは、 clearExpTextメソッドで初期化することもできる。これは、もしも、1つの テキスト行として(ログファイル中以外に)複数の例外を報告したいという場合に 便利である。

msgprepend

もしも何か設定された場合(既定値はなにもなし)、msg()/exp()/say()メソッドに対し、 各メッセージの最後にその値を追加して渡す。

dateFormat

これが定義された場合、dateTimeStampと互換のある形式となる。

say

もしも真の場合(既定値は偽)、msg()とexp()メソッドに対し、渡されたメッセージの 最後に改行文字を追加する。(たぶん) より良いなアプローチは、msg()を遣うよりは say()を使う事である。

_init とプライベートメソッド

構成の時にオブジェクトを初期化するPrivate メソッドである。new() によって 呼ばれる。全ての Private メソッドは、 _ で始まり、 PRIVATE として扱わ れる。その他の、プライベートメソッドは文書化されていない(それがプライベートで あったとしても)。

msg

msg メソッドは、ログファイルにログメッセージを書き込むのに使用される。 msg の最初の POSITIONAL 引数は、"デバッグレベル" で、"デバッグレベル" が、インスタンスの"debug level"より等しいか小さい場合、ログファイルにメッセージ が追加される。

2番目とその後に続くオプショナルな引数は、ログファイルに出力されるテキストとして 扱われる。

例. $log->msg(2, "もしも 'debug' が2以上ならば、ログファイルに出力\n");

改行文字は、メソッドによって自動的に付加されないことに注意

exp

exp は例外を報告するのに使われる。これには"デバッグレベル"パラメータはなく、 ログファイルに出力される、1つまたはそれ以上のテキスト文字列のみである。 テキストは、各行の先頭に"**" が付加されるタイムスタンプまたはPID値の前に)。

改行文字は、メソッドによって自動的に付加されないことに注意

say

行の最後に'\n'が負荷されることを除いてmsgと同じである。

exp

expが例外を報告するのに遣われる。"デバッグレベル"パラメータはなく、 ログファイルに記録される1つ以上のテキスト文字列のみである。記録されるテキストは 各行の先頭に"**"が付加される(これは、タイムスタンプ又はPID値の前に付加される)。

改行文字は、メソッドによって自動的に付加されないことに注意

close

ログファイルのファイルハンドルをクローズする。

DESTROY

DESTROY は、ログファイルのファイルハンドルをクローズして定義する。

PIDstamp

PIDstamp メソッドは、PIDstampインスタンス値を取得したり設定するのに 使われる。もしも、パラメータ無しで呼ばれた場合には、現在のPIDstampインス タンス値が戻る。 もしも、パラメータ付きで呼ばれた場合、パラメータが、PIDstampインスタンス値 に設定され、古い値が戻る。

更なる情報は、newメソッドの情報を参照のこと。

dateTimeStamp

dateTimeStamp メソッドは、dateTimeStampインスタンス値を取得したり設定 するのに使われる。もしも、パラメータ無しで呼ばれた場合には、現在の dateTimeStampインスタンス値が戻る。 もしも、パラメータ付きで呼ばれた場合、パラメータが、dateTimeStampインス タンス値に設定され、古い値が戻る。

更なる情報は、newメソッドの情報を参照のこと。

debugValue

debugValue メソッドは、debugValueインスタンス値を取得したり設定するのに 使われる。もしも、パラメータ無しで呼ばれた場合には、現在のdebugValue インスタンス値が戻る。 もしも、パラメータ付きで呼ばれた場合、パラメータが、debugValueインスタンス 値に設定され、古い値が戻る。

更なる情報は、newメソッドの情報を参照のこと。

expText

expText メソッドは、expTextインスタンス値を取得したり設定するのに 使われる。もしも、パラメータ無しで呼ばれた場合には、現在のexpText インスタンス値が戻る。 もしも、パラメータ付きで呼ばれた場合、パラメータが、expTextインスタンス 値に設定され、古い値が戻る。

更なる情報は、newメソッドの情報を参照のこと。

getExpText

expText メソッドは、"Exception Text"インスタンスの値として格納された 値を検索するのに使われる。

clearExpText

clearExpText メソッドは、"Exception Text"インスタンスの値として格納さ れた、値を消去するのに使われる。

expCnt

expCnt メソッドは、このオブジェクトのために呼ばれた exp メソッドの回数 を検索するのに使われる。

getFileName

getFileName は、このオブジェクトのために使われた実際ののログファイル名を 検索するのに使われる。

プロパティ

new メソッドを参照のこと。

既知の問題

特にない。しかし、もしも何か問題を発見したら、gng@cpan.org に 連絡を下さい。可能な限りすみやかに調べて対応します。

もしも、何らかの拡張について助言があるのであれば、メールを下さい。 助言を試してみます。

new()メソッド内で 'say' を真に設定し、次に say()メソッドを使用すると 改行が重複する。

機能拡張要求/バグ

以下の方による、機能拡張の助言/バグ報告に感謝します。

 Aaleem Jiwa - say() メソッド
 Paul K - msgprepend と dateformat

作者

 Greg George, IT Technology Solutions P/L, Australia
 Mobile: +61-404-892-159, Email: gng@cpan.org

ライセンス

Copyright (c) 1999- Greg George. All rights reserved. このプログラムは、フリーソフトウェアである。Perlそれ自身と同じように 再配布、変更ができる。

CVS ID

$Id$

変更履歴

 $Log$
 Revision 1.1  2013/04/30 00:56:03  ribbon
 add new version File-Log-1.05/Log.pod

 Revision 1.5  2008/03/01 02:56:01  Greg
 - Updated Makefile.PL to include prereq for Encode as I was getting cpan tester errors. NO CODE CHANGES


 Revision 1.4  2008/02/26 08:54:31  Greg
 - Updated POD

 Revision 1.3  2007/07/17 11:23:49  Greg
 - Added say() method
 - Added say, msgprepend and dateFormat arguments to new()
 - Added pre close of STDERR

 Revision 1.2  2004/10/08 23:10:14  Greg
 - Changed new() to allow named argument as well as the anonymous hash reference.

 Revision 1.1.1.1  2004/07/29 11:15:06  Greg
 - Initial release to CPAN

翻訳者

  太田俊哉 <ribbon@users.sourceforge.jp>