lib/MooseX/Singleton.pm

   1 package MooseX::Singleton;
   2
   3 use Moose 1.10 ();
   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.25';
  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_metaroles(
  23         for             => $caller,
  24         class_metaroles => {
  25             class => ['MooseX::Singleton::Role::Meta::Class'],
  26             instance =>
  27                 ['MooseX::Singleton::Role::Meta::Instance'],
  28             constructor =>
  29                 ['MooseX::Singleton::Role::Meta::Method::Constructor'],
  30         },
  31     );
  32
  33     Moose::Util::MetaRole::apply_base_class_roles(
  34         for_class => $caller,
  35         roles =>
  36             ['MooseX::Singleton::Role::Object'],
  37     );
  38
  39     return $caller->meta();
  40 }
  41
  42
  43 1;
  44
  45 __END__
  46
  47 =pod
  48
  49 =head1 NAME
  50
  51 MooseX::Singleton - turn your Moose class into a singleton
  52
  53 =head1 SYNOPSIS
  54
  55     package MyApp;
  56     use MooseX::Singleton;
  57
  58     has env => (
  59         is      => 'rw',
  60         isa     => 'HashRef[Str]',
  61         default => sub { \%ENV },
  62     );
  63
  64     package main;
  65
  66     delete MyApp->env->{PATH};
  67     my $instance = MyApp->instance;
  68     my $same = MyApp->instance;
  69
  70 =head1 DESCRIPTION
  71
  72 A singleton is a class that has only one instance in an application.
  73 C<MooseX::Singleton> lets you easily upgrade (or downgrade, as it were) your
  74 L<Moose> class to a singleton.
  75
  76 All you should need to do to transform your class is to change C<use Moose> to
  77 C<use MooseX::Singleton>. This module uses metaclass roles to do its magic, so
  78 it should cooperate with most other C<MooseX> modules.
  79
  80 =head1 METHODS
  81
  82 A singleton class will have the following additional methods:
  83
  84 =head2 Singleton->instance
  85
  86 This returns the singleton instance for the given package. This method does
  87 I<not> accept any arguments. If the instance does not yet exist, it is created
  88 with its defaults values. This means that if your singleton requires
  89 arguments, calling C<instance> will die if the object has not already been
  90 initialized.
  91
  92 =head2 Singleton->initialize(%args)
  93
  94 This method can be called I<only once per class>. It explicitly initializes
  95 the singleton object with the given arguments.
  96
  97 =head2 Singleton->_clear_instance
  98
  99 This clears the existing singleton instance for the class. Obviously, this is
 100 meant for use only inside the class itself.
 101
 102 =head2 Singleton->new
 103
 104 This method currently works like a hybrid of C<initialize> and
 105 C<instance>. However, calling C<new> directly will probably be deprecated in a
 106 future release. Instead, call C<initialize> or C<instance> as appropriate.
 107
 108 =head1 BUGS
 109
 110 Please report any bugs or feature requests to
 111 C<bug-moosex-singleton@rt.cpan.org>, or through the web interface at
 112 L<http://rt.cpan.org>. We will be notified, and then you'll automatically be
 113 notified of progress on your bug as we make changes.
 114
 115 =head1 AUTHORS
 116
 117 Shawn M Moore E<lt>sartak@gmail.comE<gt>
 118
 119 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 120
 121 =head1 SOME CODE STOLEN FROM
 122
 123 Anders Nor Berle E<lt>debolaz@gmail.comE<gt>
 124
 125 =head1 AND PATCHES FROM
 126
 127 Ricardo SIGNES E<lt>rjbs@cpan.orgE<gt>
 128
 129 =head1 COPYRIGHT AND LICENSE
 130
 131 Copyright 2007-2009 Infinity Interactive
 132
 133 This program is free software; you can redistribute it and/or modify it under
 134 the same terms as Perl itself.
 135
 136 =cut
 137