Author: ericwilhelm
Date: Mon Sep 3 01:55:20 2007
New Revision: 9907
Modified:
Module-Build/trunk/t/lib/DistGen.pm
Log:
t/lib/DistGen.pm - allow import of undent(),
documentation, documentation, documentation
Modified: Module-Build/trunk/t/lib/DistGen.pm
==============================================================================
--- Module-Build/trunk/t/lib/DistGen.pm (original)
+++ Module-Build/trunk/t/lib/DistGen.pm Mon Sep 3 01:55:20 2007
@@ -2,7 +2,7 @@
use strict;
-use vars qw( $VERSION $VERBOSE );
+use vars qw( $VERSION $VERBOSE @EXPORT_OK);
$VERSION = '0.01';
$VERBOSE = 0;
@@ -24,6 +24,13 @@
VMS::Filespec->import;
}
}
+BEGIN {
+ require Exporter;
+ *{import} = \&Exporter::import;
+ @EXPORT_OK = qw(
+ undent
+ );
+}
sub new {
my $package = shift;
@@ -417,7 +424,10 @@
...
$dist->regen;
- chdir($dist->dirname) or die "Cannot chdir to '@{[$dist->dirname]}': $!";
+ chdir($dist->dirname) or
+ die "Cannot chdir to '@{[$dist->dirname]}': $!";
+ ...
+ $dist->clean;
...
chdir($cwd) or die "cannot return to $cwd";
$dist->remove;
@@ -428,78 +438,99 @@
=head3 new()
-Create a new distribution generator. Does not actually write the
-contents.
+Create a new object. Does not write its contents (see L</regen()>.)
+
+ my $tmp = MBTest->tmpdir;
+ my $dist = DistGen->new(
+ name => 'Foo::Bar',
+ dir => $tmp,
+ xs => 1,
+ );
+
+The parameters are as follows.
=over
=item name
The name of the module this distribution represents. The default is
-'Simple'.
+'Simple'. This should be a "Foo::Bar" (module) name, not a "Foo-Bar"
+dist name.
=item dir
-The directory in which to create the distribution directory. The
-default is File::Spec->curdir.
+The (parent) directory in which to create the distribution directory.
+The default is File::Spec->curdir. The distribution will be created
+under this according to the "dist" form of C<name> (e.g. "Foo-Bar".)
=item xs
-Generates an XS based module.
+If true, generates an XS based module.
=back
=head2 Manipulating the Distribution
-=head3 regen( [OPTIONS] )
-
-Regenerate all files that are missing or that have changed. If the
-optional C<clean> argument is given, it also removes any extraneous
-files that do not belong to the distribution.
+These methods immediately affect the filesystem.
-=over
+=head3 regen()
-=item clean
+Regenerate all missing or changed files.
-When true, removes any files not part of the distribution while
-regenerating.
+ $dist->regen(clean => 1);
-=back
+If the optional C<clean> argument is given, it also removes any
+extraneous files that do not belong to the distribution.
=head3 clean()
Removes any files that are not part of the distribution.
-=head3 revert( [$filename] )
+ $dist->clean;
+
+=begin TODO
+
+=head3 revert()
[Unimplemented] Returns the object to its initial state, or given a
$filename it returns that file to it's initial state if it is one of
the built-in files.
+ $dist->revert;
+ $dist->revert($filename);
+
+=end TODO
+
=head3 remove()
-Removes the complete distribution.
+Removes the entire distribution directory.
=head2 Editing Files
-Note that all ${filename}s should be specified with unix-style paths,
+Note that C<$filename> should always be specified with unix-style paths,
and are relative to the distribution root directory. Eg 'lib/Module.pm'
-=head3 add_file( $filename, $content )
+No filesystem action is performed until the distribution is regenerated.
+
+=head3 add_file()
-Add a $filename containg $content to the distribution. No action is
-performed until the distribution is regenerated.
+Add a $filename containg $content to the distribution.
-=head3 remove_file( $filename )
+ $dist->add_file( $filename, $content );
-Removes $filename from the distribution. No action is performed until
-the distribution is regenerated.
+=head3 remove_file()
-=head3 change_file( $filename, $content )
+Removes C<$filename> from the distribution.
+
+ $dist->remove_file( $filename );
+
+=head3 change_file()
Changes the contents of $filename to $content. No action is performed
until the distribution is regenerated.
+ $dist->change_file( $filename, $content );
+
=head2 Properties
=head3 name()
@@ -508,7 +539,21 @@
=head3 dirname()
-Returns the directory name where the distribution is created.
+Returns the directory where the distribution is created.
+
+ $dist->dirname; # e.g. t/_tmp/Simple
+
+=head2 Functions
+
+=head3 undent()
+
+Removes leading whitespace from a multi-line string according to the
+amount of whitespace on the first line.
+
+ my $string = undent(" foo(\n bar => 'baz'\n )");
+ $string eq "foo(
+ bar => 'baz'
+ )";
=cut
