=encoding utf8

=head1 NAME

Path::Class::File - ファイルのオブジェクト表現

=head1 SYNOPSIS

  use Path::Class qw(file);  # 短いコンストラクタのエクスポート
  
  my $file = file('foo', 'bar.txt');  # Path::Class::Fileオブジェクト
  my $file = Path::Class::File->new('foo', 'bar.txt'); # 同様
  
  # Unixでは'foo/bar.txt'、Windowsでは'foo\bar.txt'などに文字列化
  print "file: $file\n";
  
  if ($file->is_absolute) { ... }
  
  my $v = $file->volume; # Windowsでは'C:'、Unixではから文字列、
                         # Mac OSでは'Macintosh HD:'など
  
  $file->cleanup; # パスネームの論理的なクリーンナップ
  
  my $dir = $file->dir;  # Path::Class::Dirオブジェクト
  
  my $abs = $file->absolute; # 絶対パスへの変換
  my $rel = $file->relative; # 相対パスへの変換

=head1 DESCRIPTION

C<Path::Class::File>クラスはクロス・プラットフォームな方法でのファイル名の操作のための機能を含みます。

=head1 METHODS

=over 4

=item $file = Path::Class::File->new( <dir1>, <dir2>, ..., <file> )

=item $file = file( <dir1>, <dir2>, ..., <file> )

新しいC<Path::Class::File>オブジェクトを生成し、これを返します。
引数でファイルへのパスを指定します。
何らかのボリュームを最初の引数で、あるいは最初の引数の一部分で指定することができます。
プラットフォーム－ニュートラルな記述：

  my $dir = file( 'foo', 'bar', 'baz.txt' );

あるいは、プラットフォーム－ネイティブな記述：

  my $dir = dir( 'foo/bar/baz.txt' );

あるいは、この二つの混合ができます：

  my $dir = dir( 'foo/bar', 'baz.txt' );

上の三つの例はいずれも、相対パスを生成します。
絶対パスを生成するには、プラットフォーム－ネイティブな次のような記述：

  my $dir = dir( '/var/tmp/foo.txt' );

または最初の引数としてから文字列を記述します：

  my $dir = dir( '', 'var', 'tmp', 'foo.txt' );

二番目の形式は不恰好に見えるとすれば、それは意図的なことです - 最初に挙げたC</var/tmp>あるいはC<\Windows>のようなパスはクロスプラットフォームのコンセプトではなく、もしあなたがコードをクロスプラットフォームにしようとしているなら、おそらくその中に現れるべきではありません。
これが設定ファイル、ユーザ入力、その他から与えられるのであれば、最初の形態はあらゆる意味ですばらしいものです。

=item $file->stringify

このメソッドはC<Path::Class::File>が文字列コンテクストで使われたときに自動的に呼ばれるもので、したがって以下は同じことになります：

  $string = $file->stringify;
  $string = "$file";

=item $file->volume

このオブジェクトにボリューム（例えば、WindowsではC<C:>、Mac OSではC<Macintosh HD:>など）があれば、それを返します。
そうでなければ、空文字列を返します。

=item $file->basename

ファイル名を、ディレクトリ部分（あれば）抜きの文字列で返します。

=item $file->is_dir

このオブジェクトがディレクトリをあらわしているか、boolean（真偽）値で返します。
当然のことですが、C<Path::Class::File>は常にfalseを返しますし、C<Path::Class::Dir>は常にtrueを返します。

=item $file->is_absolute

ファイルが絶対パス指定（C</usr/local/foo.txt>やC<\Windows\Foo.txt>のように）を指しているか否かに応じて、trueかfalseを返します。

=item $file->cleanup

ファイルパスの論理的なクリーンナップを行います。例えば：

  my $file = file('/foo//baz/./foo.txt')->cleanup;
  # $fileは'/foo/baz/foo.txt'をあらわします;

=item $dir = $file->dir

このファイルを含むディレクトリをあらわすC<Path::Class::Dir>オブジェクトを返します。

=item $dir = $file->parent

C<dir()>メソッドの別名です。

