NAME
    MooseX::RelatedClasses - Parameterized role for related class attributes

VERSION
    This document describes version 0.001 of MooseX::RelatedClasses -
    released October 29, 2012 as part of MooseX-RelatedClasses.

DESCRIPTION
    Have you ever built out a framework, or interface API of some sort, to
    discover either that you were hardcoding your related class names (not
    very extension-friendly) or writing the same code for the same type of
    attributes to specify what related classes you're using?

    Alternatively, have you ever been using a framework, and wanted to tweak
    one tiny bit of behaviour in a subclass, only to realize it was written
    in such a way to make that difficult-to-impossible without a significant
    effort?

    This package aims to end that, by providing an easy, flexible way of
    defining "related classes", their base class, and allowing traits to be
    specified.

SYNOPSIS
    package My::Framework::Thinger;
    # ...
        package My::Framework;

        use Moose;
        use namespace::autoclean;

        # with this...
        with 'MooseX::RelatedClasses' => {
            name => 'Thinger',
        };

        # ...we get:
        has thinger_class => (
            traits  => [ Shortcuts ], # MooseX::AttributeShortcuts
            is      => 'lazy',
            isa     => PackageName, # MooseX::Types::Perl
            default => sub { ... compose original class and traits ... },
        );

        has thinger_class_traits => (
            traits  => [ Shortcuts ], # MooseX::AttributeShortcuts
            is      => 'lazy',
            isa     => ArrayRef[PackageName],
            default => sub { [ ] },
        );

        has original_thinger_class => (
            traits  => [ Shortcuts ], # MooseX::AttributeShortcuts
            is      => 'lazy',
            coerce  => 1,
            isa     => LoadableClass, # MooseX::Types::LoadableClass
            init_arg => undef,
            default => sub { 'My::Framework::Thinger' },
        );

        # multiple related classes can be handled in one shot:
        with 'MooseX::RelatedClasses' => {
            names => [ qw{ Thinger Dinger Finger } ],
        };

        # if you're using this role and the name of the class is _not_ your
        # related namespace, then you can specify it:
        with 'MooseX::RelatedClasses' => {

            # e.g. My::Framework::Recorder::Thinger
            name      => 'Thinger',
            namespace => 'My::Framework::Recorder',
        };

INSPIRATION / MADNESS
    The Class::MOP / Moose MOP show the beginnings of this: with attributes
    or methods named a certain way (e.g. *_metaclass()) the class to be used
    for a particular thing (e.g. attribute metaclass) is stored in a fashion
    such that a subclass (or trait) may overwrite and provide a different
    class name to be used.

    So too, here, we do this, but in a more flexible way: we track the
    original related class, any additional traits that should be applied,
    and the new (anonymous, typically) class name of the related class.

    Another example is the (very useful and usable) Net::Amazon::EC2. It
    uses Moose, is nicely broken out into discrete classes, etc, but does
    not lend itself to easy on-the-fly extension by developers with traits.

VERY EARLY CODE
    This package is very new, and is still being vetted "in use", as it
    were. The documentation (or tests) may not be 100%, but it's in active
    use. Pull requests are happily received :)

DOCUMENTATION
    See the SYNOPSIS for information; the tests are also useful here as
    well.

    I _did_ warn you this is a very early release, right?

SOURCE
    The development version is on github at
    <http://github.com/RsrchBoy/moosex-relatedclasses> and may be cloned
    from <git://github.com/RsrchBoy/moosex-relatedclasses.git>

BUGS
    Please report any bugs or feature requests on the bugtracker website
    https://github.com/RsrchBoy/moosex-relatedclasses/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 software is Copyright (c) 2012 by Chris Weyl.

    This is free software, licensed under:

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