—

              
HideShow 192 lines of Pod
=pod
=head1 NAME
Mite::Manual::Features - other features provided by Mite
=head1 MANUAL
=head2 Class Methods
Your class can or will provide the following methods:
=head3 C<< new( %attributes ) >> or C<< new( \%attributes ) >>
Constructor for your class. It takes some arguments and returns an
object.
Mite generates this for you.
Mite automatically provides a similar feature to L<MooseX::StrictConstructor>,
so your constructor will die if you pass it unknown attributes. 
=head3 C<BUILDARGS>
Works as in L<Moose> and allows your constructor to be called with something
other than a hash of attributes. Mite does not generate this for you.
=head3 C<FOREIGNBUILDARGS>
Works as in L<Moo> and L<MooseX::NonMoose>. Mite does not generate this for
you.
=head3 C<BUILD> / C<BUILDALL>.
Works as in L<Moose>. Mite generates C<BUILDALL> for you.
From Mite 0.007004 onwards, your C<BUILD> method gets called I<before>
the strict constructor check, which allows you to remove keys from
C<< $args >> if you don't want them to trigger an exception.
=head3 C<DEMOLISH> / C<DESTROY>
Works as in L<Moose>. Mite generates C<DESTROY> for you.
On Perl older than 5.14, the C<< $in_global_destruction >> argument
will be undefined unless L<Devel::GlobalDestruction> is installed,
so add that to your project's dependencies if you are relying on it
and need to support older versions of Perl.
=head3 C<DOES> / C<does>
C<DOES> allows you to check if your class/object performs a particular
role. See L<UNIVERSAL>.
C<does> is just an alias.
If you want to fake support for a role:
    $Your::Project::SomeClass::DOES{'Your::Project::SomeRole'} = 1;
=head2 C<strict>
Mite will turn strict on for you.
=head2 C<warnings>
Mite will turn warnings on for you.
=head2 Clean Classes
Mite will automatically import L<namespace::autoclean> into your classes
if it is installed on the end user's system. If it's not available, your
classes will quietly be left with imported keywords cluttering up their
namespace.
To force namespace::autoclean, then just use it manually:
    use Your::Project::Mite;
    use namespace::autoclean;
To force it to I<not> be used:
    use Your::Project::Mite qw( -unclean );
=head2 Autolax
Autolax mode can be enabled in your F<.mite/config> file:
    autolax: 1
If you do that and recompile your project, then many of the sanity checks Mite
builds into your constructors, accessors, and method signatures will be
disabled by default. In lax mode, these checks will be disabled:
=over
=item *
MooseX::StrictConstructor-style checks for unknown named parameters passed
to your constructor.
=item *
Checks for unknown named parameters passed to method signatures.
=item *
Type checks in your constructor, except as part of coercion.
=item *
Type checks in accessors and writers, except as part of coercion.
=item *
Type checks in method signatures, except as part of coercion.
=item *
Argument count checks in readers, writers, accessors, lvalue accessors,
clearers, and predicates.
=item *
Argument count checks in method signatures.
=back
However, while the checks become disabled, they can be re-enabled by the end
user by setting the C<PERL_STRICT> environment variable, or any other
environment variable supported by L<Devel::StrictMode>.
The idea is that if your project uses autolax, you can set C<PERL_STRICT> in
your testing environment to get more rigorous checks, fix any errors you find,
and then run your code without C<PERL_STRICT> in your production environment.
=head2 Run-Time Role Application
If you add the C<< -runtime >> option when creating a Mite role:
    package Your::Project::SomeRole;
    use Your::Project::Mite -role, -runtime;
Then your role will include a couple of functions:
    # Applies the role to an existing object
    #
    Your::Project::SomeRole::APPLY_TO( $object );
    # Applies the role to an existing class
    #
    Your::Project::SomeRole::APPLY_TO( 'Some::Class' );
    # Applies the role to an existing class, but does not modify the
    # existing class.
    #
    my $new_class = Your::Project::SomeRole::CREATE_CLASS( 'Some::Class' );
As this functionality is relatively heavy, it is not included in roles
by default, which is why the C<< -runtime >> option is needed as a way
to opt in.
When applying a role to an existing class, the class's constructor
I<< will not be modified >>, so any attributes defined in the role will
only be available to get and set via accessor methods.
=head1 BUGS
Please report any bugs to L<https://github.com/tobyink/p5-mite/issues>.
=head1 AUTHOR
Michael G Schwern E<lt>mschwern@cpan.orgE<gt>.
Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
=head1 COPYRIGHT AND LICENCE
This software is copyright (c) 2011-2014 by Michael G Schwern.
This software is copyright (c) 2022 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
=head1 DISCLAIMER OF WARRANTIES
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
=cut