add a tlperl.straw directory for public inspection

git-svn-id: svn://tug.org/texlive/trunk@17235 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 145 insertions, 0 deletions

diff --git a/Master/tlpkg/tlperl.straw/lib/File/pushd.pod b/Master/tlpkg/tlperl.straw/lib/File/pushd.pod
new file mode 100755
index 00000000000..068fa4b1e77
--- /dev/null
+++ b/Master/tlpkg/tlperl.straw/lib/File/pushd.pod
@@ -0,0 +1,145 @@
+# Generated by Pod::WikiDoc version 0.17
+
+=pod
+
+=head1 NAME
+
+File::pushd - change directory temporarily for a limited scope
+
+=head1 VERSION
+
+This documentation describes version 1.00.
+
+=head1 SYNOPSIS
+
+  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
+  }
+
+=head1 DESCRIPTION
+
+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.
+
+=head1 USAGE
+
+  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.
+
+=head1 SEE ALSO
+
+=over
+
+=item *
+
+L<File::chdir>
+
+=back
+
+=head1 BUGS
+
+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.
+
+=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.
+
+