NAMES
    Vendor
    Keep
    Keeper
    ShopKeep
    Merchant
    Object::Vendor
    Curio
    Bauble
    Trinket
    Trifle
    Tchotchke

singleton example in cookbook
    package Foo;
    use Curio;
    does_caching;
    fetch_method_name 'instance';
    export_function_name 'foo_instance';
Foo->instance();

Rename Curio::Factory.
What is Curio::Factory?
- Holds values of behavioral flags.
- Acts on many of those behaviors.
    - Exception being the export function which is acted
      on by Curio::Role.
- Produces Curio objects in a factory-like way.
- Tracks Curio objects and factory objects.

- Directory
- Factory
- Metadata
- Cache
- Holder of Objects
- Describer
I create, provide, and hold objects of this type.

Definer, creator, provider, and holder of Curio objects.

::Factory
::Meta
::Core
::Box
::Workshop
::Artisan
::Driver
::Vendor
::Builder
::Depot


make sure fetch call path is as fast as possible

replace Curio::Role factory() with just a die
when a Curio::Factory is created, install a new
factory() in the curio class with a faster closure
around the $self factory

subclass of curio classes
  OMG can of worms... what would it take?
  The factory would need to be copied... is that all?
  Then we could have Curio::CHI as a base class or something.
  CurioX::CHI Curio::Object::CHI
  use Curio; extends 'Curio::Base::CHI'; add_key 'sessions' ...; # done

What about integration with configuration backends?  That was something
Trinkey does and I was doing in an older version of this module.

Would be interesting if there was a way for Vendor classes to override
certain settings - such as whether caching is enabled or not on a per-
instance basis.
    sub curio_does_caching { ... }
    does_caching sub{ ... };

three types of objects in curio:
  factory object -> curio object -> resource object

tags would be neat.  gimme all the objects with tag x and y

real world example using Service::DB and ::DBIC and how it
makes life a load better

in Vendor when a candy function is called a second time (except
add_key/add_alias) it should throw an exception.  even tho the meta is
mutable, it should not be ok for the end user as the only time
someone who calls does_caching() twice, for example, is making
a mistake, no way to argue that right I don't think
or maybe something like:
    default_key 'foo';
    default_key 'foo-dev' if $is_dev;
hmmm
    default_key $is_dev ? 'foo-dev' : 'foo';
just add a trigger method that tracks this in the meta?
should be enforced in meta, not just candy

Check which is faster:
    my $class = shift;
    my $arg = shift;
    croak 'Too many arguments' if @_;
VS:
    my ($class, $arg) = @_;
    croak 'Too many arguments' if @_ > 2;
VS:
    croak 'Too many arguments' if @_ > 2;
    my ($class, $arg) = @_;
VS:
    etc
don't think it really matters, but maybe there are some
high volume ones that this will be useful for to check


=head1 MODULES

The Curio distribution is composed of several tightly coupled
modules.

=over

=item *

L<Curio> - Stitches together all the bits needed to build your
Curio classes.  L</Adjusting the Boilerplate> shows exactly what it
is doing.

=item *

L<Curio::Role> - This role is applied by L<Curio> to your Curio
classes.  It makes L<Curio::Factory> objects and ties them into
each of your Curio classes.

=item *

L<Curio::Factory> - Each Curio class gets a factory object.  The vast
majority of Curio's logic comes from the factory object as well as all
the metadata that describes how your Curio classes works.

=item *

L<Curio::Declare> - Exports a bunch of functions which provide a
declarative interface for defining the behavior of your Curio classes.
When you use L<Curio> you automatically get this.

=back

=head1 OBJECT TYPES

Factory Object ->
Curio Object ->
Resource Object

=head1 EXPORTED FUNCTIONS

The following functions are exported when you use this module.

    fetch_method_name
    export_function_name
    always_export
    resource_method_name
    fetch_returns_resource
    registers_resources
    does_caching
    cache_per_process
    does_keys
    allow_undeclared_keys
    default_key
    key_argument
    add_key
    alias_key

See L<Curio::Declare> for details about each of these, or read on
in the L</MANUAL> for examples.

=head1 MANUAL

=head2 Getting Started

=head2 The Fetch Method

    fetch_method_name 'connect';

Changes the fetch method name from C<fetch> to the name specified.

The fetch method is installed by L<Curio::Factory> into your Curio
class and is, along with L</export_function_name>, one of the main
ways to retrieve instances of you Curio classes.

=head2 Exporting the Fetch Function

    export_function_name 'myapp_cache';
    always_export;

=head2 Caching Objects

    does_caching;
    cache_per_process;

=head2 Object Keys

    allow_undeclared_keys;
    default_key 'generic';
    key_argument 'connection_key';
    add_key sessions => (
        driver => 'Memory',
    );

=head2 Handling Arguments

ways to handle key arguments. get them out of build_args like in
SYNOPSIS, or drop them in Moo attributes, or don't have them at all
and use key_argument along with the end-user's configuration setup
to convert the key to arguments, etc?

=head2 Migrating and Merging Keys

    alias_key sess => 'sessions';

=head2 Resource Registry

    registers_resources;

=head2 Adjusting the Boilerplate

This:

    use Curio;

Is the same as:

    use Moo;
    use Curio::Declare;
    use namespace::clean;
    with 'Curio::Role';
    __PACKAGE__->initialize();

Thus, if you're not into the declarative interface, or have some
other reason to switch around this boilerplate, you may copy the
above and modify to fit your needs, rather than using this module
directly.

=head1 NAME
=head1 SYNOPSIS
=head1 DESCRIPTION
=head1 BEWARE OF EARLY RELEASES



=head1 BOILERPLATE

=head1 MOTIVATION



=head1 INTRODUCTION

=head2 What is Curio

=head2 Creating a Class

=head2 Synopsis Walkthrough



=head1 TOPICS

=head2 The Fetch Method

=head2 Exporting the Fetch Function

=head2 Caching Objects

=head2 Object Keys

=head2 Handling Arguments

=head2 Migrating and Merging Keys

=head2 Resource Registry

=head2 Injecting Mock Objects



=head1 BEST PRACTICES

=head2 Avoid Holding onto Curio objects and Resources

=head2 Use Curio Directly

=head2 Purpose of Key Aliases



=head1 INTEGRATIONS



=head1 SEE ALSO
=head1 SUPPORT
=head1 AUTHORS
=head1 ACKNOWLEDGEMENTS
=head1 LICENSE
