[gitmo/MooseX-Singleton.git] / README

NAME
    MooseX::Singleton - turn your Moose class into a singleton

VERSION
    Version 0.08, released 24 May 08

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 <sartak@gmail.com>

SOME CODE STOLEN FROM
    Anders Nor Berle <debolaz@gmail.com>

AND PATCHES FROM
    Ricardo SIGNES <rjbs@cpan.org>

    Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE
    Copyright 2007, 2008 Shawn M Moore.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.
Commit	Line	Data
b375b147	1	NAME
	2	MooseX::Singleton - turn your Moose class into a singleton
	3
	4	VERSION
99beef76	5	Version 0.08, released 24 May 08
b375b147	6
	7	SYNOPSIS
	8	package MyApp;
	9	use MooseX::Singleton;
	10
	11	has env => (
	12	is => 'rw',
	13	isa => 'HashRef[Str]',
	14	default => sub { \%ENV },
	15	);
	16
	17	package main;
	18
	19	delete MyApp->env->{PATH};
	20	my $instance = MyApp->instance;
	21	my $same = MyApp->instance;
	22
	23	DESCRIPTION
	24	A singleton is a class that has only one instance in an application.
	25	"MooseX::Singleton" lets you easily upgrade (or downgrade, as it were)
	26	your Moose class to a singleton.
	27
	28	All you should need to do to transform your class is to change "use
	29	Moose" to "use MooseX::Singleton". This module uses a new class
	30	metaclass and instance metaclass, so if you're doing metamagic you may
	31	not be able to use this.
	32
	33	"MooseX::Singleton" gives your class an "instance" method that can be
	34	used to get a handle on the singleton. It's actually just an alias for
	35	"new".
	36
	37	Alternatively, "YourPackage->method" should just work. This includes
	38	accessors.
	39
	40	TODO
	41	Always more tests and doc
	42	Fix speed boost
	43	"instance" invokes "new" every time "Package->method" is called,
	44	which incurs a nontrivial runtime cost. I've implemented a
	45	short-circuit for this case, which does eliminate nearly all of the
	46	runtime cost. However, it's ugly and should be fixed in a more
	47	elegant way.
	48
	49	BUGS
	50	All complex software has bugs lurking in it, and this module is no
	51	exception. If you find a bug please either email me, or add the bug to
	52	cpan-RT.
	53
	54	AUTHOR
	55	Shawn M Moore <sartak@gmail.com>
	56
	57	SOME CODE STOLEN FROM
	58	Anders Nor Berle <debolaz@gmail.com>
	59
b1411a85	60	AND PATCHES FROM
	61	Ricardo SIGNES <rjbs@cpan.org>
	62
	63	Dave Rolsky <autarch@urth.org>
	64
b375b147	65	COPYRIGHT AND LICENSE
86c3868d	66	Copyright 2007, 2008 Shawn M Moore.
b375b147	67
	68	This program is free software; you can redistribute it and/or modify it
	69	under the same terms as Perl itself.
	70