NAME
MooseX::Types::NumUnit - Type(s) for using units in Moose
SYNOPSIS
package MyPackage
use Moose;
use MooseX::Types::NumUnit qw/NumUnit NumSI num_of_unit/;
has 'quantity' => ( isa => NumUnit, default => 0 );
has 'si_quantity' => ( isa => NumSI, required => 1 );
has 'length' => ( isa => num_of_unit('m'), default => '1 ft' );DESCRIPTION
This module provides types (NumUnit and friends) for Moose which represent physical units. More accurately it provides String to Number coercions, so that even if the user inputs a number with an incorrect (but compatible) unit, it will automatically coerce to a number of the correct unit.
A few things to note: since NumUnit and friends are subtypes of Num, a purely numerical value will not be coerced. This is by design, but should be kept in mind. Also NumUnit and friends are coerced by default (see "AUTOMATIC COERCION").
PACKAGE VARIABLES
$MooseX::Types::NumUnit::Verbose
When set to a true value, a string representing any conversion will be printed to STDERR during coercion.
TYPE-LIKE FUNCTIONS
Since version 0.02, MooseX::Types::NumUnit does not provide global types. Rather it has exportable type-like function which behave like types but do not pollute the "type namespace". While they behave like types, remember they are functions and they should not be quoted when called. They are null prototyped though, should they shouldn't (usually) need parenthesis. Futher they are not exported by default and must be requested. For more information about this system see MooseX::Types.
NumUnit
A subtype of Num which accepts a number with a unit, but discards the unit on coercion to a Num. This is the parent unit for all other units provided herein. Of course those have different coercions.
NumSI
A subtype of NumUnit which coerces to the SI equivalent of the unit passed in (i.e. a number in feet will be converted to a number in meters). In truth it is not strictly the SI equivalent, but whatever Physics::Unit thinks is the base unit. This should always be SI (I hope!).
ANONYMOUS TYPE GENERATORS
This module provides functions which return anonymous types which satisfy certain criteria. These functions may be exported on request, but are not exported by default. As of version 0.04, if a given unit has already been used to create a NumUnit subtype, it will be returned rather than creating a new subtype object.
num_of_unit( $unit )
Creates an anonymous type which has the given $unit. If a number is passed in which can be converted to the specified unit, it is converted on coercion. If the number cannot be converted, the value of the attribute is set to 0 and a warning is thrown.
num_of_si_unit_like( $unit )
Creates an anonymous type which has the SI equivalent of the given $unit. This is especially handy for composite units when you don't want to work out by hand what the SI base would be.
As a simple example, if $unit is 'ft', numbers passed in will be converted to meters! You see, the unit only helps specify the type of unit, however the SI unit is used. Another way to think of these types is as a resticted NumSI of a certian quantity, allowing a loose specification.
As with num_of_unit, if a number is passed in which can be converted to the specified (SI) unit, it is converted on coercion. If the number cannot be converted, the value of the attribute is set to 0 and a warning is thrown.
AUTOMATIC COERCION
Since the NumUnit types provided by this module are essentially just Num types with special coercions, it doesn't make sense to use them without coercions enabled on the attribute. To that end, this module mimics MooseX::AlwaysCoerce, with the exception that it only enables coercion on NumUnit and its subtypes. To prevent this, manually set coerce => 0 for a given attribute and it will be left alone, or better yet, just use Num as the type.
NOTES
This module defines the unit mm (millimeter) which Physics::Unit inexplicably lacks.
SEE ALSO
SOURCE REPOSITORY
http://github.com/jberger/MooseX-Types-NumUnit
AUTHOR
Joel Berger, <joel.a.berger@gmail.com>
COPYRIGHT AND LICENSE
Copyright (C) 2012 by Joel Berger
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.