=pod

=for comment
DO NOT EDIT. This Pod was generated by Swim.
See http://github.com/ingydotnet/swim-pm#readme

=encoding utf8

=head1 NAME

Moos - Moo s{imple,peedy,ingle}

=for html
<a href="https://travis-ci.org/ingydotnet/moos-pm"><img src="https://travis-ci.org/ingydotnet/moos-pm.png" alt="moos-pm"></a>
<a href="https://coveralls.io/r/ingydotnet/moos-pm?branch=master"><img src="https://coveralls.io/repos/ingydotnet/moos-pm/badge.png" alt="moos-pm"></a>

=head1 SYNOPSIS

    package Foos;
    use Moos;

    extends 'Boos';
    with 'Cloos';

    has this => ();
    has that => 42;
    has other => (
        builder => 'build_other',
        lazy => 1,
    );

    sub BUILD {
        my $self = shift;
        # build, build, build
    }

    sub BUILDARGS {
        my ($self, @args) = @_;
        # munge, munge, munge
        return {%munged_args};
    }

=head1 DESCRIPTION

Moos completes the M to Moose sequence of Perl OO modules.

This one is pure Perl, single file and mostly Moose compatible (for what it
does). Moos has no non-core dependencies, but certain features (roles,
debugging functions, legacy Perl support) do require additional modules. If
you steer away from those features, you don't need those additional modules.

=head1 FEATURES

Here's a quick list of the L<Moose> compatible features that are supported
by L<Moos>.

=head2 strict/warnings

Turns on C<strict> and C<warnings> for you.

=head2 Helpful exports

The ever useful C<blessed> (from L<Scalar::Util>) and C<confess> (from
L<Carp>) are exported to your namespace.

=head2 extends

For inheritance. C<Moos::Object> is the default base class.

    package MyClass;
    extends 'MyBaseClass';

Supports multiple inheritance, by allowing multiple classes on a single
invocation.

=head2 with

Moos can consume roles using the C<with> keyword. Using this feature requires
L<Role::Tiny> to be installed.

    with 'ThisClass', 'ThatClass';

=head2 has

Accessor generator. Supports the C<is>, C<default>, C<build>, C<lazy>,
C<clearer>, C<predicate>, C<required>, C<handles> and C<trigger> options,
described below. The supported options are about the same as Moose. Other
arguments (e.g. C<isa> and C<coerce>) are currently ignored.

    has this => ();

NOTE: Class::XSAccessor will be used for simple accessors if it is installed.
      This can be disabled by setting $Moos::CAN_HAZ_XS to false or by setting
      the PERL_MOOS_XS_DISABLE to true.

=over

=item is

Specify which type of attribute accessor to provide. The default is "rw", a
read-write accessor. Read-only "ro" accessors are also supported.

    has this => ( is => "ro" );
    has 'this';                   # read-write
    has that => ();               # read-write

Unlike Moose, Moos cannot generate differently named getters and setters. If
you want your setter named something different (e.g. a private method), then
you could do something like:

    has this => ( is => 'ro' );
    sub _set_this { $_[0]{this} = $_[1] }

=item required

Require that a value for the attribute be provided to the constructor or
generated during object construction.

    has this => ( required => 1 );

=item lazy

Don't generate defaults during object construction.

    has this => ( builder => '_build_this', lazy => 1 );

=item trigger

A coderef which will be called when the attribute is assigned to via a method
call or the constructor. (But not when an attribute is implicitly given a
value via a default or builder.) The coderef is called with the instance as
the first parameter, the new value as the second parameter, and the old value
(if any) as the third parameter.

    has age => ( trigger => sub {
        croak "non-numeric age" unless looks_like_number($_[1]);
    } );

Triggers can be used to emulate Moose's type constraints, coercion and
weakened reference features, but if you find yourself doing this frequently
then you should consider upgrading to Moo or Moose.

=item handles

Delegated method calls.

    has wheels => (handles => [qw/ roll /]);

This accepts a hashref or arrayref, but not the other possibilities offered
by L<Moose>.

=item builder

Specify the method name to generate a default value.

    has this => ( builder => '_build_this' );
    has that => ( builder => 1 );  # accept default name for method

=item default

Specify the sub to generate a default value.

    has this => ( default => sub { 42 } );

Moos provides a shortcut for specifying the default. If the number of
arguments (after the name) is an odd number, then the first argument is the
default. The following forms are valid:

    has a => 42;
    has b => 'string' => (lazy => 1);
    has c => {};
    has d => [1, 2, 3, 4];

These all result in creating a Moos C<default> argument. If the default is an
array or hash reference, a shallow copy is made.

=item clearer

Creates a clearer method.

    has this => ( clearer => "clear_this" );
    has that => ( clearer => 1 );  # accept default name for method

=item predicate

Creates a predicate method, which can be used to check if the attribute is
set or unset.

    has this => ( predicate => "has_this" );
    has that => ( predicate => 1 );  # accept default name for method

=back

=head2 Class and Object Methods

