[svn-inject] Installing original source of libclass-insideout-perl

parents
use strict;
use Module::Build;
my $class = Module::Build->subclass(
class => "Module::Build::WikiDoc",
code => <<'SUBCLASS', );
sub ACTION_wikidoc {
my $self = shift;
eval "use Pod::WikiDoc";
if ( $@ eq '' ) {
my $parser = Pod::WikiDoc->new( {
comment_blocks => 1,
keywords => { VERSION => $self->dist_version },
});
for my $src ( keys %{ $self->find_pm_files() } ) {
(my $tgt = $src) =~ s{\.pm$}{.pod};
$parser->filter( {
input => $src,
output => $tgt,
});
print "Creating $tgt\n";
$tgt =~ s{\\}{/}g;
$self->_add_to_manifest( 'MANIFEST', $tgt );
}
}
else {
warn "Pod::WikiDoc not available. Skipping wikidoc.\n";
}
}
sub ACTION_test {
my $self = shift;
my $missing_pod;
for my $src ( keys %{ $self->find_pm_files() } ) {
(my $tgt = $src) =~ s{\.pm$}{.pod};
$missing_pod = 1 if ! -e $tgt;
}
if ( $missing_pod ) {
$self->depends_on('wikidoc');
$self->depends_on('build');
}
$self->SUPER::ACTION_test;
}
sub ACTION_testpod {
my $self = shift;
$self->depends_on('wikidoc');
$self->SUPER::ACTION_testpod;
}
sub ACTION_distdir {
my $self = shift;
$self->depends_on('wikidoc');
$self->SUPER::ACTION_distdir;
}
SUBCLASS
my $builder = $class->new(
module_name => 'Class::InsideOut',
dist_author => 'David A. Golden <dagolden@cpan.org>',
license => 'apache',
create_readme => 1,
create_makefile_pl => 'traditional',
requires => {
'perl' => 5.005, # says Perl::MinimumVersion
'base' => 0,
'Class::ISA' => 0, # why reimplement what works
'Config' => 0,
'Exporter' => 0,
'Test::More' => 0.45, # thread-safe
'Scalar::Util' => 1.09, # refaddr
},
add_to_cleanup => [ 'Class-InsideOut-*' ],
meta_add => {
no_index => {
file => [ qw{
lib/Class/InsideOut/Manual/About.pm
lib/Class/InsideOut/Manual/Advanced.pm
} ],
directory => [ 'examples' ],
}
},
);
$builder->create_build_script;
Revision history for Perl module Class::InsideOut
1.09 Fri Jan 4 18:42:41 EST 2008
- bugfix: allow use of upper or mixed case property accessors
(David Schmitt)
- testfix: tests will now pass on Perl 5.005 -- though 5.005 is not
recommended due to the lack of weak references
- pod: added a note about using "our" instead of "my" for properties
- critic: various cleanups to about Perl::Critic level 5
- moved author tests to xt directory for CPANTS compatibility
1.08 Thu Aug 23 07:12:33 EDT 2007
- STORABLE_attach warns instead of dying if it can't provide a singleton
back to Storable, leaving Storable to croak instead; on 5.6.2 (and
possibly older Perls), this change works around Storable dying during
cleanup if STORABLE_attach dies inside an eval()
- thread tests skip on perl < 5.8.5 due to unexplained thread failures;
perl585delta alludes to thread fixes when weak references are in use
and this may be related
- removed "use warnings" from singleton test files for back compatibility
- moved pod/coverage tests to t_extra/ and stopped depending on an
environment variable to allow them to run
- changed to the Apache License, version 2.0; (it's clearer, relicensable,
and is explicit about contributions)
1.07 Fri Aug 10 07:41:00 EDT 2007
- fixes for using ":storable" with older versions of Exporter
that required tags to come first. Now we just strip it during import.
1.06 Mon Feb 12 19:34:59 EST 2007
- all tests involving Storable now skip if Storable isn't installed
(instead of only a few) (David Cantrell)
1.05 Sun Feb 11 16:29:16 EST 2007
- fixed optional new method with hash reference (RT#24839)
1.04 Thu Jan 18 21:47:19 EST 2007
- added 'readonly' accessor-creator
1.0301 Wed Nov 15 06:08:47 EST 2006
- removing email address for bug reports to (hopefully)
cut down on RT ticket spam
1.03 Wed Oct 11 10:55:28 EDT 2006
- thread tests skip if thread creation fails
- added an examples directory with a reference to some of the objects
used in testing
1.02 Tue Aug 15 09:26:11 EDT 2006
- fixed duplicate property name checking (RT#20997)
1.01 Thu Jul 27 12:30:54 EDT 2006
- register() now handles standard cases with "sufficiently advanced
technology" and does the right thing
- optional simple "new" constructor added
- changed "foreign" inheritance to "black-box" inheritance in Pod
1.00 Fri May 12 21:25:34 EDT 2006
- removed Data::Dump::Streamer support attempts until RT#19060 can
be addressed
0.90_02 Thu May 4 00:56:04 EDT 2006
- fixed up META.yml and a pod typo
0.90_01 Wed May 3 20:47:34 EDT 2006
- *API CHANGE* renamed serialization hooks to FREEZE and THAW
- added support for STORABLE_attach for singletons
- improved test coverage
- refactored some of the test classes
- refactored STORABLE_* code
- refactored documentation
- added draft (non-working) support for serialization with
Data::Dump::Streamer
0.14 Thu Mar 16 23:07:22 EST 2006
- Fixed test bug where thread test wouldn't properly skip for Win32 Perl
5.6 (with ithreads enabled for pseudofork but no threads.pm)
- Improved handling of "die" in set_hook and get_hook callbacks
0.13 Fri Mar 10 10:32:08 EST 2006
- Test for Scalar::Util::weaken fallback had a bug that would fail on
Perl versions prior to 5.6. Fixed to be fully backwards compatible.
0.12 Wed Mar 8 21:58:58 EST 2006
- Added workaround for unavailable Scalar::Util::weaken; gives warning
about not running thread-safe; added missing weaken skips to thread/fork
test files
- property/public/private arguments are now validated. Property names must
be identifiers; Property options must be given as hash references;
Duplicate property names are not permitted.
- options argument checked for proper format; option values are checked
for validity
- register argument checked for blessed reference
- added optional pod/pod_coverage tests (skipped by default)
0.11 Sat Jan 28 11:09:50 EST 2006
- tweaked Build.PL; dropped Test::More dependency to 0.45 to help pass
ActiveState automated tests (0.45 first to offer thread safety and in the
5.008 core); fixed copy/paste error for cleanup
- documentation cleanup; fixed links; restructured Pod for options;
softened alpha warnings as we get closer to a stable API
0.10 Fri Jan 27 01:41:38 EST 2006
- added "set_hook" and "get_hook" option for custom accessor/mutator
manipulations
- added ":all" and ":std" tags
- cleaned up or reorganized documentation in places; revised synopsis
to be shorter
0.09 Fri Jan 20 14:55:14 EST 2006
- added basic accessor generation as an option for property declarations;
added aliases "public" and "private" as shortcuts to property options
- added per-class default options for properties
- added support for user-written freeze and thaw hooks
- documentation updates: typo safety requires strict (Steven Lembark);
caching refaddr() to minimize overhead; new features documented
0.08 Wed Jan 18 10:50:13 EST 2006
- BACKWARDS INCOMPATIBLE CHANGE: property definitions now require a
label in addition to the property hash
- Class::ISA results are now cached when first used; also minor
optimization of reftype switching in STORABLE_* methods (Adam Kennedy)
- foreign inheritance test now checks for IO::File or skips
- documentation cleanup and trailing whitespace removal (Ron Savage)
0.07 Mon Jan 9 09:48:46 EST 2006
- Storable support tested with references, grouped references and circular
references; references external to the freeze are cloned
- documentation cleanup
0.06 Sun Jan 8 23:07:22 EST 2006
- DESTROY cleans up all Class::InsideOut properties in the @ISA tree;
updated documentation on object destruction for clarity; fixes
diamond-pattern inheritance memory leaks without requiring a DEMOLISH
method
- added first-draft support of serialization with Storable for objects
based on scalars, arrays and hashes; tested on data values only; not
yet tested on values with references or objects, particularly circular
reference chains
- CLONE no longer exported; all refaddr index cleanup handled globally in
Class::InsideOut::CLONE rather than in class-specific methods
0.05 Fri Jan 6 09:07:07 EST 2006
- added caveats on usage and current limitations
- more documentation tweaks
0.04 Thu Jan 5 21:44:30 EST 2006
- major documentation update
0.03 Thu Jan 5 18:41:05 EST 2006
- thread test no longer dies if threads are not configured
- added DEMOLISH support for custom destruction actions
- added id() as optional alias for refaddr
- documentation tweaks
0.02 Thu Jan 5 00:51:01 EST 2006
- basic property and object registration with automatic CLONE and DESTROY
0.01 Wed Jan 4 12:06:51 EST 2006
- placeholder
INSTALLATION
If Module::Build is installed (preferred):
perl Build.PL
perl Build
perl Build test
perl Build install
Otherwise, using a Makefile:
perl Makefile.PL
make
make test
make install
If you are on a windows box you should use 'nmake' rather than 'make'.
This diff is collapsed.
Build.PL
Changes
examples/README
INSTALL
lib/Class/InsideOut.pm
lib/Class/InsideOut.pod
lib/Class/InsideOut/Manual/About.pm
lib/Class/InsideOut/Manual/About.pod
lib/Class/InsideOut/Manual/Advanced.pm
lib/Class/InsideOut/Manual/Advanced.pod
LICENSE
Makefile.PL
MANIFEST
MANIFEST.SKIP
META.yml
README
t/01_load.t
t/02_register.t
t/03_properties.t
t/04_threaded.t
t/05_forking.t
t/06_export_ok.t
t/07_synopsis_obj.t
t/08_DEMOLISH.t
t/09_foreign.t
t/10_storable_values.t
t/11_storable_refs.t
t/12_storable_hooks.t
t/13_options.t
t/14_accessor_hooks.t
t/15_no_weaken_fallback.t
t/16_property_argument_checking.t
t/17_option_argument_checking.t
t/18_register_argument_checking.t
t/19_storable_singleton.t
t/20_storable_singleton_error.t
t/21_optional_new.t
t/22_readonly.t
t/data/testdata.txt
t/Object/Animal.pm
t/Object/Animal/Antelope.pm
t/Object/Animal/Jackalope.pm
t/Object/Animal/JackRabbit.pm
t/Object/Array.pm
t/Object/Foreign.pm
t/Object/Friends.pm
t/Object/Hash.pm
t/Object/Hooked.pm
t/Object/ReadOnly.pm
t/Object/RegisterClassname.pm
t/Object/RegisterRef.pm
t/Object/Scalar.pm
t/Object/Singleton/Hooked.pm
t/Object/Singleton/MissingConstructor.pm
t/Object/Singleton/Simple.pm
t/Object/Synopsis.pm
t/Object/Trivial.pm
t/Object/WithNew.pm
t/Object/WithNew/Inherited.pm
Todo
xt/criticrc
xt/perl-critic.t
xt/pod-coverage.t
xt/pod.t
# Version control files and dirs.
\bRCS\b
\bCVS\b
,v$
.svn/
# ExtUtils::MakeMaker generated files and dirs.
^MANIFEST\.(?!SKIP)
^Makefile$
^blib/
^blibdirs$
^PM_to_blib$
^MakeMaker-\d
# Module::Build
^Build$
^_build
.bat$
# Test coverage
^cover_db
# Temp, old, vi and emacs files.
~$
\.old$
^#.*#$
^\.#
\.swp$
\.bak$
---
name: Class-InsideOut
version: 1.09
author:
- 'David A. Golden <dagolden@cpan.org>'
abstract: 'a safe, simple inside-out object construction kit'
license: apache
resources:
license: http://apache.org/licenses/LICENSE-2.0
requires:
Class::ISA: 0
Config: 0
Exporter: 0
Scalar::Util: 1.09
Test::More: 0.45
base: 0
perl: 5.005
provides:
Class::InsideOut:
file: lib/Class/InsideOut.pm
version: 1.09
Class::InsideOut::Manual::About:
file: lib/Class/InsideOut/Manual/About.pm
version: 1.09
Class::InsideOut::Manual::Advanced:
file: lib/Class/InsideOut/Manual/Advanced.pm
version: 1.09
generated_by: Module::Build version 0.280801
meta-spec:
url: http://module-build.sourceforge.net/META-spec-v1.2.html
version: 1.2
no_index:
directory:
- examples
file:
- lib/Class/InsideOut/Manual/About.pm
- lib/Class/InsideOut/Manual/Advanced.pm
# Note: this file was auto-generated by Module::Build::Compat version 0.2808_01
require 5.005;
use ExtUtils::MakeMaker;
WriteMakefile
(
'PL_FILES' => {},
'INSTALLDIRS' => 'site',
'NAME' => 'Class::InsideOut',
'EXE_FILES' => [],
'VERSION_FROM' => 'lib/Class/InsideOut.pm',
'PREREQ_PM' => {
'base' => 0,
'Test::More' => '0.45',
'Scalar::Util' => '1.09',
'Class::ISA' => 0,
'Exporter' => 0,
'Config' => 0
}
)
;
This diff is collapsed.
TODO list for Perl module Class::InsideOut
# Todos after 1.0
- change to Apache license
- add support for new DDS serialization hooks
- test DDS on other serialization tests
- document DDS support
- accessor style options
- write FAQs
- expand documentation (cookbook? quick-start? notes on writing Builders)
- document some internal introspection functions (e.g. _evert/_revert)
# Possible todos depending on demand
- class accessors via "public foo => my $foo";
- add public introspection methods (property list and options?)
- accessor privacy => "protected" and matching property alias
- look into support for cloning tied objects(?) in the blessed hash(?)
- pre-clone user hook?? (waiting for someone to say they need it)
- BUILD method
#--------------------------------------------------------------------------#
# Thoughts about property accessor styles and options
#--------------------------------------------------------------------------#
# have to be careful of interrelationship between style and custom prefixes;
# maybe don't allow custom prefixes at all
Class::InsideOut::options(
accessor_style => 'perl', # default
# "combined"; "perl" => foo() and foo(x)
# "get_set"; "java" => get_foo() and set_foo(x)
# "eiffel" => foo() and set_foo(x)
get_prefix => 'get_', # maybe don't bother (YAGNI)
set_prefix => 'set_', # maybe don't bother (YAGNI)
privacy => 'public', # create accessors for everything given to properties
# or 'readonly' or 'protected' or 'private'
set_hook => \&coderef, # mutator argument filtered through this
# will catch die message for error
set_returns => 'self' # or 'newvalue' or 'oldvalue'
);
#--------------------------------------------------------------------------#
# FAQ ideas
#--------------------------------------------------------------------------#
* Security (c.f use perl post)
* advisory encapsulation
* Why "public *foo*" separate from "my %foo" (e.g. for "my %foo_of")
* Another advantage of InsideOut over accessors -- can use as Lvalue for
things like increments: $count_of{ id $self }
#--------------------------------------------------------------------------#
# Cookbook ideas
#--------------------------------------------------------------------------#
* Outside-in pattern
* Property aliasing: ( should work, but what about Storable? )
assets => my %assets;
wealth => my %assets;
For examples, see the objects used in testing located in t/Object/.
In particular, t/Object/Animal.pm and the subclasses in t/Object/Animal/
show typical object inheritance techniques.
For an example of foreign/black-box inheritance of an IO::File object,
see t/Object/Foreign.pm.
This diff is collapsed.
This diff is collapsed.
package Class::InsideOut::Manual::About;
# Not really a .pm file, but holds wikidoc which will be
# turned into .pod by the Build.PL
use strict; # make CPANTS happy
use vars /$VERSION/;
$VERSION = '1.09';
1;
__END__
=begin wikidoc
= NAME
Class::InsideOut::Manual::About - guide to this and other implementations of the
inside-out technique
= VERSION
This documentation refers to version %%VERSION%%
= DESCRIPTION
This manual provides an overview of the inside-out technique and its
application within {Class::InsideOut} and other modules. It also provides a
list of references for further study.
== Inside-out object basics
Inside-out objects use the blessed reference as an index into lexical data
structures holding object properties, rather than using the blessed reference
itself as a data structure.
$self->{ name } = "Larry"; # classic, hash-based object
$name{ refaddr $self } = "Larry"; # inside-out
The inside-out approach offers three major benefits:
* Enforced encapsulation: object properties cannot be accessed directly
from ouside the lexical scope that declared them
* Making the property name part of a lexical variable rather than a hash-key
means that typos in the name will be caught as compile-time errors (if
using [strict])
* If the memory address of the blessed reference is used as the index,
the reference can be of any type
In exchange for these benefits, robust implementation of inside-out
objects can be quite complex. {Class::InsideOut} manages that complexity.
== Philosophy of {Class::InsideOut}
{Class::InsideOut} provides a set of tools for building safe inside-out classes
with maximum flexibility.
It aims to offer minimal restrictions beyond those necessary for robustness of
the inside-out technique. All capabilities necessary for robustness should be
automatic. Anything that can be optional should be. The design should not
introduce new restrictions unrelated to inside-out objects, such as attributes
and {CHECK} blocks that cause problems for {mod_perl} or the use of source
filters for syntatic sugar.
As a result, only a few things are mandatory:
* Properties must be based on hashes and declared via {property}
* Property hashes must be keyed on the {Scalar::Util::refaddr}
* {register} must be called on all new objects
All other implementation details, including constructors, initializers and
class inheritance management are left to the user (though a very simple
constructor is available as a convenience). This does requires some additional
work, but maximizes freedom. {Class::InsideOut} is intended to be a base class
providing only fundamental features. Subclasses of {Class::InsideOut} could be
written that build upon it to provide particular styles of constructor,
destructor and inheritance support.
== Other modules on CPAN
* [Object::InsideOut] -- This is perhaps the most full-featured, robust
implementation of inside-out objects currently on CPAN. It is highly
recommended if a more full-featured inside-out object builder is needed.
Its array-based mode is faster than hash-based implementations, but black-box
inheritance is handled via delegation, which imposes certain limitations.
* [Class::Std] -- Despite the name, this does not reflect currently known best
practices for inside-out objects. Does not provide thread-safety with CLONE
and doesn't support black-box inheritance. Has a robust
inheritance/initialization system.
* [Class::BuildMethods] -- Generates accessors with encapsulated storage using
a flyweight inside-out variant. Lexicals properties are hidden; accessors must
be used everywhere. Not thread-safe.
* [Lexical::Attributes] -- The original inside-out implementation, but missing
some key features like thread-safety. Also, uses source filters to provide
Perl-6-like object syntax. Not thread-safe.
* [Class::MakeMethods::Templates::InsideOut] -- Not a very robust
implementation. Not thread-safe. Not overloading-safe. Has a steep learning
curve for the Class::MakeMethods system.
* [Object::LocalVars] -- My own original thought experiment with 'outside-in'
objects and local variable aliasing. Not safe for any production use and offers
very weak encapsulation.
== References for further study
Much of the Perl community discussion of inside-out objects has taken place on
Perlmonks ([http://perlmonks.org]). My scratchpad there has a fairly
comprehensive list of articles
([http://perlmonks.org/index.pl?node_id=360998]). Some of the more
informative articles include:
* Abigail-II. "Re: Where/When is OO useful?". July 1, 2002.
[http://perlmonks.org/index.pl?node_id=178518]
* Abigail-II. "Re: Tutorial: Introduction to Object-Oriented Programming".
December 11, 2002. [http://perlmonks.org/index.pl?node_id=219131]
* demerphq. "Yet Another Perl Object Model (Inside Out Objects)". December 14,
2002. [http://perlmonks.org/index.pl?node_id=219924]
* xdg. "Threads and fork and CLONE, oh my!". August 11, 2005.
[http://perlmonks.org/index.pl?node_id=483162]
* jdhedden. "Anti-inside-out-object-ism". December 9, 2005.
[http://perlmonks.org/index.pl?node_id=515650]
= SEE ALSO
* [Class::InsideOut]
* [Class::InsideOut::Manual::Advanced]
= AUTHOR
David A. Golden (DAGOLDEN)
= COPYRIGHT AND LICENSE
Copyright (c) 2006, 2007 by David A. Golden
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
L<http://www.apache.org/licenses/LICENSE-2.0>
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
=end wikidoc
# Generated by Pod::WikiDoc version 0.18
=pod
=head1 NAME
Class::InsideOut::Manual::About - guide to this and other implementations of the
inside-out technique
=head1 VERSION
This documentation refers to version 1.09
=head1 DESCRIPTION
This manual provides an overview of the inside-out technique and its
application within C<<< Class::InsideOut >>> and other modules. It also provides a
list of references for further study.
=head2 Inside-out object basics
Inside-out objects use the blessed reference as an index into lexical data
structures holding object properties, rather than using the blessed reference
itself as a data structure.
$self->{ name } = "Larry"; # classic, hash-based object
$name{ refaddr $self } = "Larry"; # inside-out
The inside-out approach offers three major benefits:
=over
=item *
Enforced encapsulation: object properties cannot be accessed directly
from ouside the lexical scope that declared them
=item *