lib/MooseX/Singleton.pm

   1 package MooseX::Singleton;
   2
   3 use Moose 0.89_02 ();
   4 use Moose::Exporter;
   5 use MooseX::Singleton::Object;
   6 use MooseX::Singleton::Meta::Class;
   7
   8 our $VERSION = '0.19';
   9 $VERSION = eval $VERSION;
  10
  11 Moose::Exporter->setup_import_methods( also => 'Moose' );
  12
  13 sub init_meta {
  14     shift;
  15     my %p = @_;
  16
  17     Moose->init_meta(%p);
  18
  19     my $caller = $p{for_class};
  20
  21     Moose::Util::MetaRole::apply_metaclass_roles(
  22         for_class       => $caller,
  23         metaclass_roles => ['MooseX::Singleton::Role::Meta::Class'],
  24         instance_metaclass_roles =>
  25             ['MooseX::Singleton::Role::Meta::Instance'],
  26         constructor_class_roles =>
  27             ['MooseX::Singleton::Role::Meta::Method::Constructor'],
  28     );
  29
  30     Moose::Util::MetaRole::apply_base_class_roles(
  31         for_class => $caller,
  32         roles =>
  33             ['MooseX::Singleton::Role::Object'],
  34     );
  35
  36     return $caller->meta();
  37 }
  38
  39
  40 1;
  41
  42 __END__
  43
  44 =pod
  45
  46 =head1 NAME
  47
  48 MooseX::Singleton - turn your Moose class into a singleton
  49
  50 =head1 VERSION
  51
  52 Version 0.18, released 24 May 08
  53
  54 =head1 SYNOPSIS
  55
  56     package MyApp;
  57     use MooseX::Singleton;
  58
  59     has env => (
  60         is      => 'rw',
  61         isa     => 'HashRef[Str]',
  62         default => sub { \%ENV },
  63     );
  64
  65     package main;
  66
  67     delete MyApp->env->{PATH};
  68     my $instance = MyApp->instance;
  69     my $same = MyApp->instance;
  70
  71 =head1 DESCRIPTION
  72
  73 A singleton is a class that has only one instance in an application.
  74 C<MooseX::Singleton> lets you easily upgrade (or downgrade, as it were) your
  75 L<Moose> class to a singleton.
  76
  77 All you should need to do to transform your class is to change C<use Moose> to
  78 C<use MooseX::Singleton>. This module uses a new class metaclass and instance
  79 metaclass, so if you're doing metamagic you may not be able to use this.
  80
  81 C<MooseX::Singleton> gives your class an C<instance> method that can be used to
  82 get a handle on the singleton. It's actually just an alias for C<new>.
  83
  84 Alternatively, C<< YourPackage->method >> should just work. This includes
  85 accessors.
  86
  87 If you need to reset your class's singleton object for some reason (e.g.
  88 tests), you can call C<< YourPackage->_clear_instance >>.
  89
  90 =head1 TODO
  91
  92 =over
  93
  94 =item Always more tests and doc
  95
  96 =item Fix speed boost
  97
  98 C<instance> invokes C<new> every time C<< Package->method >> is called, which
  99 incurs a nontrivial runtime cost. I've implemented a short-circuit for this
 100 case, which does eliminate nearly all of the runtime cost. However, it's ugly
 101 and should be fixed in a more elegant way.
 102
 103 =back
 104
 105 =head1 BUGS
 106
 107 All complex software has bugs lurking in it, and this module is no
 108 exception. If you find a bug please either email me, or add the bug
 109 to cpan-RT.
 110
 111 =head1 AUTHORS
 112
 113 Shawn M Moore E<lt>sartak@gmail.comE<gt>
 114
 115 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 116
 117 =head1 SOME CODE STOLEN FROM
 118
 119 Anders Nor Berle E<lt>debolaz@gmail.comE<gt>
 120
 121 =head1 AND PATCHES FROM
 122
 123 Ricardo SIGNES E<lt>rjbs@cpan.orgE<gt>
 124
 125 =head1 COPYRIGHT AND LICENSE
 126
 127 Copyright 2007, 2008 Infinity Interactive
 128
 129 This program is free software; you can redistribute it and/or modify it under
 130 the same terms as Perl itself.
 131
 132 =cut
 133