=over

=item new

A constructor class method.

    my $object = MyClass->new(this => 'nice', that => 2);

=item BUILD

Custom object construction. If you define BUILD, it is passed the value of the
new object during construction. You can modify the object. Any value you
return is ignored.

    sub BUILD { my $self = shift; ... }

=item BUILDARGS

Custom constructor argument processing. If you define BUILDARGS, you can
control how the constructor's arguments are built into the object hashref.

    sub BUILDARGS { my ($class, @args) = @_; ... }

=item dump

Returns a textual dump of the object.

=item meta

Returns a Moos::Meta::Class object for the class. This has a very limited
subset of L<Moose::Meta::Class>' functionality, including implementations of
the following methods: C<name>, C<attribute_metaclass>, C<add_attribute>,
C<add_method>, C<superclasses>, C<linearized_isa>, C<new_object>,
C<get_all_attributes>, C<get_attribute> and C<find_attribute_by_name>.

The attribute introspection methods return L<Moos::Meta::Attribute> objects
which provide a very limited subset of L<Moose::Meta::Attribute>'s
functionality, including implementations of the following methods: C<name>,
C<associated_class>, C<predicate>, C<clearer>, C<default>, C<builder>,
C<trigger>, C<required>, C<lazy> and C<documentation>.

=item does/DOES

Methods to check whether the classI<< object performs a particular role. The
methods differ in that C<does> checks roles only in the Moose >>Moo/Role::Tiny
sense; C<DOES> also takes into account L<UNIVERSAL>::DOES.

=back

=head2 Roles

If you need roles, then Moos classes have B<experimental> support for
L<Role::Tiny>, L<Moo::Role> and L<Moose::Role> roles. (Moos provides a C<with>
command that uses L<Role::Tiny> to do the work.)

    {
        package Local::Class;
        use Moos;
        with "Local::Role";
        ...;
    }

B<Limitations:> Note that Moo and Moose each allow type constraints for
attributes; Moos does not. This means that if you compose, say, a Moose::Role
into a Moos class, you end up with a strange situation where the accessor
methods will enforce type constraints (because they were generated by Moose)
but the constructor will not (because it is inherited from Moos::Object).

See also L<Moos::Role>.

=head2 Method Modifiers

If you need method modifiers, then try L<Class::Method::Modifiers>.

=head2 Development Options

Moos has a couple of builtin dev options. They are controlled by environment
variables.

=over

=item PERL_MOOS_ACCESSOR_CALLS

By setting this environment variable, Moos will warn everytime an accessor
method is called.

=item PERL_MOOS_XXX

By setting the environment variable, Moos will export the L<XXX>
debugging keywords.

=back

=head1 WHENCE MOOS

I(ngy) created Moos during L<Pegex> development. Pegex uses a clone of Moos
called L<Pegex::Base>. (L<Moos> ships with a commandline utility called
C<remoos> that does this cloning.)

Pegex is a parser framework and needs to be fast. While looking into speed
issues I noted that accessor calling was the biggest hit. I tried all the
various Mo* solutions and L<Mouse> was the fastest.

I was happy until I remembered that Mouse uses XS, and for various reasons
this broke my toolchain (TestML, Module::Install, etc).

So I made a single module/file Moose clone and it worked out well. I've shared
Pegex::Base as L<Moos> in case any other projects want it.

Later on, Toby Inkster added a bunch of low-cost but very handy features
from Moose.

The name L<Moos> was chosen because it was the only name left between M and
Moose. (Thus adding to the epic confusion that we embrace as Perl Mongers! :)

=head1 ON SPEED

In the end, I got Pegex to run even faster with Moos than it originally did
with Mouse. I'll tell you my secret...

B<< Accessors I<(usually)> do not need to be method calls. >>

Replace these:

    my $foo = $self->foo;
    $self->foo($foo);

with:

    my $foo = $self->{foo};
    $self->{foo} = $foo;

And your code will be faster (and a bit uglier).

The only time that you need to call an accessor method is when you are
accessing a property and it might invoke a C<lazy> C<builder>, C<default> or
C<trigger> method. Otherwise you are just wasting time. At least with the
minimal feature set offered by Moos.

The PERL_MOOS_ACCESSOR_CALLS feature described above is for finding these
method calls.

Note that third parties can still use your module's accessor methods like they
would expect to.

I'm sure I've missed some subtleties, and would be glad to hear opinions, but
in the meantime I'm happy that my code is faster and pure Perl.

=head1 SEE ALSO

=over

=item * L<M>

=item * L<Mo>

=item * L<Moo>

=item * L<Moos>

=item * L<Moose>

=item * L<Mouse>

=item * L<Mousse>

=back

=head1 AUTHORS

Ingy döt Net <ingy@cpan.org>

Toby Inkster <tobyink@cpan.org>

=head1 COPYRIGHT AND LICENSE

Copyright 2012-2014. Ingy döt Net.

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

See L<http://www.perl.com/perl/misc/Artistic.html>

=cut
