NAME

Reindeer - Moose with more antlers

VERSION

This document describes version 0.014 of Reindeer - released August 31, 2012 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!' }

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' };

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' };

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.

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:

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 stanalone 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.

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 is free software, licensed under:

The GNU Lesser General Public License, Version 2.1, February 1999

To install Reindeer, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Reindeer

CPAN shell

perl -MCPAN -e shell
install Reindeer

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)