NAME

Context::Singleton - Context specific singleton values

GLOSSARY

dependency

Singleton which value is required to build another singleton's value

frame

Frame represents hierarchy. It is for data what block is for code. Resource value is by default cached in the top-most frame providing all its dependencies.

Cached values are destroyed upon leaving context.

rule

Rule specifies how to build singleton value

contrive 'singleton' => ( ... );

There can be multiple rules for building a single singleton. The one with most relevant dependencies will be used. When there are more available rules, the first defined will be used.

Refer "#contrive ()" for more.

singleton

A value identified by string. Singleton identifier is global.

DESCRIPTION

What is a context specific singleton?

As your workflow handles its tasks, granularity become finer and certain entities behaves like singletons.

As your application evolves, this granularity changes along with data model and/or data representation.

How does it differ from the multiton pattern?

Multiton is a set of named singletons (global variables) whereas values mantained by Context::Singleton are context sensitive.

Doesn't local already provide similar behaviour?

In addition to local Context::Singleton provides also immutability in scope assignment and lazy values built on demand.

When use Context::Singleton?

When your application evolves

When your application has tests

EXPORTED FUNCTIONS

Context::Singleton uses Exporter::Tiny to do hard work.

frame {}

frame {
	...;
}

Creates a new frame, calls its argument while preserving list/scalar context, and passes through returned value.

It doesn't consume any exception.

proclaim ()

proclaim singleton => value;
proclaim singleton_1 => value, singleton_2 => value2;

Define the value of a singleton in the current frame.

When it is already populated it throws an Context::Singleton::Exception::Deduced exception.

Returns the value of the last singleton from the argument list.

deduce ()

my $var = deduce q (singleton);

Returns a singleton value relevant in current frame.

If singleton value is not available, it tries to contrive it using known rules or looks into parent frame.

load_path ()

load_path q (prefix-1), ...;

Evaluate all modules within given module prefix(es). Every prefix is evaluated only once.

contrive ()

Defines new rule how to build singleton value

contrive q (name)
	=> class   => q (Foo::Bar)
	=> deduce  => q (singleton)
	=> builder => q (new)
	=> default => { singleton_1 => q (v1), ... }
	=> dep     => [ q (singleton_2), ... ]
	=> dep     => { param_a => q (singleton_1), ... }
	=> as      => sub { ... }
	=> value   => 10
;

value => constant

contrive q (http-request-timeout)
	=> value => 900
	;

Simplest rule, just constant value.

as => CODEREF

contrive q (ideal-body-weight-ibw)
	=> dep => [qw[ height gender ]]
	=> as  => sub ($height, $gender) {
		my $kg = 22 * ($heigth->meters - ($gender->is_woman ? 10 : 0)) ** 2;
		Weight->new (kilograms => $height->centimeters - 100);
	};

Defines code used to build singleton value. Dependencies are passed as arguments.

When used in conjuction with class or deduce, their value is passed as first argument (mimics method call).

builder => method_name

contrive q (height-in-meters)
	=> deduce  => q (height)
	=> builder => q (meters)
	;

contrive q (db-connection)
	=> class   => q (DBI)
	=> builder => q (connect)
	=> dep     => [qw[ db-dsn db-user db-password db-connection-options ]]
	;

Specifies method name to be applied on class or deduce. Defaults to new.

class => Class::Name

Calls the builder method with dependencies on the given class to build a value. Automatically creates singleton Class::Name with a rule dynamically loading given class and returning its name, almost like:

my $class_name = eval "require Class::Name; 'Class::Name'";
$class_name->$builder (@deps);

When class singleton is proclaimed class is not autoloaded.

See also: "#contrive_class ()"

deduce => singleton

Calls the builder method (with dependencies) on the object available as a value of the given singleton.

my $object = deduce q (singleton);
$object->$builder (@deps);

default => { singleton => value, ... }

Default values of dependencies. If used they are treated as deduced in root frame but are not stored neither cached anywhere.

dep

Dependencies required for this rule.

Two forms are recognized at the moment:

ARRAYREF

List of required singletons. Passed as a list to the builder function

HASHREF

Hash values are treated as singleton names. Passed as a list of named parameters to the builder function.

contrive_class ()

contrive_class q (Class::Name);

Setup autoload mechanism same as when using contrive with class.

SUBCLASSING

package My::Context::Singleton;
use parent q (Context::Singleton);

use My::Frame;
use constant DEFAULT_FRAME_CLASS => My::Frame::;

__PACKAGE__->import;

A subclass of Context::Singleton can declare a DEFAULT_FRAME_CLASS constant to specify which Context::Singleton::Frame (sub)class its exported functions operate on, without requiring every caller to pass frame_class explicitly.

frame_class passed at use time still takes precedence over DEFAULT_FRAME_CLASS:

use My::Context::Singleton;                                     # uses My::Frame
use My::Context::Singleton { frame_class => q (Other::Frame) }; # uses Other::Frame

See "EXTENDING FRAME" in Context::Singleton::Frame for how to implement a custom frame class.

TUTORIAL

See short tutorial Context::Singleton::Tutorial

REPOSITORY

https://github.com/happy-barney/perl-Context-Singleton

AUTHOR

Branislav Zahradník <barney.cpan@gmail.com>

COPYRIGHT AND LICENSE

Context::Singleton distribution can be distributed and modified under The Artistic License 2.0.

cpanm Context::Singleton

perl -MCPAN -e shell
install Context::Singleton