# NAME

MooseX::MarkAsMethods - Mark overload code symbols as methods

# SYNOPSIS

    package Foo;
    use Moose;

    # mark overloads as methods and wipe other non-methods
    use MooseX::MarkAsMethods autoclean => 1;

    # define overloads, etc as normal

    package Baz;
    use Moose::Role
    use MooseX::MarkAsMethods autoclean => 1;

    # overloads defined in a role will "just work" when the role is
    # composed into a class

    # additional methods generated outside Class::MOP/Moose can be marked, too
    __PACKAGE__->meta->mark_as_method('foo');

    package Bar;
    use Moose;

    # order is important!
    use namespace::autoclean;
    use MooseX::MarkAsMethods;

    # ...

# DESCRIPTION

MooseX::MarkAsMethods allows one to easily mark certain functions as Moose
methods.  This will allow other packages such as [namespace::autoclean](http://search.cpan.org/perldoc?namespace::autoclean) to
operate without blowing away your overloads.  After using
MooseX::MarkAsMethods your overloads will be recognized by [Class::MOP](http://search.cpan.org/perldoc?Class::MOP) as
being methods, and class extension as well as composition from roles with
overloads will "just work".

By default we check for overloads, and mark those functions as methods.

If 'autoclean => 1' is passed to import on use'ing this module, we will invoke
namespace::autoclean to clear out non-methods.

# TRAITS APPLIED

use'ing this package causes a trait to be applied to your metaclass (for both
roles and classes), that provides a mark_as_method() method.  You can use this
to mark newly generated methods at runtime (e.g. during class composition)
that some other package has created for you.

mark_as_method() is invoked with one or more names to mark as a method.  We die
on any error (e.g. name not in symbol table, already a method, etc).  e.g.

    __PACKAGE__->meta->mark_as_method('newly_generated');

e.g. say you have some sugar from another package that creates accessors of
some sort; you could mark them as methods via a method modifier:

    # called as __PACKAGE__->foo_generator('name', ...)
    after 'foo_generator' => sub {

        shift->meta->mark_as_method(shift);
    };

# IMPLICATIONS FOR ROLES

Using MooseX::MarkAsMethods in a role will cause Moose to track and treat your
overloads like any other method defined in the role, and things will "just
work".  That's it.

# CAVEATS

## meta->mark_as_method()

__You almost certainly don't need or want to do this.__  CMOP/Moose are fairly
good about determining what is and what isn't a method, but not perfect.
Before using this method, you should pause and think about why you need to.

## namespace::autoclean

As currently implemented, we run our "method maker" at the end of the calling
package's compile scope ([B::Hooks::EndOfScope](http://search.cpan.org/perldoc?B::Hooks::EndOfScope)).  As [namespace::autoclean](http://search.cpan.org/perldoc?namespace::autoclean)
does the same thing, it's important that if namespace::autoclean is used that
it be use'd BEFORE MooseX::MarkAsMethods, so that its end_of_scope block is
run after ours.

e.g.

    # yes!
    use namespace::autoclean;
    use MooseX::MarkAsMethods;

    # no -- overloads will be removed
    use namespace::autoclean;
    use MooseX::MarkAsMethods;

The easiest way to invoke this module and clean out non-methods without having
to worry about ordering is:

    use MooseX::MarkAsMethods autoclean => 1;

# SEE ALSO

[overload](http://search.cpan.org/perldoc?overload), [B::Hooks::EndOfScope](http://search.cpan.org/perldoc?B::Hooks::EndOfScope), [namespace::autoclean](http://search.cpan.org/perldoc?namespace::autoclean), [Class::MOP](http://search.cpan.org/perldoc?Class::MOP),
[Moose](http://search.cpan.org/perldoc?Moose).

[MooseX::Role::WithOverloading](http://search.cpan.org/perldoc?MooseX::Role::WithOverloading) does allow for overload application from
roles, but it does this by copying the overload symbols from the (not
namespace::autoclean'ed role) the symbols handing overloads during class
composition; we work by marking the overloads as methods and letting
CMOP/Moose handle them.

# AUTHOR

Chris Weyl, `<cweyl at alumni.drew.edu>`

# BUGS

Please report any bugs or feature requests to
`bug-moosex-markasmethods at rt.cpan.org`, or through
the web interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MooseX-MarkAsMethods>.

# TODO

Additional testing is required, particularly where namespace::autoclean is
also being used.

# SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc MooseX::MarkAsMethods



You can also look for information at:

- * RT: CPAN's request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=MooseX-MarkAsMethods>

- * AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/MooseX-MarkAsMethods>

- * CPAN Ratings

<http://cpanratings.perl.org/d/MooseX-MarkAsMethods>

- * Search CPAN

<http://search.cpan.org/dist/MooseX-MarkAsMethods/>



# COPYRIGHT & LICENSE

Copyright (c) 2009, 2010, Chris Weyl `<cweyl@alumni.drew.edu>`.

This library is free software; you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the Free
Software Foundation; either version 2.1 of the License, or (at your option)
any later version.

This library is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
OR A PARTICULAR PURPOSE.

See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this library; if not, write to the

    Free Software Foundation, Inc.,
    59 Temple Place, Suite 330,
    Boston, MA  02111-1307 USA