From: Shawn M Moore Date: Sun, 16 Dec 2007 19:21:20 +0000 (+0000) Subject: Documentation and little fixes. This one (0.03) is heading to CPAN X-Git-Tag: 0.09_02~24 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=b375b147ae0615bfe819dad1b2233ebf3fd90fc3;p=gitmo%2FMooseX-Singleton.git Documentation and little fixes. This one (0.03) is heading to CPAN --- diff --git a/ChangeLog b/ChangeLog new file mode 100644 index 0000000..9fe0922 --- /dev/null +++ b/ChangeLog @@ -0,0 +1,11 @@ +Revision history for Perl extension MooseX-Singleton + +0.03 2007-12-16 + - reimplementation as a metaclass (Sartak) + - initial CPAN release + +0.02 2007-12-16 + - instance and new are really the same, cleanup (Sartak) + +0.01 2007-04-20 + - initial implementation as a role (Debolaz) diff --git a/README b/README new file mode 100644 index 0000000..76812b7 --- /dev/null +++ b/README @@ -0,0 +1,65 @@ +NAME + MooseX::Singleton - turn your Moose class into a singleton + +VERSION + Version 0.03, released 16 Dec 07 + +SYNOPSIS + package MyApp; + use MooseX::Singleton; + + has env => ( + is => 'rw', + isa => 'HashRef[Str]', + default => sub { \%ENV }, + ); + + package main; + + delete MyApp->env->{PATH}; + my $instance = MyApp->instance; + my $same = MyApp->instance; + +DESCRIPTION + A singleton is a class that has only one instance in an application. + "MooseX::Singleton" lets you easily upgrade (or downgrade, as it were) + your Moose class to a singleton. + + All you should need to do to transform your class is to change "use + Moose" to "use MooseX::Singleton". This module uses a new class + metaclass and instance metaclass, so if you're doing metamagic you may + not be able to use this. + + "MooseX::Singleton" gives your class an "instance" method that can be + used to get a handle on the singleton. It's actually just an alias for + "new". + + Alternatively, "YourPackage->method" should just work. This includes + accessors. + +TODO + Always more tests and doc + Fix speed boost + "instance" invokes "new" every time "Package->method" is called, + which incurs a nontrivial runtime cost. I've implemented a + short-circuit for this case, which does eliminate nearly all of the + runtime cost. However, it's ugly and should be fixed in a more + elegant way. + +BUGS + All complex software has bugs lurking in it, and this module is no + exception. If you find a bug please either email me, or add the bug to + cpan-RT. + +AUTHOR + Shawn M Moore + +SOME CODE STOLEN FROM + Anders Nor Berle + +COPYRIGHT AND LICENSE + Copyright 2007 Shawn M Moore. + + This program is free software; you can redistribute it and/or modify it + under the same terms as Perl itself. + diff --git a/lib/MooseX/Singleton.pm b/lib/MooseX/Singleton.pm index c8c4123..5d16bdd 100644 --- a/lib/MooseX/Singleton.pm +++ b/lib/MooseX/Singleton.pm @@ -3,7 +3,7 @@ use Moose; use MooseX::Singleton::Object; use MooseX::Singleton::Meta::Class; -our $VERSION = 0.02; +our $VERSION = 0.03; sub import { my $caller = caller; @@ -13,8 +13,89 @@ sub import { Moose->import({into => $caller}); strict->import; warnings->import; - } 1; +__END__ + +=pod + +=head1 NAME + +MooseX::Singleton - turn your Moose class into a singleton + +=head1 VERSION + +Version 0.03, released 16 Dec 07 + +=head1 SYNOPSIS + + package MyApp; + use MooseX::Singleton; + + has env => ( + is => 'rw', + isa => 'HashRef[Str]', + default => sub { \%ENV }, + ); + + package main; + + delete MyApp->env->{PATH}; + my $instance = MyApp->instance; + my $same = MyApp->instance; + +=head1 DESCRIPTION + +A singleton is a class that has only one instance in an application. +C lets you easily upgrade (or downgrade, as it were) your +L class to a singleton. + +All you should need to do to transform your class is to change C to +C. This module uses a new class metaclass and instance +metaclass, so if you're doing metamagic you may not be able to use this. + +C gives your class an C method that can be used to get a handle on the singleton. It's actually just an alias for C. + +Alternatively, C<< YourPackage->method >> should just work. This includes +accessors. + +=head1 TODO + +=over + +=item Always more tests and doc + +=item Fix speed boost + +C invokes C every time C<< Package->method >> is called, which +incurs a nontrivial runtime cost. I've implemented a short-circuit for this +case, which does eliminate nearly all of the runtime cost. However, it's ugly +and should be fixed in a more elegant way. + +=back + +=head1 BUGS + +All complex software has bugs lurking in it, and this module is no +exception. If you find a bug please either email me, or add the bug +to cpan-RT. + +=head1 AUTHOR + +Shawn M Moore Esartak@gmail.comE + +=head1 SOME CODE STOLEN FROM + +Anders Nor Berle Edebolaz@gmail.comE + +=head1 COPYRIGHT AND LICENSE + +Copyright 2007 Shawn M Moore. + +This program is free software; you can redistribute it and/or modify it under +the same terms as Perl itself. + +=cut + diff --git a/lib/MooseX/Singleton/Meta/Class.pm b/lib/MooseX/Singleton/Meta/Class.pm index 51ca11c..28b1437 100644 --- a/lib/MooseX/Singleton/Meta/Class.pm +++ b/lib/MooseX/Singleton/Meta/Class.pm @@ -32,3 +32,19 @@ override construct_instance => sub { 1; +__END__ + +=pod + +=head1 NAME + +MooseX::Singleton::Meta::Class + +=head1 DESCRIPTION + +This metaclass is where the forcing of one instance occurs. The first call to +C is run normally (and then cached). Subsequent calls will +return the cached version. + +=cut + diff --git a/lib/MooseX/Singleton/Meta/Instance.pm b/lib/MooseX/Singleton/Meta/Instance.pm index c0dbc91..ad01ccc 100644 --- a/lib/MooseX/Singleton/Meta/Instance.pm +++ b/lib/MooseX/Singleton/Meta/Instance.pm @@ -56,3 +56,19 @@ sub inline_slot_access { 1; +__END__ + +=pod + +=head1 NAME + +MooseX::Singleton::Meta::Instance + +=head1 DESCRIPTION + +This instance metaclass manages attribute access and storage. When accessing an +attribute, it will convert a bare package to its cached singleton instance +(creating it if necessary). + +=cut + diff --git a/lib/MooseX/Singleton/Object.pm b/lib/MooseX/Singleton/Object.pm index 08a4926..c35c1e8 100644 --- a/lib/MooseX/Singleton/Object.pm +++ b/lib/MooseX/Singleton/Object.pm @@ -5,9 +5,21 @@ use metaclass 'MooseX::Singleton::Meta::Class'; extends 'Moose::Object'; -no strict 'refs'; - sub instance { shift->new } 1; +__END__ + +=pod + +=head1 NAME + +MooseX::Singleton::Object - base class for MooseX::Singleton + +=head1 DESCRIPTION + +This just adds C as a shortcut for C. + +=cut +