=encoding utf8

=head1 NAME

Path::Class::Dir - ディレクトリのオブジェクト表現

=head1 SYNOPSIS

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

  # IO::Dirメソッドによるイテレート:
  my $handle = $dir->open;
  while (my $file = $handle->read) {
    $file = $dir->file($file);  # Turn into Path::Class::File object
    ...
  }
  
  # Path::Classメソッドによるイテレート:
  while (my $file = $dir->next) {
    # $fileはPath::Class::FileまたはPath::Class::Dirオブジェクト
    ...
  }


=head1 DESCRIPTION

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

=head1 METHODS

=over 4

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

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

C<Path::Class::Dir>オブジェクトを生成し、これを返します。
この引数では、連結されて単一のディレクトリオブジェクトを生成するのに使われるディレクトリ名を指定します。
何らかのボリュームを最初の引数で、あるいは最初の引数の一部分で指定することができます。
プラットフォーム－ニュートラルな記述：

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

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

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

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

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

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

  my $dir = dir( '/var/tmp' );

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


  my $dir = dir( '', 'var', 'tmp' );

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

特別なケースとして、有用でありこの方法で定義できると便利だからという以外の意味はありませんが、C<< Path::Class::Dir->new() >>（あるいはC<dir()>）は現在のディレクトリ（C<< File::Spec->curdir >>）を指します。現在のディレクトリを絶対パスで得るには、C<< dir()->absolute >>とします。

=item $dir->stringify

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

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

=item $dir->volume

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

=item $dir->is_dir

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

=item $dir->is_absolute

ディレクトリが絶対パス指定（C</usr/local>やC<\Windows>のように）を指しているか否かに応じて、trueかfalseを返します。

=item $dir->cleanup

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

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

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

C<$dir>またはこのサブディレクトリの一つの中のものをあらわすC<Path::Class::File>オブジェクトを返します。
内部的には、C<< Path::Class::File->new( @_ ) >>を呼ぶだけです。

=item $subdir = $dir->subdir( <dir1>, <dir2>, ... )

C<$dir>のサブディレクトリをあらわす新しいC<Path::Class::Dir>オブジェクトを返します。

=item $parent = $dir->parent

C<$dir>の親ディレクトリを返します。
これはI<論理的な>親であり、必ずしも物理的な親であるとは限らないことに注意指定下さい。
実際に意味するのは、これいじょう切り落とせなくなるまで、ディレクトリリストの末端からエントリを切り落とすというだけです。
もしディレクトリが相対であれば、親ディレクトリの相対での形式を使用するところから始めます。

以下のコードは絶対及び相対ディレクトリの振る舞いのデモンストレーションです：

  $dir = dir('/foo/bar');
  for (1..6) {
    print "Absolute: $dir\n";
    $dir = $dir->parent;
  }
  
  $dir = dir('foo/bar');
  for (1..6) {
    print "Relative: $dir\n";
    $dir = $dir->parent;
  }
  
  ########### Output on Unix ################
  Absolute: /foo/bar
  Absolute: /foo
  Absolute: /
  Absolute: /
  Absolute: /
  Absolute: /
  Relative: foo/bar
  Relative: foo
  Relative: .
  Relative: ..
  Relative: ../..
  Relative: ../../..

=item @list = $dir->children

このディレクトリ内のオブジェクトをリストアップし、C<Path::Class::File>およびC<Path::Class::Dir>のリスト、またはスカラコンテキストではその数として返します。
分かりきったことですが、子を検索するためにはC<$dir>が存在し、読み込み可能であることが必要です。

子はC<$dir>のサブディレクトリとして、つまりF<foo>の子はF<bar>やF<baz>ではなく、F<foo/bar>やF<foo/baz>として返されることに注意してください。

基本的に、C<children()>はI<self>とI<parent>にあたるエントリーのC<.>やC<..>（あるいは非Unixシステムのこれにあたるもの）を含みません。
これはI'm-my-own-grandpaビジネスのようなものですから。
これらの特別なものを含むディレクトリ・エントリが欲しいのであれば、C<all>にtrueの値を渡してください：

  @c = $dir->children(); # 子のみ
  @c = $dir->children(all => 1); # 全てのエントリ

=item $abs = $dir->absolute

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

=item $rel = $dir->relative

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

=item $boolean = $dir->subsumes($other)

ディレクトリ指定が、他方のディレクトリ指定に含まれているものであればtrueを、そうでなければfalseを返します。
"subsumes"は"contains"だと考えることもできますが、C<$dir>が実際にファイルシステム上でC<$other>を含んでいるかではなく、I<指定>だけを見ています。

