From: Matt S Trout Date: Wed, 18 Jul 2012 19:56:26 +0000 (+0000) Subject: doc cleanup X-Git-Tag: v1.000000~3 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=71bd6a81f0713ae3316fd5a044204ea479022496;p=gitmo%2FMoo.git doc cleanup --- diff --git a/Changes b/Changes index d527a31..f7f1dd0 100644 --- a/Changes +++ b/Changes @@ -1,3 +1,4 @@ + - clean up doc language and expand on Moo and Moose - error prefixes for isa and coerce exceptions - unmark Moo and Moose as experimental since it's relatively solid now - convert isa and coerce info from external role attributes diff --git a/lib/Moo.pm b/lib/Moo.pm index 17f5226..35c2df6 100644 --- a/lib/Moo.pm +++ b/lib/Moo.pm @@ -226,19 +226,30 @@ and else where =head1 DESCRIPTION -This module is an extremely light-weight, high-performance L replacement. +This module is an extremely light-weight subset of L optimised for +rapid startup and pay for what you use. + It also avoids depending on any XS modules to allow simple deployments. The name C is based on the idea that it provides almost -but not quite- two thirds of L. -Unlike C this module does not aim at full L compatibility. See -L for more details. +Unlike C this module does not aim at full compatibility with +L's surface syntax, preferring instead of provide full interoperability +via the metaclass inflation capabilites described in L. + +For a full list of the minor differences between L and L's surface +syntax, see L. =head1 WHY MOO EXISTS If you want a full object system with a rich Metaprotocol, L is already wonderful. +However, sometimes you're writing a command line script or a CGI script +where fast startup is essential, or code designed to be deployed as a single +file via L, or you're writing a CPAN module and you want it +to be usable by people with those constraints. + I've tried several times to use L but it's 3x the size of Moo and takes longer to load than most of my Moo based CGI scripts take to run. @@ -246,15 +257,15 @@ If you don't want L, you don't want "less metaprotocol" like L, you want "as little as possible" - which means "no metaprotocol", which is what Moo provides. -By Moo 1.0 I intend to have Moo's equivalent of L built in - -if Moose gets loaded, any Moo class or role will act as a Moose equivalent -if treated as such. +Better still, if you install and load L, we set up metaclasses for your +L classes and L roles, so you can use them in L code +without ever noticing that some of your codebase is using L. Hence - Moo exists as its name - Minimal Object Orientation - with a pledge to make it smooth to upgrade to L when you need more than minimal features. -=head1 Moo and Moose +=head1 MOO AND MOOSE If L detects L being loaded, it will automatically register metaclasses for your L and L packages, so you should be able @@ -272,7 +283,13 @@ This means that there is no need for anything like L for Moo code - Moo and Moose code should simply interoperate without problem. To handle L code, you'll likely need an empty Moo role or class consuming or extending the L stuff since it doesn't register true L -metaclasses like we do. +metaclasses like L does. + +If you want types to be upgraded to the L types, use +L and install the L library to +match the L library you're using - L will +load the L library and use that type for the newly created +metaclass. If you need to disable the metaclass creation, add: