Commits

Toby Inkster committed 7f9f0ce

improve docs; reduce Perl version dependency to 5.000

  • Participants
  • Parent commits 9e4c2c5
  • Tags 0.003

Comments (0)

Files changed (1)

 package thanks;
 
-use 5.006;
+"
+use 5.000;
+";
 
 BEGIN {
 	$thanks::AUTHORITY = 'cpan:TOBYINK';
-	$thanks::VERSION   = '0.002';
+	$thanks::VERSION   = '0.003';
 }
 
 sub _module_notional_filename
 	my @caller = caller(0);
 	@_ = $caller[0] unless @_;
 	my $file = $caller[1];
-	for my $module (@_)
-		{ $INC{ _module_notional_filename($module) } = $file }
+	for (@_)
+		{ $INC{ _module_notional_filename($_) } = $file }
 }
 
 1;
 
 =head1 SYNOPSIS
 
-	no thanks 'strict';
-	use strict; # no-op
+	BEGIN {
+		package My::Package;
+		no thanks;
+		# everything else goes here
+	};
+	
+	use My::Package;  # No error message about missing
+	                  # file "My/Package.pm".
+	                  #
+
+=head1 ELEVATOR PITCH
+
+Defining multiple Perl packages in the same file can be fraught with
+difficulty. C<< no thanks >> makes it a bit easier. To define a package
+just do...
+
+	BEGIN {
+		package My::Package;
+		no thanks;
+		# everything else goes here
+	};
+
+Then everything should more or less work exactly if My::Package had
+been a package defined in an external file and loaded like:
+
+	use My::Package ();
+
+(The exception being that the inlined My::Package can see file-scoped
+lexicals.)
+
+Why define multiple packages in the same file? Because often namespacing
+concerns and code organisation concerns don't align. For example, you
+have many small packages which it is important don't share namespaces,
+but you want to be able to edit them all in the same window/tab of your
+editor.
 
 =head1 DESCRIPTION
 
 just adds an entry to that hash to trick Perl into thinking that a module
 has already been loaded.
 
+C<thanks> is a deliberately light-weight module. It has no dependencies (not
+even L<strict> or L<warnings>) and is believed to work in any release of Perl
+5. (The installation and testing scripts have more dependencies, but if push
+comes to shove, you can manually copy thanks.pm to an appropriate location.)
+
 =head2 Methods
 
 =over
 
 =back
 
-=head2 Use Case 1: You Really Want to Prevent a Module from Loading
-
-It's quite a messy thing to do, but if you really need to silently prevent
-a module from being loaded, then C<< no thanks >> will do the trick. Just
-make sure you do it early.
-
-This is almost always a bad idea.
-
-=head2 Use Case 2: Multiple Packages in the Same File
+=head2 Use Case 1: Multiple Packages in the Same File
 
 Perl's C<< use >> keyword muddies the distinction between packages (which
 are just namespaces) and modules (which are just files). Sometimes you wish
 then this will prevent C<< use My::Package::Helper >> from throwing an error
 message, provided C<< My/Package.pm >> is already loaded.
 
+=head2 Use Case 2: You Really Want to Prevent a Module from Loading
+
+It's quite a messy thing to do, but if you really need to silently prevent
+a module from being loaded, then C<< no thanks >> will do the trick. Just
+make sure you do it early.
+
+This is almost always a bad idea.
+
 =head1 BUGS
 
 Please report any bugs to