C<$other>引数はC<Path::Class::Dir>オブジェクト、C<Path::Class::File>オブジェクト、文字列のどれでもかまいません。
最後のケースでは、これをディレクトリであると仮定します。

  # 例:
  dir('foo/bar' )->subsumes(dir('foo/bar/baz'))  # True
  dir('/foo/bar')->subsumes(dir('/foo/bar/baz')) # True
  dir('foo/bar' )->subsumes(dir('bar/baz'))      # False
  dir('/foo/bar')->subsumes(dir('foo/bar'))      # False


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

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

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

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

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

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

=item @list = $dir->dir_list([OFFSET, [LENGTH]])

このディレクトリ構成を内部的に示す文字列のリストを返します。
リストのそれぞれの連続したメンバーは、その前のもののディレクトリリストのエントリーだと理解されます。
約束として、C<< Path::Class->new( $dir->dir_list ) >>はC<$dir>と等価です。

このメソッドの意味合いはPerlのC<splice>またはC<substr>関数に類似しています；C<OFFSET>から初めてC<LENGTH>個の要素を返します。
C<LENGTH>が省略されると、C<OFFSET>からリストの最後までのすべての要素を返します。
C<LENGTH>がマイナスであれば、C<OFFSET>より前方の末尾C<-LENGTH>個の要素を返します。
C<OFFSET>がマイナスであれば、リストの末尾からC<OFFSET>個の要素を数えます。
C<OFFSET>とC<LENGTH>が両方とも省略されると、全体のリストを返します。

スカラコンテキストでは、引数なしのC<dir_list()>はディレクトリリストのエントリの個数を返します；
C<dir_list(OFFSET)>は個のオフセット位置の要素一つを返します；
C<dir_list(OFFSET, LENGTH)>はリストコンテキストで返された要素の最後のものを返します。

=item $fh = $dir->open()

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

=item $dir->mkpath($verbose, $mode)

C<$dir>を含む与えられた引数すべてをC<< File::Path::mkpath() >>に渡し、結果（作成されたすべてのディレクトリ）を返します。

=item $dir->rmtree($verbose, $cautious)

C<$dir>を含む与えられた引数すべてをC<< File::Path::rmtree() >>に渡し、結果（削除に成功したファイル数）を返します。

=item $dir->remove()

ディレクトリを削除しますが、空であることが必要です。
ディレクトリの削除に成功したか否かを示すboolean（真偽）値を返します。
このメソッドは主に、C<Path::Class::File>のC<remove()>メソッドとの一貫性のために提供されます。

=item $dir_or_file = $dir->next()

ディレクトリのコンテンツ一通りにイテレート（反復）を行うのに便利な方法です。
最初にC<next()>が呼ばれると、ディレクトリをC<open()>し、ここから最初のアイテムを読み込み、結果をC<Path::Class::Dir>またはC<Path::Class::File>（もちろん、実際のタイプがどちらかによります）で返します。
以降のC<next()>呼び出しは、ディレクトリ内のコンテンツに対して単に反復され、ディレクトリ内にそれ以上のアイテムがなくなると、未定義値が返されます。
ディレクトリ内の通常ファイルすべてに対してイテレートをする例です：

  while (my $file = $dir->next) {
    next unless -f $file;
    my $fh = $file->open('r') or die "Can't read $file: $!";
    ...
  }

ディレクトリを開く際にエラー（例えば存在しないか読み取り不可）が発生すると、C<next()>はC<$!>の値とともに例外を投げます。

=item $dir->recurse( callback => sub {...} )

このディレクトリと、全ての子、全ての子の子、etc.に対して反復して、それぞれのエントリに対するC<callback>サブルーチンの呼び出しを行います。
これは多くの点でC<File::Find>モジュールが行うことに似ており、もちろんC<File::Find>はC<Path::Class>オブジェクト上でもよく動作しますが、C<recurse()>メソッドにはコールバック・サブルーチンに単なるパス名の文字列ではなくC<Path::Class>オブジェクトを送るという利点があります。

C<recurse()>メソッドは各エントリに対して呼び出されるサブルーチンがC<callback>パラメータで指定されることを要求します。
これはC<Path::Class>オブジェクトを第一引数として渡されます。

C<recurse()>はさらに二つの再起処理順をコントロールするbooleanパラメータ、C<depthfirst>とC<preorder>を受け取ることができます。
デフォルトはpreorderで、横型探索、つまりC<< depthfirst => 0, preorder => 1 >>です。
これを書いている時点では、C<< depthfirst => 0, preorder => 0 >>をI<除く>全ての両パラメータの組み合わせがサポートされています。

=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::File, File::Spec

=head1 DOCUMENT TRANSLATION

Makio Tsukamoto, tsukamoto@gmail.com

=cut