=item $abs = $file->absolute

C<$file>を絶対パスであらわしたC<Path::Class::File>オブジェクトを返します。
追加引数として、文字列かC<Path::Class::Dir>オブジェクトで、相対パスのベースとして使われるディレクトリを指定することができます。
指定しなかった時は、現在のワーキング・ディレクトリが使われます。

=item $rel = $file->relative

C<$file>を相対パスであらわしたC<Path::Class::File>オブジェクトを返します。
追加引数として、文字列かC<Path::Class::Dir>オブジェクトで、相対パスのベースとして使われるディレクトリを指定することができます。
指定しなかった時は、現在のワーキング・ディレクトリが使われます。

=item $foreign = $file->as_foreign($type)

C<$file>をC<$type>タイプのシステムで指定した場合のC<Path::Class::File>オブジェクトを返します。
既知のタイプにはC<Unix>、C<Win32>、C<Mac>、C<VMS>、そしてC<OS2>、つまりC<File::Spec>にサブクラスがあるすべてのものが含まれます。

生成されたオブジェクト（サブディレクトリ、ファイル、親ディレクトリなど）はこのタイプを保持します。

=item $foreign = Path::Class::File->new_foreign($type, @args)

C<$file>をC<$type>タイプのシステムで指定した場合のC<Path::Class::File>オブジェクトを返します。
既知のタイプにはC<Unix>、C<Win32>、C<Mac>、C<VMS>、そしてC<OS2>、つまりC<File::Spec>にサブクラスがあるすべてのものが含まれます。

C<@args>に含まれる引数は、C<new()>で指定されるものと同じです。

=item $fh = $file->open($mode, $permissions)

C<$file>を含む与えられた引数すべてをC<< IO::File->new >>に渡し（この順番でC<< IO::File->open >>が呼ばれます）、その結果をC<IO::File>オブジェクトとして返します。
openが失敗すると、C<undef>が返されC<$!>がセットされます。

=item $fh = $file->openr()

以下を行うためのショートカットです。

 $fh = $file->open('r') or die "Can't read $file: $!";

=item $fh = $file->openw()

以下を行うためのショートカットです。

 $fh = $file->open('w') or die "Can't write $file: $!";

=item $file->touch

与えられたファイルが存在すれば、その更新時刻をアクセス時刻をたった今にセットします。存在しない時は、C<touch()>は存在I<するようにします> - YES! - その更新時刻とアクセス時刻は居間にセットされます。

=item $file->slurp()

スカラコンテキストでは、C<$file>の内容を文字列で返します。リストコンテキストでは、C<$file>の内容を（C<$/>の設定内容に応じて）行ごとのリストとして返します。ファイルを読めなかった時は、このメソッドは例外を投げます。

ファイルの各行に対してC<chomp()>を行いたいときには、C<chomp>またはC<chomped>パラメータにtrueの値を渡してください：

  my @lines = $file->slurp(chomp => 1);

=item $file->remove()

このメソッドはどのプラットフォームあれできるだけうまく行く方法でファイルの削除を試み、ファイル削除に成功したか否かをboolean値で返します。

C<remove()>は単純にPerlのC<unlink()>関数を呼ぶよりよい方法です。
というのは、いくつかのプラットホーム（特記すべきものとしてはVMS）では、実際にはファイルの全バージョンがなくなるまでC<unlink()>を複数回呼ばなければならないからです。
C<remove()>メソッドは、このプロセスを行ってくれます。

=item $st = $file->stat()

このファイルに対するC<< File::stat::stat() >>を呼び出し、その結果を示すC<File::stat>オブジェクトを返します。

=item $st = $file->lstat()

C<stat()>と同じですが、C<$file>がシンボリックリンクの時は、C<lstat()>はリンクの指すファイルの代わりにリンクのstatを行います。

=back

=head1 AUTHOR

Ken Williams, ken@mathforum.org

=head1 SEE ALSO

Path::Class, Path::Class::Dir, File::Spec

=head1 DOCUMENT TRANSLATION

Makio Tsukamoto, tsukamoto@gmail.com

=cut