Skip to content

Commit

Permalink
0.15 Some minor API tweaks:
Browse files Browse the repository at this point in the history
  • Loading branch information
mnunberg committed Jan 24, 2012
1 parent 1a3d862 commit 7f3d7a3
Show file tree
Hide file tree
Showing 6 changed files with 145 additions and 86 deletions.
15 changes: 10 additions & 5 deletions 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
2 changes: 2 additions & 0 deletions MANIFEST
Expand Up @@ -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
79 changes: 50 additions & 29 deletions 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
Expand Down Expand Up @@ -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");

Expand All @@ -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);
Expand Down Expand Up @@ -269,15 +271,15 @@ 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;
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;
Expand All @@ -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';
Expand Down Expand Up @@ -366,14 +368,17 @@ 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.
=head3 Basic Options
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>
Expand All @@ -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;
Expand Down Expand Up @@ -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.
Expand All @@ -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)];
Expand All @@ -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
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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
Expand All @@ -587,19 +592,21 @@ 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:
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",
;
Expand All @@ -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"];
Expand All @@ -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
Expand Down
56 changes: 56 additions & 0 deletions 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;
}
}
56 changes: 4 additions & 52 deletions 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;
}
}
1;

0 comments on commit 7f3d7a3

Please sign in to comment.