/ 
Variable-Strongly-Typed-v1.0.0
River stage zero No dependents
/ Variable::Strongly::Typed

NAME

Variable::Strongly::Typed - Let some variables be strongly typed

VERSION

This document describes Variable::Strongly::Typed version 1.0.0

SYNOPSIS

use Variable::Strongly::Typed;

my $int             :TYPE('int');       # must have an 'int' value
my $float           :TYPE('float');     # must have a 'float' value
my $string          :TYPE('string');    # must not be a reference
my $file            :TYPE('IO::File');  # must be an IO::File
my @array_of_ints   :TYPE('int');       # Each slot must contain an int
my %hash_of_floats  :TYPE('float');     # Each value must be a float

my @array_of_rgb :TYPE(\&red_green_blue); # my enumerated type

# ... and later ...

$int = 23;          # All is well
$int = 'howdy!';    # This line will croak with a good error message

$float = 3.23;              # All is well, nothing to see here
$float = new XML::Parser;   # croak!

$array_of_ints[23] = 44;    # Groovy
$array_of_ints[12] = 'yah'; # croak!

$hash_of_floats{pi} = 3.14159;      # no problem
$hash_of_floats{e}  = new IO::File; # croak!

# Return 1 if this val is RED, BLUE, or GREEN
#   0 otherwise
sub red_green_blue {
    local $_ = shift;

    /\A RED \z/xms || /\A BLUE \z/xms || /\A GREEN \z/xms;
}

$array_of_my_very_own_types[23] = 99;       # croak!
$array_of_my_very_own_types[2] = 'BLUE';    # OK!

DESCRIPTION

This modules allow you to strongly type your variables.  Also known
as the 'no fun' module - it can greatly enhance you code's quality
and robustness.

By enforcing types on some (or all) of your variables you will eliminate
a large class of careless (& not so careless) errors.

This could also aid an editor or code-browsing tools to verify code 
correctness without having to execute the script.

INTERFACE

Variable types are specified using the 'TYPE' attribute.  There are 
currently 7 builtin types:

'int'       => /\A \d+ \z/xms;
'string'    => anything that's not a reference (!ref)
'float'     => standard float regex
'bool'      => same as 'int'
'SCALAR'    => unblessed scalar ref
'ARRAY'     => unblessed array ref
'HASH'      => unblessed hash ref

You can also specify a class name like 'XML::Parser' - note this is 
NOT the same as 'HASH' which represents an unblessed HASH reference.

Note when specifying 'XML::Parser' assigning 'XML::Parser' or any subclass of 
'XML::Parser' will be valid - it does a $value->isa('XML::Parser')
(or whatever the type you specified was) to test the value.

If you try to assign an illegal value to your variable the assignment will
croak with an informative error message.  Perhaps in the future there'll be
an option to only carp...

All builtin types allow 'undef' or any false value as a valid value.  Your
own types (see section below) should probably do the same.

ROLLING YOUR OWN TYPES

NOTE: You do NOT have to roll your own type to just specify a blessed
object - see the section above!

Specifying a CODE ref in your TYPE() attribute allows you to define your
own types.  Your function will be call with 1 parameter - the value that's
about to be assigned to any variable of that TYPE().

Returning 1 (or any true value) will allow the assignment to happen.
Return 0 (or any false value) will cause to assignment to croak.

I'm sure you can dream up of all sorts of interesting types -
enumerated types, all sorts of specific string types, bounded numbers,
words only from a specific language are the sorts of things that pop
into my mind.  Again I heartily expect you to surprise me with 
the types you come up with.

Note also you must allow for 'undef' as that is the initial value your
variable will have!  Allowing for any false value may also be a good idea.

DIAGNOSTICS

croak'ed error messages for built-in types look like:
    
  Cannot assign <value> to a [ scalar | hash | array ] of type <whatever>

croak'ed error messages for user-supplied types look like:
    
  Cannot assign <value> to a user-validated  [ scalar | hash | array ] variable

CONFIGURATION AND ENVIRONMENT

Variable::Strongly::Typed requires no configuration files or environment variables.

DEPENDENCIES

Attribute::Handlers handle the attribute stuff
Class::Std::Utils handle the basic 'inside-out' module work
Test::More for testing
version for versioning

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-perl-strongly-typed@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Mark Ethan Trostler <mark@zzo.com>

LICENCE AND COPYRIGHT

Copyright (c) 2005, Mark Ethan Trostler <mark@zzo.com>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.