=encoding utf-8

=head1 NAME

=begin original

File::pushd - change directory temporarily for a limited scope

=end original

File::pushd - スコープ内での一時的なディレクトリの変更

=head1 VERSION

=begin original

This documentation describes version 1.00.

=end original

このドキュメントはバージョン 1.00について述べたものです.

=head1 SYNOPSIS

=begin original

  use File::pushd;

  chdir $ENV{HOME};

  # change directory again for a limited scope
  {
      my $dir = pushd( '/tmp' );
      # working directory changed to /tmp
  }
  # working directory has reverted to $ENV{HOME}

  # tempd() is equivalent to pushd( File::Temp::tempdir )
  {
      my $dir = tempd();
  }

  # object stringifies naturally as an absolute path
  {
     my $dir = pushd( '/tmp' );
     my $filename = File::Spec->catfile( $dir, "somefile.txt" );
     # gives /tmp/somefile.txt
  }

=end original

  use File::pushd;

  chdir $ENV{HOME};

  # スコープ内でディレクトリを変更します
  {
      my $dir = pushd( '/tmp' );
      # working directory changed to /tmp
  }
  # 作業ディレクトリは $ENV{HOME}に戻ります

  # tempd()は pushd( File::Temp::tempdir )と等価です.
  {
      my $dir = tempd();
  }

  # オブジェクトの文字列化すると絶対パスが得られます
  {
     my $dir = pushd( '/tmp' );
     my $filename = File::Spec->catfile( $dir, "somefile.txt" );
     # /tmp/somefile.txt が得られます
  }

=head1 DESCRIPTION

=begin original

File::pushd does a temporary C<<< chdir >>> that is easily and automatically
reverted, similar to C<<< pushd >>> in some Unix command shells.  It works by
creating an object that caches the original working directory.  When the object
is destroyed, the destructor calls C<<< chdir >>> to revert to the original working
directory.  By storing the object in a lexical variable with a limited scope,
this happens automatically at the end of the scope.

This is very handy when working with temporary directories for tasks like
testing; a function is provided to streamline getting a temporary
directory from L<File::Temp>.

For convenience, the object stringifies as the canonical form of the absolute
pathname of the directory entered.

=end original

File::pushdは簡単な方法で一時的に C<<< chdir >>>し, 自動的に元に戻します.
これは Unixコマンドの C<<< pushd >>>と類似しています.
これはオブジェクトを作成し, オリジナルの作業ディレクトリをキャッシュします.
そしてオブジェクトが破棄されるとき, デストラクタは C<<< chdir >>>を呼び出し,
元の作業ディレクトリへと戻ります.
オブジェクトをスコープ中のレキシカル変数に格納することで, スコープ終了時に,
このことが自動的に行われます.

これはテストのようなテンポラリディレクトリで作業を行う場合に便利です.
L<File::Temp>からテンポラリディレクトリの取得を能率的に行う機能を提供します.

便宜上, オブジェクトを文字列化した場合,
移動したディレクトリの絶対パスの標準形が得られます.

=head1 USAGE

=begin original

  use File::pushd;

Using File::pushd automatically imports the C<<< pushd >>> and C<<< tempd >>> functions.

=head2 pushd

  {
      my $dir = pushd( $target_directory );
  }

Caches the current working directory, calls C<<< chdir >>> to change to the target
directory, and returns a File::pushd object.  When the object is
destroyed, the working directory reverts to the original directory.

The provided target directory can be a relative or absolute path. If
called with no arguments, it uses the current directory as its target and
returns to the current directory when the object is destroyed.

=head2 tempd

  {
      my $dir = tempd();
  }

This function is like C<<< pushd >>> but automatically creates and calls C<<< chdir >>> to
a temporary directory created by L<File::Temp>. Unlike normal L<File::Temp>
cleanup which happens at the end of the program, this temporary directory is
removed when the object is destroyed. (But also see C<<< preserve >>>.)  A warning
will be issued if the directory cannot be removed.

=head2 preserve

  {
      my $dir = tempd();
      $dir->preserve;      # mark to preserve at end of scope
      $dir->preserve(0);   # mark to delete at end of scope
  }

Controls whether a temporary directory will be cleaned up when the object is
destroyed.  With no arguments, C<<< preserve >>> sets the directory to be preserved.
With an argument, the directory will be preserved if the argument is true, or
marked for cleanup if the argument is false.  Only C<<< tempd >>> objects may be
marked for cleanup.  (Target directories to C<<< pushd >>> are always preserved.)
C<<< preserve >>> returns true if the directory will be preserved, and false
otherwise.

=end original

  use File::pushd;

File::pushdを useすると, C<<< pushd >>>と C<<< tempd >>>
関数が自動的にインポートされます.

=head2 pushd

  {
      my $dir = pushd( $target_directory );
  }

現在の作業ディレクトリをキャッシュし,
目的のディレクトリに切り替えるために C<<< chdir >>>を呼び出し,
そして File::pushdオブジェクトを返します.
オブジェクトが破棄されるとき, 作業ディレクトリを元のディレクトリに戻します.

引数として与えるディレクトリは相対パスでも, 絶対パスでも指定できます.
もし引数がなければ, カレントディレクトリをターゲットして使用し,
オブジェクトが破棄されたときにカレントディレクトリに戻ります.

=head2 tempd

  {
      my $dir = tempd();
  }

この関数は C<<< pushd >>>と似ていますが, L<File::Temp>により,
テンポラリディレクトリを作成し, そのディレクトリに C<<< chdir >>>します.
通常の L<File::Temp>のプログラム終了時のクリーンアップと異なり,
このテンポラリディレクトリは, オブジェクトが破棄されたときに削除されます.
(C<<< preserve >>>も参照してください.)
ディレクトリを削除することができない場合は, 警告が発せされます.

=head2 preserve

  {
      my $dir = tempd();
      $dir->preserve;      # mark to preserve at end of scope
      $dir->preserve(0);   # mark to delete at end of scope
  }

オブジェクトが破棄される場合に, ディレクトリを削除するかどうかについての制御を行います.
引数なしの場合, C<<< preserve >>>はディレクトリを保存するように設定します.
引数ありの場合, 引数が真であればディレクトリを保存し,
偽であれば削除するようにマークします.
C<<< tempd >>>オブジェクトであれば削除するようマークします.
(ターゲットディレクトリへの C<<< pushd >>>であれば, 常に保存されます.)
ディレクトリを保存するようにできれば C<<< preserve >>>は真を返し,
その他の場合は偽を返します.

=head1 SEE ALSO

=over

=item *

L<File::chdir>

=back

=head1 BUGS

=begin original

Please report any bugs or feature using the CPAN Request Tracker.
Bugs can be submitted through the web interface at
L<http://rt.cpan.org/Dist/Display.html?Queue=File-pushd>

When submitting a bug or request, please include a test-file or a patch to an
existing test-file that illustrates the bug or desired feature.

=end original

バグ, 機能に関するレポートについては CPAN Request Trackerを利用してください.
バグについては Webインタフェースで投稿することもできます.
L<http://rt.cpan.org/Dist/Display.html?Queue=File-pushd>

バグ, 機能について投稿を行う際は, バグ, 機能を説明するためのテストファイルか,
既存のテストファイルに対するパッチファイルを含めるようにしてください.

=head1 AUTHOR

David A. Golden (DAGOLDEN)

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2005, 2006, 2007 by David A. Golden

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
L<http://www.apache.org/licenses/LICENSE-2.0>

Files produced as output though the use of this software, including
generated copies of boilerplate templates provided with this software,
shall not be considered Derivative Works, but shall be considered the
original work of the Licensor.

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

=cut