From 7f3d7a379017cf30439cb05bdfe1d70a9a4fb6ee Mon Sep 17 00:00:00 2001
From: Mark Nunberg <mnunberg@haskalah.org>
Date: Tue, 24 Jan 2012 00:04:48 -0800
Subject: [PATCH] 0.15    Some minor API tweaks:

        added 'dualvar' option, fixed POD errors,
        changed ::Stringified to ::Dualvar

        https://rt.cpan.org/Ticket/Display.html?id=74247
        https://rt.cpan.org/Ticket/Display.html?id=74249
        https://rt.cpan.org/Ticket/Display.html?id=74235
---
 Changes                              | 15 ++++--
 MANIFEST                             |  2 +
 lib/Constant/Generate.pm             | 79 ++++++++++++++++++----------
 lib/Constant/Generate/Dualvar.pm     | 56 ++++++++++++++++++++
 lib/Constant/Generate/Stringified.pm | 56 ++------------------
 t/99-api_revision.t                  | 23 ++++++++
 6 files changed, 145 insertions(+), 86 deletions(-)
 create mode 100644 lib/Constant/Generate/Dualvar.pm
 create mode 100644 t/99-api_revision.t

diff --git a/Changes b/Changes
index cba541e..28e1846 100644
--- a/Changes
+++ b/Changes
@@ -1,9 +1,14 @@
 Revision history for Constant-Generate
 
-0.01    Date/time
-        First version, released on an unsuspecting world.
+0.15    Some minor API tweaks:
+        added 'dualvar' option, fixed POD errors,
+        changed ::Stringified to ::Dualvar
+        
+        https://rt.cpan.org/Ticket/Display.html?id=74247
+        https://rt.cpan.org/Ticket/Display.html?id=74249
+        https://rt.cpan.org/Ticket/Display.html?id=74235
 
-0.04    Updated dependency for constant.pm
-0.10    Stringy options, listings
-0.11    Fixed some documentation
 0.12	Explained listings a bit better
+0.11    Fixed some documentation
+0.10    Stringy options, listings
+0.04    Updated dependency for constant.pm
diff --git a/MANIFEST b/MANIFEST
index 73b6d9e..a8924da 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -4,11 +4,13 @@ Makefile.PL
 README
 lib/Constant/Generate.pm
 lib/Constant/Generate/Stringified.pm
+lib/Constant/Generate/Dualvar.pm
 
 t/00-all.t
 t/01-strings.t
 t/02-dualvar.t
 t/03-listings.t
 t/99-synopsis.t
+t/99-api_revision.t
 
 test.pl
diff --git a/lib/Constant/Generate.pm b/lib/Constant/Generate.pm
index b351fce..da4f432 100644
--- a/lib/Constant/Generate.pm
+++ b/lib/Constant/Generate.pm
@@ -1,11 +1,11 @@
 package Constant::Generate;
 use strict;
 use warnings;
-our $VERSION  = '0.12';
+our $VERSION  = '0.15';
 
 use Data::Dumper;
 use Carp qw(confess);
-use Constant::Generate::Stringified;
+use Constant::Generate::Dualvar;
 use Scalar::Util qw(looks_like_number);
 
 #these two functions produce reverse mapping, one for simple constants, and
