NAME
Curio::Manual - The Curio developer's manual.
UNDER CONSTRUCTION
This document is missing a lot of content! Right now it is mostly an outline. Hopefully the "SYNOPSIS" in Curio plus the bits of information in here is enough to get you started.
You are welcome to reach out to me by email at bluefeet@gmail.com and I'll get back to you right away.
INTRODUCTION
What is Curio
Creating a Class
Synopsis Walkthrough
TOPICS
Exporting the Fetch Function
To get at a Curio object's resource takes a lot of typing out of the box:
my $chi = MyApp::Service::Cache->fetch( $key )->chi();Creating an export function that wraps this all up is a great way to simplify things. In your Curio class write something like this after the use Curio line:
use Exporter qw( import );
our @EXPORT = qw( myapp_cache );And make a function like this:
sub myapp_cache {
return __PACKAGE__->fetch( @_ )->chi();
}Then users of your Curio class just write:
my $chi = myapp_cache( $key );Adjusting the Boilerplate
Near the top of most Curio classes is this line:
use Curio;Which is exactly the same as:
use Moo;
use Curio::Declare;
use namespace::clean;
with 'Curio::Role';
__PACKAGE__->initialize();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.
Read more about Moo and namespace::clean if you are not familiar with them.
Caching Objects
Keys
Handling Arguments
Migrating and Merging Keys
The Resource Registry
Injecting Mock Objects
IMPORTANT PRACTICES
Avoid Holding onto Curio Objects and Resources
Curio is designed to make it cheap to retrieve Curio objects and the underlying resources. Take advantage of this. Don't pass around your resource objects or put them in attributes. Instead, when you need them, get the from your Curio classes.
If your Curio class supports keys, then passing around the key that you want particular code to be using, rather than the Curio object or the resource, is a much better way of handling things.
Read more of the reasoning for this in "MOTIVATION" in Curio.
Use Curio Directly
It is tempting to use the "INTEGRATIONS" in Curio such as Catalyst::Model::Curio, and sometimes it is necessary to do so. Most of the time there is no need to add that extra layer of complexity.
Using Catalyst as an example, there are few reasons you can't just use your Curio classes directly from your Catalyst controllers.
At ZipRecruiter, where we have some massive Catalyst applications, we only use Catalyst models in the few cases where other parts of Catalyst demand that models be setup. For the most part we bypass the model system completely and it makes everything much cleaner and easier to deal with.
Appropriate Uses of Key Aliases
Key aliases are meant as a tool for migrating and merging keys. They are meant to be something you temporarily setup as you change your code to use the new keys, and then once done you remove the aliases.
It can be tempting to use key aliases to provide simpler or alternative names for existing keys. The problem with doing this is now you've introduced multiple keys for the same Curio class which in practice does cause unnecessary confusion.
COPYRIGHT AND LICENSE
Copyright (C) 2019 Aran Clary Deltac
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.