=encoding utf8

=head1 NAME

Moos - Moo s{imple,peedy,ingle}

=head1 SYNOPSIS

    package Foos;
    use Moos;

    extends 'Bars';

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

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

=head1 DESCRIPTION

Moos completes the M to Moose sequence of Perl OO modules. This one is pure
Perl, no dependencies, single file, Moose compatible (for what it does). It is
fairly minimal; it supports the features shown in the L<SYNOPSIS>.

=head1 FEATURES

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

=over

=item extends($class);

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

=item $class->new(key => $value, key2 => $value)

A constructor.

=item sub BUILD { ... }

Custom object construction.

=item has name => ( ...options... );

Accessor generator.

=item has name => ( default => sub { ... } );

Specify the sub to generate a default value.

=item has name => ( buillder => 'buiild_method_name' );

Specify the method name to generate a default value.

=item has name => (..., lazy => 1);

Don't generate defaults during object construction.

=back

=head1 DEV OPTIONS

Moos has a couple 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

I(ngy) created Moos during L<Pegex> development. Pegex uses a clone of Moos
called L<Pegex::Base>.

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

I tried to inline L<Moo> into one file but failed, and ended up with this.
I've shared Pegex::Base as L<Moos> in case any other projects want it.

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

    Accessors (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 reading
a property and it might invoke a C<lazy> C<builder> or C<default> 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 users of your module's accessor methods can still use the method
calls like they would expect to.

I'm sure I've missed some subtlties, 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<Moose>

=item *

L<Mouse>

=item *

L<Mousse>

=back

=head1 AUTHOR

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

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2012. 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 http://www.perl.com/perl/misc/Artistic.html

=cut