@@ -186,7 +186,9 @@ sub import {
 	my $prefix			= _getopt(%opts, "prefix") || "";
 	my $display_prefix 	= _getopt(%opts, "show_prefix");
 	my $start 			= _getopt(%opts, "start_at") || 0;
-	my $stringy			= _getopt(%opts, "stringy_vars");
+	my $stringy			= _getopt(%opts, "stringy_vars")
+						|| _getopt(%opts, "dualvar");
+						
 	my $listname		= _getopt(%opts, "allvalues");
 	my $symsname		= _getopt(%opts, "allsyms");
 	
@@ -208,7 +210,7 @@ sub import {
 			
 			my $dv_name = $display_prefix ? $prefix . $symname : $symname;
 			
-			$symval = Constant::Generate::Stringified::CG_dualvar(
+			$symval = Constant::Generate::Dualvar::CG_dualvar(
 				$symval, $dv_name);
 		}
 		_gen_constant($reqpkg, $prefix.$symname, $symval);
@@ -269,7 +271,7 @@ Simplest use
 	
 Bitflags:
 
-	use Constant::Generate [qw(ANNOYING STRONG LAZY)], type => 'bitflags';
+	use Constant::Generate [qw(ANNOYING STRONG LAZY)], type => 'bits';
 	my $state = (ANNOYING|LAZY);
 	$state & STRONG == 0;
 
@@ -277,7 +279,7 @@ With reverse mapping:
 
 	use Constant::Generate
 		[qw(CLIENT_IRSSI CLIENT_XCHAT CLIENT_PURPLE)],
-		type => "bitflags",
+		type => "bits",
 		mapname => "client_type_to_str";
 	
 	my $client_type = CLIENT_IRSSI | CLIENT_PURPLE;
@@ -296,19 +298,19 @@ Generate reverse maps, but do not generate values. also, push to exporter
 		O_WRONLY => 01,
 		O_RDWR	 => 02,
 		O_CREAT  => 0100
-	}, tag => "openflags", -type => 'bits';
+	}, tag => "openflags", type => 'bits';
 	
 	my $oflags = O_RDWR|O_CREAT;
 	print openflags_to_str($oflags); #prints 'O_RDWR|O_CREAT';
 	
 DWIM Constants
 
-	use Constant::Generate::Stringified {
+	use Constant::Generate {
 		RDONLY	=> 00,
 		WRONLY	=> 01,
 		RDWR	=> 02,
 		CREAT	=> 0100
-	}, -prefix => 'O_';
+	}, prefix => 'O_', dualvar => 1;
 	
 	my $oflags = O_RDWR|O_CREAT;
 	O_RDWR eq 'RDWR';
@@ -366,7 +368,7 @@ By default, symbols are assumed to correlate to a single independent integer val
 and any reverse mapping performed will only ever map a symbol value to a single
 symbol name.
 
-For bitflags, it is possible to specify C<type => 'bitfield'> in the L</Options>
+For bitflags, it is possible to specify C<type =E<gt> 'bits'> in the L</Options>
 which will modify the auto-generation of the constants as well as provide
 suitable output for reverse mapping functions.
 
@@ -374,6 +376,9 @@ suitable output for reverse mapping functions.
 
 The second argument to the import function is a hash of options.
 
+All options may be prefixed by a dash (C<-option>) or in their 'bare' form
+(C<option>).
+
 =over
 
 =item C<type>
@@ -395,7 +400,7 @@ This specifies the starting value for the
 first constant of the enumeration. If the enumeration is a bitfield, then the
 value is a factor by which to left-shift 1, thus
 	
-	use Constant::Generate [qw(OPT_FOO OPT_BAR)], type => "bitfield";
+	use Constant::Generate [qw(OPT_FOO OPT_BAR)], type => "bits";
 	
 	OPT_FOO == 1 << 0;
 	OPT_BAR == 1 << 1;
@@ -456,7 +461,7 @@ With auto-prefixing:
 When prefixes are specified, the default is that reverse mapping functions will
 display only the 'bare', user-specified name. Thus:
 
-	use Constant::Generate [qw( FOO )], -prefix => "MY_", -mapname => "const_str";
+	use Constant::Generate [qw( FOO )], prefix => "MY_", mapname => "const_str";
 	const_str(MY_FOO) eq 'FOO';
 	
 Setting C<show_prefix> to a true value will display the full name.
@@ -473,14 +478,15 @@ or using C<Constant::Generate::Stringified>:
 
 =item C<stringy_vars>
 
+=item C<dualvar>
+
 This will apply some trickery to the values returned by the constant symbols.
 
 Normally, constant symbols will return only their numeric value, and a reverse
 mapping function is needed to retrieve the original symbolic name.
 
-When C<stringy_vars> is set to a true value, OR if one C<use>s
-C<Constant::Generate::Stringified>, the values returned by the constant subroutine
-will do the right thing in string and numeric contexts; thus:
+When C<dualvar> is set to a true value the values returned by the constant
+subroutine will do the right thing in string and numeric contexts; thus:
 
 	use Constant::Generate::Stringified [qw(FOO BAR)];
 	
@@ -490,14 +496,13 @@ will do the right thing in string and numeric contexts; thus:
 The L</show_prefix> option controls whether the prefix is part of the stringified
 form.
 
