Utility subroutines for building "inside-out" objects
This document describes Class::Std::Utils version 0.0.3
use Class::Std::Utils;
# Constructor for anonymous scalars...
my $new_object = bless anon_scalar(), $class;
# Convert an object reference into a unique ID number...
my $ID_num = ident $new_object;
# Extract class-specific arguments from a hash reference...
my %args = extract_initializers_from($arg_ref);
This module provides three utility subroutines that simplify the creation of \*(L"inside-out\*(R" classes. See Chapters 15 and 16 of \*(L"Perl Best Practices\*(R" (O'Reilly, 2005) for details.
This subroutine is always exported. It takes no arguments and returns a reference to an anonymous scalar, suitable for blessing as an object. This subroutine is always exported. It takes one argument\*(--a reference\*(-- and acts exactly like the \*(C`Scalar::Util::refaddr()\*(C', returning a unique integer value suitable for identifying the referent. This subroutine is always exported. It takes one argument\*(--a hash reference\*(-- and returns a \*(L"flattened\*(R" set of key/value pairs extracted from that hash. The typical usage is: my %class_specific_args = extract_initializers_from($args_ref); The argument hash is flattened as described in Chapter 16 of \*(L"Perl Best Practices\*(R":
The subroutine is always called with the original multi-level argument hash from the constructor. It then looks up the class's own name (i.e. its \*(C`caller\*(C' package) in the argument hash, to see if an initializer with that key has been defined. Finally, \*(C`extract_initializers_for()\*(C' returns the flattened set of key/value pairs for the class's initializer set, by appending the class-specific initializer subhash to the end of the original generic initializer hash. Appending the specific initializers after the generic ones means that any key in the class- specific set will override any key in the generic set, thereby ensuring that the most relevant initializers are always selected, but that generic initializers are still available where no class-specific value has been passed in.
In other words, given: my $arg_ref = { key_1 => 'generic value 1', key_2 => 'generic value 2',
'Base::Class' => { key_1 => 'base value 1' },
'Der::Class' => { key_1 => 'der value 1' key_2 => 'der value 2' }, };
package Base::Class; use Class::Std::Utils;
my %base_args = extract_initializers_from($arg_ref);
package Der::Class; use Class::Std::Utils;
my %der_args = extract_initializers_from($arg_ref); then %base_args would be initialized to: ( key_1 => 'base value 1', key_2 => 'generic value 2',
'Base::Class' => { key_1 => 'base value 1', },
'Der::Class' => { key_1 => 'der value 1', key_2 => 'der value 2', }, ) whilst %der_args would be initialized to: ( key_1 => 'der value 1', key_2 => 'der value 2',
'Base::Class' => { key_1 => 'base value 1', },
'Der::Class' => { key_1 => 'der value 1', key_2 => 'der value 2', }, ) That is, the top-level entries would be replaced by any second-level entries with the same key that appear in a top-level entry of the same name as the calling package. This means that each class can just refer to $args{key_1} and $args{key_2} and be confident that the resulting values will be the most specific available for that class.
Thrown by \*(C`extract_initializers_from()\*(C'. You specified a top-level key that has the same name of the current class, but the value of that key wasn't a hash reference.
Class::Std::Utils requires no configuration files or environment variables.
Thsi module requires both the \*(C`Scalar::Util\*(C' and \*(C`List::Util\*(C' modules, which are standard in Perl 5.8 and available from the \s-1CPAN\s0 for earlier versions of Perl.
None reported.
The \*(C`Class::Std\*(C' module
\*(L"Perl Best Practices\*(R", O'Reilly, 2005.
No bugs have been reported.
Please report any bugs or feature requests to \*(C`[email protected]\*(C', or through the web interface at <http://rt.cpan.org>.
Damian Conway \*(C`<[email protected]>\*(C'
Copyright (c) 2005, Damian Conway \*(C`<[email protected]>\*(C'. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
\s-1BECAUSE\s0 \s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1LICENSED\s0 \s-1FREE\s0 \s-1OF\s0 \s-1CHARGE\s0, \s-1THERE\s0 \s-1IS\s0 \s-1NO\s0 \s-1WARRANTY\s0 \s-1FOR\s0 \s-1THE\s0 \s-1SOFTWARE\s0, \s-1TO\s0 \s-1THE\s0 \s-1EXTENT\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0. \s-1EXCEPT\s0 \s-1WHEN\s0 \s-1OTHERWISE\s0 \s-1STATED\s0 \s-1IN\s0 \s-1WRITING\s0 \s-1THE\s0 \s-1COPYRIGHT\s0 \s-1HOLDERS\s0 \s-1AND/OR\s0 \s-1OTHER\s0 \s-1PARTIES\s0 \s-1PROVIDE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1WITHOUT\s0 \s-1WARRANTY\s0 \s-1OF\s0 \s-1ANY\s0 \s-1KIND\s0, \s-1EITHER\s0 \s-1EXPRESSED\s0 \s-1OR\s0 \s-1IMPLIED\s0, \s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0, \s-1THE\s0 \s-1IMPLIED\s0 \s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. \s-1THE\s0 \s-1ENTIRE\s0 \s-1RISK\s0 \s-1AS\s0 \s-1TO\s0 \s-1THE\s0 \s-1QUALITY\s0 \s-1AND\s0 \s-1PERFORMANCE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1WITH\s0 \s-1YOU\s0. \s-1SHOULD\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1PROVE\s0 \s-1DEFECTIVE\s0, \s-1YOU\s0 \s-1ASSUME\s0 \s-1THE\s0 \s-1COST\s0 \s-1OF\s0 \s-1ALL\s0 \s-1NECESSARY\s0 \s-1SERVICING\s0, \s-1REPAIR\s0, \s-1OR\s0 \s-1CORRECTION\s0.
\s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1UNLESS\s0 \s-1REQUIRED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0 \s-1OR\s0 \s-1AGREED\s0 \s-1TO\s0 \s-1IN\s0 \s-1WRITING\s0 \s-1WILL\s0 \s-1ANY\s0 \s-1COPYRIGHT\s0 \s-1HOLDER\s0, \s-1OR\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1WHO\s0 \s-1MAY\s0 \s-1MODIFY\s0 \s-1AND/OR\s0 \s-1REDISTRIBUTE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1AS\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1THE\s0 \s-1ABOVE\s0 \s-1LICENCE\s0, \s-1BE\s0 \s-1LIABLE\s0 \s-1TO\s0 \s-1YOU\s0 \s-1FOR\s0 \s-1DAMAGES\s0, \s-1INCLUDING\s0 \s-1ANY\s0 \s-1GENERAL\s0, \s-1SPECIAL\s0, \s-1INCIDENTAL\s0, \s-1OR\s0 \s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 \s-1ARISING\s0 \s-1OUT\s0 \s-1OF\s0 \s-1THE\s0 \s-1USE\s0 \s-1OR\s0 \s-1INABILITY\s0 \s-1TO\s0 \s-1USE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 (\s-1INCLUDING\s0 \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0 \s-1LOSS\s0 \s-1OF\s0 \s-1DATA\s0 \s-1OR\s0 \s-1DATA\s0 \s-1BEING\s0 \s-1RENDERED\s0 \s-1INACCURATE\s0 \s-1OR\s0 \s-1LOSSES\s0 \s-1SUSTAINED\s0 \s-1BY\s0 \s-1YOU\s0 \s-1OR\s0 \s-1THIRD\s0 \s-1PARTIES\s0 \s-1OR\s0 A \s-1FAILURE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1TO\s0 \s-1OPERATE\s0 \s-1WITH\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1SOFTWARE\s0), \s-1EVEN\s0 \s-1IF\s0 \s-1SUCH\s0 \s-1HOLDER\s0 \s-1OR\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1HAS\s0 \s-1BEEN\s0 \s-1ADVISED\s0 \s-1OF\s0 \s-1THE\s0 \s-1POSSIBILITY\s0 \s-1OF\s0 \s-1SUCH\s0 \s-1DAMAGES\s0.