validate_card() is a new synonym for validate(), starting a long-term plan to stop...

diff --git a/Changes b/Changes
index c8870e0..e35a8e9 100644 (file)
--- a/Changes
+++ b/Changes
@@ -1,5 +1,10 @@
 Revision history for Perl extension Business::CreditCard.
 
+0.36  unreleased
+        - Allow (and doc) import of receipt_cardtype
+        - validate_card() is a new synonym for validate(), starting a long-term
+          plan to stop exporting validate() or anything else by default.
+
 0.35  Tue Feb  9 14:43:38 PST 2016
         - Fix bug identifying 49* Visa cards introduced in 0.34, patch from
           Ed J, thanks!

diff --git a/CreditCard.pm b/CreditCard.pm
index 8d5dcbb..ed18b08 100644 (file)
--- a/CreditCard.pm
+++ b/CreditCard.pm
@@ -1,11 +1,15 @@
 package Business::CreditCard;
 
 require Exporter;
-use vars qw( @ISA $VERSION $Country );
+use vars qw( @ISA $VERSION @EXPORT @EXPORT_OK %EXPORT_TAGS $Country );
 
 @ISA = qw( Exporter );
 
-$VERSION = "0.35";
+$VERSION = "0.36_01";
+
+@EXPORT = qw( cardtype validate generate_last_digit );
+@EXPORT_OK = qw( receipt_cardtype validate_card );
+$EXPORT_TAGS{NEW} = qw( validate_card cardtype receipt_cardtype );
 
 $Country = 'US';
 
@@ -114,6 +118,15 @@ cardtype().
 
 Use this for receipt display/printing only.
 
+Note: this subroutine is not exported by default like the others.
+Before 0.36, you needed to call this subroutine fully-qualified, as
+Business::CreditCard::receipt_cardtype()
+
+In 0.36 and later, you can import it into your namespace:
+
+  use Business::CreditCard qw( :DEFAULT receipt_cardtype );
+
+
 =head1 ORIGINAL AUTHOR
 
 Jon Orwant
@@ -152,6 +165,41 @@ how to change things to behave in a more modern fashion without breaking
 existing code?  "use Business::CreditCard <some_minimum_version>" turns it off?
 Explicitly ask to turn it off and list that in the SYNOPSIS?
 
+=head2 validate() and @EXPORT transition plan
+
+First (done in 0.36): 
+
+validate_card() is the new name for validate().  Both work for now.
+
+New-style usage (not recommended for code that needs to support B:CC before 0.36):
+
+  use Business::CreditCard qw( :NEW );
+
+You get validate_card(), cardtype() and receipt_cardtype().  You can also ask
+for them explicitly / individually:
+
+  use Business::CreditCard qw( validate_card cardtype receipt_cardtype );
+
+
+Second (we're at now now): 
+
+Waiting for 0.36+ to become more prevalent.
+
+
+Third:
+
+Recommend new-style usage.
+
+
+Fourth:
+ (this is the incompatible part):
+
+Don't export validate() (or anything else [separately?]) by default.
+
+This is the part that will break things and we probably won't do for a long
+time, until new-style usage is the norm and the tradeoff of breaking old code
+is worth it to stop or namespace pollution.
+
 =head1 SEE ALSO
 
 L<Business::CreditCard::Object> is a wrapper around Business::CreditCard
@@ -166,8 +214,6 @@ providing credit card number verification (LUHN checking).
 
 =cut
 
-@EXPORT = qw(cardtype validate generate_last_digit);
-
 ## ref http://neilb.org/reviews/luhn.html#Comparison it looks like
 ## Business::CCCheck is 2x faster than we are.  looking at their implementation
 ## not entirely a fair comparison, we also do the equivalent of their CC_clean,
@@ -298,7 +344,10 @@ sub generate_last_digit {
 #  }
 #  $type = '' if $ccn % 10;
 #  return $type;
-sub validate {
+
+sub validate { validate_card(@_); }
+
+sub validate_card {
     # Allow use as a class method
     shift if UNIVERSAL::isa( $_[0], 'Business::CreditCard' );