-Do not rely too much on C<stringy_vars> to magically convert any number into
+Do not rely too much on C<dualvar> to magically convert any number into
 some meaningful string form. In particular, it will only work on scalars which
 are directly descended from the constant symbols. Paritcularly, this means that
 unpack()ing or receiving data from a different process will not result in these
 special stringy variables.
 
-It is an error to use both C<stringy_vars> as an option to
-C<Constant::Generate::Stringified>
+The C<stringy_vars> is an alias to C<dualvar>
 
 =back
 
@@ -527,9 +532,9 @@ Or something potentially more useful:
 		HICCUP
 		ZOMBIES
 		)],
-	-type => 'bit',
-	-allvalues => 'symptoms',
-	-mapname => "symptom_str";
+	type => 'bits',
+	allvalues => 'symptoms',
+	mapname => "symptom_str";
 	
 	my $remedies = {
 		COUGH, "Take some honey",
@@ -573,7 +578,7 @@ exporter parameters is quite hairy, and the export options can natually
 be a bit tricky.
 
 In order to succesfully export symbols made by this module, you must specify
-either C<-export_ok> or C<-export> as hash options to C<import>. These correspond
+either C<export_ok> or C<export> as hash options to C<import>. These correspond
 to the like-named variables documented by L<Exporter>.
 
 Additionally, export tags can be specified only if one of the C<export> flags is
@@ -587,8 +592,9 @@ Nicest way:
 	our (@EXPORT, %EXPORT_TAGS);
 	use Constant::Generate
 		[qw(FOO BAR BAZ)],
-		-export => 1,
-		-tag => "some_constants"
+		
+		export => 1,
+		tag => "some_constants"
 	;
 	
 A bit more explicit:
@@ -596,10 +602,11 @@ A bit more explicit:
 	use base qw(Exporter);
 	use Constant::Generate
 		[qw(FOO BAR BAZ)],
-		-export => \our @EXPORT,
-		-export_tags => \our %EXPORT_TAGS,
-		-tag => "some_constants",
-		-mapname => "some_constants_to_str",
+		
+		export => \our @EXPORT,
+		export_tags => \our %EXPORT_TAGS,
+		tag => "some_constants",
+		mapname => "some_constants_to_str",
 	;
 
 
@@ -612,7 +619,7 @@ Or DIY
 		@SYMS = qw(FOO BAR BAZ);
 	}
 	
-	use Constant::Generate \@SYMS, -mapname => "some_constants_to_str";
+	use Constant::Generate \@SYMS, mapname => "some_constants_to_str";
 	
 	push @EXPORT, @SYMS, "some_constants_to_str";
 	$EXPORT_TAGS{'some_constants'} = [@SYMS, "some_constants_to_str"];
@@ -624,6 +631,20 @@ Also note that any L</allvalues>, L</allsyms>, or L</mapname>
 subroutines will be exported according
 to whatever specifications were configured for the constants themselves.
 
+=head2 NOTES
+
+The C<dualvar> or C<stringy_var> option can be short-handed by doing the following:
+
+	use Constant::Generate::Dualvar [qw(
+		FOO
+		BAR
+		BAZ
+	)], prefix => 'MY_';
+	
+	MY_FOO eq 'FOO';
+	
+etc.
+
 =head1 BUGS & TODO
 
 It's somewhat ironic that a module which aims to promote the use of symbolic
