lib/MooseX/Singleton.pm

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