NAME
Reindeer - Moose with more antlers
VERSION
This document describes version 0.017 of Reindeer - released March 03,
2014 as part of Reindeer.
SYNOPSIS
# ta-da!
use Reindeer;
# ...is the same as:
use Moose;
use MooseX::MarkAsMethods autoclean => 1;
use MooseX::AlwaysCoerce;
use MooseX::AttributeShortcuts;
# etc, etc, etc
DESCRIPTION
Like Moose? Use MooseX::* extensions? Maybe some MooseX::Types
libraries? Hate that you have to use them in every. Single. Class.
Reindeer aims to resolve that :) Reindeer _is_ Moose -- it's just Moose
with a number of the more useful/popular extensions already applied.
Reindeer is a drop-in replacement for your "use Moose" line, that
behaves in the exact same way... Just with more pointy antlers.
EARLY RELEASE!
Be aware this package should be considered early release code. While
Moose and all our incorporated extensions have their own classifications
(generally GA or "stable"), this bundling is still under active
development, and more extensions, features and the like may still be
added.
That said, my goal here is to increase functionality, not decrease it.
When this package hits GA / stable, I'll set the release to be >= 1.000.
NEW CLASS METHODS
with_traits()
This method allows you to easily compose a new class with additional
traits:
my $foo = Bar->with_traits('Stools', 'Norm')->new(beer => 1, tab => undef);
(See also MooseX::Traits.)
NEW ATTRIBUTE OPTIONS
Unless specified here, all options defined by Moose::Meta::Attribute and
Class::MOP::Attribute remain unchanged.
For the following, "$name" should be read as the attribute name; and the
various prefixes should be read using the defaults
coerce => 0
Coercion is ENABLED by default; explicitly pass "coerce => 0" to
disable.
(See also MooseX::AlwaysCoerce.)
lazy_require => 1
The reader methods for all attributes with that option will throw an
exception unless a value for the attributes was provided earlier by a
constructor parameter or through a writer method.
(See also MooseX::LazyRequire.)
is => 'rwp'
Specifying "is => 'rwp'" will cause the following options to be set:
is => 'ro'
writer => "_set_$name"
is => 'lazy'
Specifying "is => 'lazy'" will cause the following options to be set:
is => 'ro'
builder => "_build_$name"
lazy => 1
NOTE: Since 0.009 we no longer set "init_arg => undef" if no "init_arg"
is explicitly provided. This is a change made in parallel with Moo,
based on a large number of people surprised that lazy also made one's
"init_def" undefined.
is => 'lazy', default => ...
Specifying "is => 'lazy'" and a default will cause the following options
to be set:
is => 'ro'
lazy => 1
default => ... # as provided
That is, if you specify "is => 'lazy'" and also provide a "default",
then we won't try to set a builder, as well.
builder => 1
Specifying "builder => 1" will cause the following options to be set:
builder => "_build_$name"
clearer => 1
Specifying "clearer => 1" will cause the following options to be set:
clearer => "clear_$name"
or, if your attribute name begins with an underscore:
clearer => "_clear$name"
(that is, an attribute named "_foo" would get "_clear_foo")
predicate => 1
Specifying "predicate => 1" will cause the following options to be set:
predicate => "has_$name"
or, if your attribute name begins with an underscore:
predicate => "_has$name"
(that is, an attribute named "_foo" would get "_has_foo")
trigger => 1
Specifying "trigger => 1" will cause the attribute to be created with a
trigger that calls a named method in the class with the options passed
to the trigger. By default, the method name the trigger calls is the
name of the attribute prefixed with "_trigger_".
e.g., for an attribute named "foo" this would be equivalent to:
trigger => sub { shift->_trigger_foo(@_) }
For an attribute named "_foo":
trigger => sub { shift->_trigger__foo(@_) }
This naming scheme, in which the trigger is always private, is the same
as the builder naming scheme (just with a different prefix).
builder => sub { ... }
Passing a coderef to builder will cause that coderef to be installed in
the class this attribute is associated with the name you'd expect, and
"builder => 1" to be set.
e.g., in your class,
has foo => (is => 'ro', builder => sub { 'bar!' });
...is effectively the same as...
has foo => (is => 'ro', builder => '_build_foo');
sub _build_foo { 'bar!' }
isa => ..., constraint => sub { ... }
Specifying the constraint option with a coderef will cause a new subtype
constraint to be created, with the parent type being the type specified
in the "isa" option and the constraint being the coderef supplied here.
For example, only integers greater than 10 will pass this attribute's
type constraint:
# value must be an integer greater than 10 to pass the constraint
has thinger => (
isa => 'Int',
constraint => sub { $_ > 10 },
# ...
);
Note that if you supply a constraint, you must also provide an "isa".
isa => ..., constraint => sub { ... }, coerce => 1
Supplying a constraint and asking for coercion will "Just Work", that
is, any coercions that the "isa" type has will still work.
For example, let's say that you're using the "File" type constraint from
MooseX::Types::Path::Class, and you want an additional constraint that
the file must exist:
has thinger => (
is => 'ro',
isa => File,
constraint => sub { !! $_->stat },
coerce => 1,
);
"thinger" will correctly coerce the string "/etc/passwd" to a
"Path::Class:File", and will only accept the coerced result as a value
if the file exists.
coerce => [ Type => sub { ...coerce... }, ... ]
Specifying the coerce option with a hashref will cause a new subtype to
be created and used (just as with the constraint option, above), with
the specified coercions added to the list. In the passed hashref, the
keys are Moose types (well, strings resolvable to Moose types), and the
values are coderefs that will coerce a given type to our type.
has bar => (
is => 'ro',
isa => 'Str',
coerce => [
Int => sub { "$_" },
Object => sub { 'An instance of ' . ref $_ },
],
);
NEW KEYWORDS (SUGAR)
In addition to all sugar provided by Moose (e.g. has, with, extends), we
provide a couple new keywords.
class_type ($class, ?$options)
Creates a new subtype of "Object" with the name $class and the metaclass
Moose::Meta::TypeConstraint::Class.
# Create a type called 'Box' which tests for objects which ->isa('Box')
class_type 'Box';
By default, the name of the type and the name of the class are the same,
but you can specify both separately.
# Create a type called 'Box' which tests for objects which ->isa('ObjectLibrary::Box');
class_type 'Box', { class => 'ObjectLibrary::Box' };
(See also Moose::Util::TypeConstraints.)
role_type ($role, ?$options)
Creates a "Role" type constraint with the name $role and the metaclass
Moose::Meta::TypeConstraint::Role.
# Create a type called 'Walks' which tests for objects which ->does('Walks')
role_type 'Walks';
By default, the name of the type and the name of the role are the same,
but you can specify both separately.
# Create a type called 'Walks' which tests for objects which ->does('MooseX::Role::Walks');
role_type 'Walks', { role => 'MooseX::Role::Walks' };
(See also Moose::Util::TypeConstraints.)
class_has => (...)
Exactly like "has" in Moose, but operates at the class (rather than
instance) level.
(See also MooseX::ClassAttribute.)
default_for
default_for() is a shortcut to extend an attribute to give it a new
default; this default value may be any legal value for default options.
# attribute bar defined elsewhere (e.g. superclass)
default_for bar => 'new default';
... is the same as:
has '+bar' => (default => 'new default');
abstract
abstract() allows one to declare a method dependency that must be
satisfied by a subclass before it is invoked, and before the subclass is
made immutable.
abstract 'method_name_that_must_be_satisfied';
requires
requires() is a synonym for abstract() and works in the way you'd
expect.
OVERLOADS
It is safe to use overloads in your Reindeer classes and roles; they
will work just as you expect: overloads in classes can be inherited by
subclasses; overloads in roles will be incorporated into consuming
classes.
(See also MooseX::MarkAsMethods)
AVAILABLE OPTIONAL ATTRIBUTE TRAITS
We export the following trait aliases. These traits are not
automatically applied to attributes, and are lazily loaded (e.g. if you
don't use them, they won't be loaded and are not dependencies).
They can be used by specifying them as:
has foo => (traits => [ TraitAlias ], ...);
AutoDestruct
has foo => (
traits => [ AutoDestruct ],
is => 'ro',
lazy => 1,
builder => 1,
ttl => 600,
);
Allows for a "ttl" attribute option; this is the length of time (in
seconds) that a stored value is allowed to live; after that time the
value is cleared and the value rebuilt (given that the attribute is lazy
and has a builder defined).
See MooseX::AutoDestruct for more information.
CascadeClearing
This attribute trait allows one to designate that certain attributes are
to be cleared when certain other ones are; that is, when an attribute is
cleared that clearing will be cascaded down to other attributes. This is
most useful when you have attributes that are lazily built.
See MooseX::CascadeClearing for more information and a significantly
more cogent description.
ENV
This is a Moose attribute trait that you use when you want the default
value for an attribute to be populated from the %ENV hash. So, for
example if you have set the environment variable USERNAME to 'John' you
can do:
package MyApp::MyClass;
use Moose;
use MooseX::Attribute::ENV;
has 'username' => (is=>'ro', traits=>['ENV']);
package main;
my $myclass = MyApp::MyClass->new();
print $myclass->username; # STDOUT => 'John';
This is basically similar functionality to something like:
has 'attr' => (
is=>'ro',
default=> sub {
$ENV{uc 'attr'};
},
);
If the named key isn't found in %ENV, then defaults will execute as
normal.
See MooseX::Attribute::ENV for more information.
MultiInitArg
has 'data' => (
traits => [ MultiInitArg ],
is => 'ro',
isa => 'Str',
init_args => [qw(munge frobnicate)],
);
This trait allows your attribute to be initialized with any one of
multiple arguments to new().
See MooseX::MultiInitArg for more information.
UndefTolerant
Applying this trait to your attribute makes it's initialization tolerant
of of undef. If you specify the value of undef to any of the attributes
they will not be initialized (or will be set to the default, if
applicable). Effectively behaving as if you had not provided a value at
all.
package My:Class;
use Moose;
use MooseX::UndefTolerant::Attribute;
has 'bar' => (
traits => [ UndefTolerant ],
is => 'ro',
isa => 'Num',
predicate => 'has_bar'
);
# Meanwhile, under the city...
# Doesn't explode
my $class = My::Class->new(bar => undef);
$class->has_bar # False!
See MooseX::UndefTolerant::Attribute for more information.
INCLUDED EXTENSIONS
Reindeer includes the traits and sugar provided by the following
extensions. Everything their docs say they can do, you can do by default
with Reindeer.
MooseX::AbstractMethod
MooseX::AlwaysCoerce
MooseX::AttributeShortcuts
MooseX::ClassAttribute
MooseX::CurriedDelegation
MooseX::LazyRequire
MooseX::MarkAsMethods
Note that this causes any overloads you've defined in your class/role to
be marked as methods, and namespace::autoclean invoked.
MooseX::NewDefaults
MooseX::StrictConstructor
MooseX::Traits
This provides a new class method, "with_traits()", allowing you to
compose traits in on the fly:
my $foo = Bar->with_traits('Stools')->new(...);
INCLUDED TYPE LIBRARIES
MooseX::Types::Moose
MooseX::Types::Common::String
MooseX::Types::Common::Numeric
MooseX::Types::LoadableClass
MooseX::Types::Path::Class
MooseX::Types::Tied::Hash::IxHash
OTHER
Non-Moose specific items made available to your class/role:
Perl v5.10 features
If you're running on v5.10 or greater of Perl, Reindeer will
automatically enable v5.10 features in the consuming class.
namespace::autoclean
Technically, this is done by MooseX::MarkAsMethods, but it's worth
pointing out here. Any overloads present in your class/role are marked
as methods before autoclean is unleashed, so Everything Will Just Work
as Expected.
Path::Class
use Path::Class;
my $dir = dir('foo', 'bar'); # Path::Class::Dir object
my $file = file('bob', 'file.txt'); # Path::Class::File object
# Stringifies to 'foo/bar' on Unix, 'foo\bar' on Windows, etc.
print "dir: $dir\n";
# Stringifies to 'bob/file.txt' on Unix, 'bob\file.txt' on Windows
print "file: $file\n";
my $subdir = $dir->subdir('baz'); # foo/bar/baz
my $parent = $subdir->parent; # foo/bar
my $parent2 = $parent->parent; # foo
my $dir2 = $file->dir; # bob
# Work with foreign paths
use Path::Class qw(foreign_file foreign_dir);
my $file = foreign_file('Mac', ':foo:file.txt');
print $file->dir; # :foo:
print $file->as_foreign('Win32'); # foo\file.txt
# Interact with the underlying filesystem:
# $dir_handle is an IO::Dir object
my $dir_handle = $dir->open or die "Can't read $dir: $!";
# $file_handle is an IO::File object
my $file_handle = $file->open($mode) or die "Can't read $file: $!";
See the Path::Class documentation for more detail.
Try::Tiny
You can use Try::Tiny's "try" and "catch" to expect and handle
exceptional conditions, avoiding quirks in Perl and common mistakes:
# handle errors with a catch handler
try {
die "foo";
} catch {
warn "caught error: $_"; # not $@
};
You can also use it like a standalone "eval" to catch and ignore any
error conditions. Obviously, this is an extreme measure not to be
undertaken lightly:
# just silence errors
try {
die "foo";
};
See the Try::Tiny documentation for more detail.
CAVEAT
This author is applying his own assessment of "useful/popular
extensions". You may find yourself in agreement, or violent disagreement
with his choices. YMMV :)
ACKNOWLEDGMENTS
Reindeer serves largely to tie together other packages -- Moose
extensions and other common modules. Those other packages are largely by
other people, without whose work Reindeer would have a significantly
smaller rack.
We also use documentation as written for the other packages pulled in
here to help present a cohesive whole.
SEE ALSO
Please see those modules/websites for more information related to this
module.
* Moose, and all of the above-referenced packages.
SOURCE
The development version is on github at
<http://github.com/RsrchBoy/reindeer> and may be cloned from
<git://github.com/RsrchBoy/reindeer.git>
BUGS
Please report any bugs or feature requests on the bugtracker website
https://github.com/RsrchBoy/reindeer/issues
When submitting a bug or request, please include a test-file or a patch
to an existing test-file that illustrates the bug or desired feature.
AUTHOR
Chris Weyl <cweyl@alumni.drew.edu>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2011 by Chris Weyl.
This is free software, licensed under:
The GNU Lesser General Public License, Version 2.1, February 1999