diff --git a/lib/Constant/Generate/Dualvar.pm b/lib/Constant/Generate/Dualvar.pm
new file mode 100644
index 0000000..8105e44
--- /dev/null
+++ b/lib/Constant/Generate/Dualvar.pm
@@ -0,0 +1,56 @@
+package Constant::Generate::Dualvar::_Overloaded;
+use constant {
+    FLD_INT => 0,
+    FLD_STR => 1
+};
+#Stolen from:
+#http://perldoc.perl.org/overload.html
+
+sub new { my $p = shift; bless [@_], $p }
+use overload '""' => \&str, '0+' => \&num, fallback => 1;
+sub num {shift->[0]}
+sub str {shift->[1]}
+
+
+BEGIN {
+    $INC{'Constant/Generate/Dualvar/_Overloaded.pm'} = 1;
+}
+
+package Constant::Generate::Dualvar;
+use strict;
+use warnings;
+use Scalar::Util;
+use base qw(Exporter);
+
+our @EXPORT_OK = qw(CG_dualvar);
+our $USE_SCALAR_UTIL;
+
+sub CG_dualvar($$);
+
+BEGIN {
+    $USE_SCALAR_UTIL = eval 'use List::Util::XS 1.20; $List::Util::XS::VERSION;';
+    if($USE_SCALAR_UTIL) {
+        *CG_dualvar = \&Scalar::Util::dualvar;
+    } else {
+        require Constant::Generate::Stringified::_Overloaded;
+        warn "Scalar::Util::XS not available. Falling back to using overload";
+        *CG_dualvar = sub($$) {
+            my ($num,$string) = @_;
+            return Constant::Generate::Stringified::_Overloaded->new(
+                $num,$string);
+        }
+    }
+}
+
+sub import {
+    my ($cls,$symspec,%options) = @_;
+    if($symspec) {
+        #We're being imported as user..
+        require 'Constant/Generate.pm';
+        $options{dualvar} = 1;
+        @_ = ('Constant::Generate', $symspec, %options);
+        goto &Constant::Generate::import;
+    } else {
+        goto &Exporter::import;
+    }
+}
\ No newline at end of file
diff --git a/lib/Constant/Generate/Stringified.pm b/lib/Constant/Generate/Stringified.pm
index 7667285..ee9fddb 100644
--- a/lib/Constant/Generate/Stringified.pm
+++ b/lib/Constant/Generate/Stringified.pm
@@ -1,56 +1,8 @@
-package Constant::Generate::Stringified::_Overloaded;
-use constant {
-    FLD_INT => 0,
-    FLD_STR => 1
-};
-#Stolen from:
-#http://perldoc.perl.org/overload.html
-
-sub new { my $p = shift; bless [@_], $p }
-use overload '""' => \&str, '0+' => \&num, fallback => 1;
-sub num {shift->[0]}
-sub str {shift->[1]}
-
-
-BEGIN {
-    $INC{'Constant/Generate/Stringified/_Overloaded.pm'} = 1;
-}
-
 package Constant::Generate::Stringified;
-use strict;
-use warnings;
-use Scalar::Util;
-use base qw(Exporter);
+require Constant::Generate::Dualvar;
 
-our @EXPORT_OK = qw(CG_dualvar);
-our $USE_SCALAR_UTIL;
-
-sub CG_dualvar($$);
-
-BEGIN {
-    $USE_SCALAR_UTIL = eval 'use List::Util::XS 1.20; $List::Util::XS::VERSION;';
-    if($USE_SCALAR_UTIL) {
-        *CG_dualvar = \&Scalar::Util::dualvar;
-    } else {
-        require Constant::Generate::Stringified::_Overloaded;
-        warn "Scalar::Util::XS not available. Falling back to using overload";
-        *CG_dualvar = sub($$) {
-            my ($num,$string) = @_;
-            return Constant::Generate::Stringified::_Overloaded->new(
-                $num,$string);
-        }
-    }
+sub import {
+    goto &Constant::Generate::Dualvar::import;
 }
 
-sub import {
-    my ($cls,$symspec,%options) = @_;
-    if($symspec) {
-        #We're being imported as user..
-        require 'Constant/Generate.pm';
-        $options{stringy_vars} = 1;
-        @_ = ('Constant::Generate', $symspec, %options);
-        goto &Constant::Generate::import;
-    } else {
-        goto &Exporter::import;
-    }
-}
\ No newline at end of file
+1;
\ No newline at end of file
diff --git a/t/99-api_revision.t b/t/99-api_revision.t
new file mode 100644
index 0000000..458b661
--- /dev/null
+++ b/t/99-api_revision.t
@@ -0,0 +1,23 @@
+#!/usr/bin/perl
+use strict;
+use warnings;
+use Test::More;
+
+use Constant::Generate [qw(FOO)],
+    dualvar => 1, -prefix => 'STR_';
+    
+ok(STR_FOO == 0 && STR_FOO eq 'FOO',
+   "dualvar option");
+
+use Constant::Generate::Dualvar [qw(GRR GAH)],
+    prefix => 'STR_';
+    
+ok(STR_GRR == 0 && STR_GRR eq 'GRR',
+   "Constant::Generate::Dualvar");
+
+use Constant::Generate::Stringified [qw(MEH)], prefix => 'STR_';
+
+ok(STR_MEH == 0 && STR_MEH eq 'MEH',
+   "Constant::Generate::Stringified back-compat");
+
+done_testing();
\ No newline at end of file