summaryrefslogtreecommitdiff
path: root/lib/Class/MakeMethods/Docs
diff options
context:
space:
mode:
Diffstat (limited to 'lib/Class/MakeMethods/Docs')
-rw-r--r--lib/Class/MakeMethods/Docs/Catalog.pod888
-rw-r--r--lib/Class/MakeMethods/Docs/Changes.pod661
-rw-r--r--lib/Class/MakeMethods/Docs/Examples.pod554
-rw-r--r--lib/Class/MakeMethods/Docs/ReadMe.pod279
-rw-r--r--lib/Class/MakeMethods/Docs/RelatedModules.pod962
-rw-r--r--lib/Class/MakeMethods/Docs/ToDo.pod296
6 files changed, 3640 insertions, 0 deletions
diff --git a/lib/Class/MakeMethods/Docs/Catalog.pod b/lib/Class/MakeMethods/Docs/Catalog.pod
new file mode 100644
index 0000000..ba17349
--- /dev/null
+++ b/lib/Class/MakeMethods/Docs/Catalog.pod
@@ -0,0 +1,888 @@
+=head1 NAME
+
+Class::MakeMethods::Docs::Catalog - List of Makable Method Types
+
+
+=head1 DESCRIPTION
+
+This document lists the various subclasses of Class::MakeMethods included
+in this distribution, and the method types each one provides.
+
+See the documentation for each implementation for more details
+about the features it provides.
+
+For each class, a parenthetical comment indicates whether the methods it generates are applicable to individual blessed objects (Instances), to class data (Global), or both (Any)
+=head2 Scoping
+
+The final part of the name of a method-generating subclass typically indicates the scope or applicability of the methods it generates
+
+=over 4
+
+=item Hash
+
+For object instances based on blessed hashes with named values.
+
+=item Array
+
+For object instances based on blessed arrays with positional values.
+
+=item Scalar
+
+For object instances based on blessed scalars with a single value.
+
+=item InsideOut
+
+For any object instance regardless of underlying data type.
+
+=item Ref
+
+For any object instance regardless of underlying data type.
+
+=item Inheritable
+
+For data which can be set at the class, subclass, or instance level.
+
+=item Class
+
+For class data shared by all instances but different for each subclass
+
+=item ClassVar
+
+For class data shared by all instances but different for each subclass
+
+=item ClassInherit
+
+For class data shared by all instances but different for each subclass
+
+=item Global
+
+For global data shared by a class and all its instances and subclasses
+
+=item PackageVar
+
+For global data shared by a class and all its instances and subclasses
+
+=item Universal
+
+# General method types that are widely applicable
+
+=back
+
+=head2 Summary Charts
+
+This table shows which scopes are available in each generator family:
+
+ SCOPING Basic Standard Evaled Composite Template
+ Hash + + + + +
+ Array + + + +
+ Scalar +
+ InsideOut +
+ Ref +
+ Inheritable + + +
+ Class +
+ ClassVar +
+ ClassInherit +
+ Global + + + +
+ PackageVar +
+ Universal + +
+
+This table shows which types of methods are typically available in each generator family:
+
+ METHOD Basic Standard Evaled Composite Template
+ new + + + +
+
+ scalar + + + +
+ string +
+ string_index +
+ number +
+ boolean +
+ boolean_index +
+ bits +
+
+ array + + + +
+ struct +
+
+ hash + + + +
+ hash_of_arrays +
+ tiedhash +
+
+ object + + +
+ instance +
+ array_of_objects +
+
+ code +
+ code_or_scalar +
+
+
+=head1 BASIC CLASSES
+
+=head2 Basic::Hash (Instances)
+
+Methods for objects based on blessed hashes. See L<Class::MakeMethods::Basic::Hash> for details.
+
+=over 4
+
+=item *
+
+new: create and copy instances
+
+=item *
+
+scalar: get and set scalar values in each instance
+
+=item *
+
+array: get and set values stored in an array refered to in each
+instance
+
+=item *
+
+hash: get and set values in a hash refered to in each instance
+
+=back
+
+=head2 Basic::Array (Instances)
+
+Methods for manipulating positional values in arrays. See L<Class::MakeMethods::Basic::Array> for details.
+
+=over 4
+
+=item *
+
+new: create and copy instances
+
+=item *
+
+scalar: get and set scalar values in each instance
+
+=item *
+
+array: get and set values stored in an array refered to in each
+instance
+
+=item *
+
+hash: get and set values in a hash refered to in each instance
+
+=back
+
+=head2 Basic::Global (Global)
+
+Global methods are not instance-dependent; calling them by class
+name or from any instance or subclass will consistently access the
+same value. See L<Class::MakeMethods::Basic::Global> for details.
+
+=over 4
+
+=item *
+
+scalar: get and set a global scalar value
+
+=item *
+
+array: get and set values in a global array
+
+=item *
+
+hash: get and set values in a global hash
+
+=back
+
+
+=head1 STANDARD CLASSES
+
+=head2 Standard::Hash (Instances)
+
+Methods for objects based on blessed hashes. See L<Class::MakeMethods::Standard::Hash> for details.
+
+=over 4
+
+=item *
+
+new: create and copy instances
+
+=item *
+
+scalar: get and set scalar values in each instance
+
+=item *
+
+array: get and set values stored in an array refered to in each
+instance
+
+=item *
+
+hash: get and set values in a hash refered to in each instance
+
+=item *
+
+object: access an object refered to by each instance
+
+=back
+
+=head2 Standard::Array (Instances)
+
+Methods for manipulating positional values in arrays. See L<Class::MakeMethods::Standard::Array> for details.
+
+=over 4
+
+=item *
+
+new: create and copy instances
+
+=item *
+
+scalar: get and set scalar values in each instance
+
+=item *
+
+array: get and set values stored in an array refered to in each
+instance
+
+=item *
+
+hash: get and set values in a hash refered to in each instance
+
+=item *
+
+object: access an object refered to by each instance
+
+=back
+
+=head2 Standard::Global (Global)
+
+Methods for manipulating global data. See L<Class::MakeMethods::Standard::Global> for details.
+
+=over 4
+
+=item *
+
+scalar: get and set global scalar
+
+=item *
+
+array: get and set values stored in a global array
+
+=item *
+
+hash: get and set values in a global hash
+
+=item *
+
+object: global access to an object ref
+
+=back
+
+
+=head2 Standard::Inheritable (Any)
+
+Methods for manipulating data which may be overridden per class or instance. Uses external data storage, so it works with objects of any underlying data type. See L<Class::MakeMethods::Standard::Inheritable> for details.
+
+=over 4
+
+=item *
+
+scalar: get and set scalar values for each instance or class
+
+=back
+
+
+=head1 COMPOSITE CLASSES
+
+=head2 Composite::Hash (Instances)
+
+Methods for objects based on blessed hashes. See L<Class::MakeMethods::Composite::Hash> for details.
+
+=over 4
+
+=item *
+
+new: create and copy instances
+
+=item *
+
+scalar: get and set scalar values in each instance
+
+=item *
+
+array: get and set values stored in an array refered to in each
+instance
+
+=item *
+
+hash: get and set values in a hash refered to in each instance
+
+=item *
+
+object: access an object refered to by each instance
+
+=back
+
+=head2 Composite::Array (Instances)
+
+Methods for manipulating positional values in arrays. See L<Class::MakeMethods::Composite::Array> for details.
+
+=over 4
+
+=item *
+
+new: create and copy instances
+
+=item *
+
+scalar: get and set scalar values in each instance
+
+=item *
+
+array: get and set values stored in an array refered to in each
+instance
+
+=item *
+
+hash: get and set values in a hash refered to in each instance
+
+=item *
+
+object: access an object refered to by each instance
+
+=back
+
+=head2 Composite::Global (Global)
+
+Methods for manipulating global data. See L<Class::MakeMethods::Composite::Global> for details.
+
+=over 4
+
+=item *
+
+scalar: get and set global scalar
+
+=item *
+
+array: get and set values stored in a global array
+
+=item *
+
+hash: get and set values in a global hash
+
+=item *
+
+object: global access to an object ref
+
+=back
+
+
+=head2 Composite::Inheritable (Any)
+
+Methods for manipulating data which may be overridden per class or instance. Uses external data storage, so it works with objects of any underlying data type. See L<Class::MakeMethods::Composite::Inheritable> for details.
+
+=over 4
+
+=item *
+
+scalar: get and set scalar values for each instance or class
+
+=item *
+
+hook: create a subroutine intended to have operations added to it
+
+=back
+
+
+=head2 Composite::Universal (Any)
+
+Methods for padding pre- and post-conditions to any class. See L<Class::MakeMethods::Composite::Universal> for details.
+
+=over 4
+
+=item *
+
+patch: add pre and post operations to an existing subroutine
+
+=back
+
+
+=head1 TEMPLATE CLASSES
+
+=head2 Template::Universal (Any)
+
+Meta-methods for any type of object. See L<Class::MakeMethods::Template::Universal>.
+
+=over 4
+
+=item *
+
+no_op - a method with an empty body
+
+=item *
+
+croak - a method which will croak if called
+
+=item *
+
+method_init - calls other methods from a list of method name => argument pairs
+
+=item *
+
+forward_methods - delegates to an object provided by another method
+
+=back
+
+=head2 Template::Ref (Any Instance)
+
+Methods for deep copies and comparisons. See L<Class::MakeMethods::Template::Ref>.
+
+=over 4
+
+=item *
+
+clone: make a deep copy of an object instance
+
+=item *
+
+prototype: make new objects by cloning a typical instance
+
+=item *
+
+compare: compare one object to another
+
+=back
+
+
+=head2 Template::Generic (Abstract)
+
+The remaining subclasses inherit a similar collection of templates from Template::Generic, and provide a different type of scoping or binding for the functionality defined by the Generic template. See L<Class::MakeMethods::Template::Generic> for details.
+
+
+=head2 Template::Hash (Instances)
+
+The most commonly used implementation, for objects based on blessed hashes. See L<Class::MakeMethods::Template::Hash>.
+
+=over 4
+
+=item *
+
+new: create and copy instances
+
+=item *
+
+scalar: get and set scalar values in each instance
+
+=item *
+
+string: get and set string values in each instance
+
+=item *
+
+number: get and set numeric values in each instance
+
+=item *
+
+boolean: get and set boolean values in each instance
+
+=item *
+
+bits: get and set boolean values stored in a single value in each
+instance
+
+=item *
+
+array: get and set values stored in an array refered to in each
+instance
+
+=item *
+
+struct - methods for acccessing values which are stored by
+position in an array
+
+=item *
+
+hash: get and set values in a hash refered to in each instance
+
+=item *
+
+tiedhash: get and set values in a tied hash refered to in each
+instance
+
+=item *
+
+hash_of_arrays: for references to hashes of arrays contained in each
+instance
+
+=item *
+
+object: set or access a reference to an object contained in each
+instance
+
+=item *
+
+array_of_objects: manipulate an array of object references within in
+each instance
+
+=item *
+
+code: set or call a function reference contained in each instance
+
+=back
+
+
+=head2 Template::Array (Instances)
+
+Methods for manipulating positional values in arrays. See L<Class::MakeMethods::Template::Array>.
+
+=over 4
+
+=item *
+
+new: create and copy array instances
+
+=item *
+
+scalar: get and set scalar values in a given array position
+
+=item *
+
+string: get and set string values in a given array position
+
+=item *
+
+number: get and set numeric values in a given array position
+
+=item *
+
+boolean: get and set boolean values in a given array position
+
+=item *
+
+builtin_isa: generates a wrapper around some builtin function,
+cacheing the results in the object and providing a by-name interface
+
+=back
+
+
+
+=head2 Template::Scalar (Instances)
+
+For objects based on blessed scalars. See L<Class::MakeMethods::Template::Scalar>.
+
+Note that these objects can generally only have one value accessor method, as all such accessors will refer to the same value.
+
+=over 4
+
+=item *
+
+new: create and copy instances
+
+=item *
+
+scalar: get and set scalar values in each instance
+
+=item *
+
+string: get and set a string value in each instance
+
+=item *
+
+number: get and set a numeric value in each instance
+
+=item *
+
+boolean: get and set a boolean value in each instance
+
+=item *
+
+bits: get and set boolean values stored in a single value in each
+instance
+
+=item *
+
+code: set or call a function reference contained in each instance
+
+=back
+
+
+=head2 Template::InsideOut (Instances)
+
+Stores values for objects in an external location hashed by identity. See L<Class::MakeMethods::Template::InsideOut>.
+
+Note that while the below constructor creates and returns scalar
+references, accessor methods can be created with this implementation
+for use with any type of object.
+
+=over 4
+
+=item *
+
+new: create and copy instances
+
+=item *
+
+scalar: get and set scalar values associated with each instance
+
+=item *
+
+string: get and set string values associated with each instance
+
+=item *
+
+string_index: get and set string values associated with each
+instance, and maintain an index of instances by value
+
+=item *
+
+number: get and set numeric values associated with each instance
+
+=item *
+
+boolean: get and set boolean values associated with each instance
+
+=item *
+
+boolean_index: get and set boolean values associated with each instance, and maintain a list of items which have the flag set
+
+=item *
+
+bits: get and set boolean values stored in a single value associated with each
+instance
+
+=item *
+
+array: get and set values stored in an array associated with each
+instance
+
+=item *
+
+hash: get and set values in a hash associated with each instance
+
+=item *
+
+code: set or call a function reference associated with each instance
+
+=back
+
+
+=head2 Template::Global (Global)
+
+Global methods are not instance-dependent; calling them by class
+name or from any instance will consistently access the same value. See L<Class::MakeMethods::Template::Static>.
+
+=over 4
+
+=item *
+
+scalar: get and set a global scalar value
+
+=item *
+
+string: get and set a global string value
+
+=item *
+
+number: get and set a global number value
+
+=item *
+
+boolean: get and set a global boolean value
+
+=item *
+
+array: get and set values in a global array
+
+=item *
+
+hash: get and set values in a global hash
+
+=item *
+
+tiedhash: get and set values in a global tied hash
+
+=item *
+
+hash_of_arrays: get and set values in a global hash of arrays
+
+=item *
+
+object: set and access a global reference to an object
+
+=item *
+
+instance: set and access a global reference to an object of the declaring class
+
+=item *
+
+code: set and access a global reference to a subroutine.
+
+=back
+
+
+=head2 Template::PackageVar (Global)
+
+PackageVar methods access a variable in the declaring package. Thus,
+they have the same effect as Static methods, while keeping their
+value accessible via the symbol table. See L<Class::MakeMethods::Template::PackageVar>.
+
+=over 4
+
+=item *
+
+scalar: get and set a global scalar value
+
+=item *
+
+string: get and set a global string value
+
+=item *
+
+number: get and set a global number value
+
+=item *
+
+boolean: get and set a global boolean value
+
+=item *
+
+array: get and set values in a global array
+
+=item *
+
+hash: get and set values in a global hash
+
+=back
+
+
+=head2 Template::Class (Global)
+
+Class methods are similar to Static methods, except that each subclass and its instances will access a distinct value. See L<Class::MakeMethods::Template::Class>.
+
+=over 4
+
+=item *
+
+scalar: get and set a class-specific scalar value
+
+=item *
+
+string: get and set a class-specific string value
+
+=item *
+
+number: get and set a class-specific number value
+
+=item *
+
+boolean: get and set a class-specific boolean value
+
+=item *
+
+array: get and set values in a class-specific array
+
+=item *
+
+hash: get and set values in a class-specific hash
+
+=back
+
+
+=head2 Template::ClassVar (Global)
+
+ClassVar methods access a variable in the package on which they
+are called. Thus, they have the same effect as Class methods,
+while keeping their value accessible via the symbol table, like
+PackageVar. See L<Class::MakeMethods::Template::ClassVar>.
+
+=over 4
+
+=item *
+
+scalar: get and set a class-specific scalar value
+
+=item *
+
+string: get and set a class-specific string value
+
+=item *
+
+number: get and set a class-specific number value
+
+=item *
+
+boolean: get and set a class-specific boolean value
+
+=item *
+
+array: get and set values in a class-specific array
+
+=item *
+
+hash: get and set values in a class-specific hash
+
+=back
+
+
+=head2 Template::ClassInherit (Global)
+
+ClassInherit methods are an intermediate point between Static and Class methods; subclasses inherit their superclass's value until they set their own value, after which they become distinct. See L<Class::MakeMethods::Template::ClassInherit>.
+
+=over 4
+
+=item *
+
+scalar: get and set an inheritable class-specific scalar value
+
+=item *
+
+string: get and set an inheritable class-specific string value
+
+=item *
+
+number: get and set an inheritable class-specific number value
+
+=item *
+
+boolean: get and set an inheritable class-specific boolean value
+
+=item *
+
+array: get and set values in an inheritable class-specific array
+
+=item *
+
+hash: get and set values in an inheritable class-specific hash
+
+=back
+
+
+=head2 Template::Inheritable (Any)
+
+Methods for manipulating data which may be overridden per class or instance. Uses external data storage, so it works with objects of any underlying data type. See L<Class::MakeMethods::Template::Inheritable> for details.
+
+=over 4
+
+=item *
+
+scalar: get and set scalar values for each instance or class
+
+=item *
+
+string: get and set string values for each instance or class
+
+=item *
+
+number: get and set numeric values for each instance or class
+
+=item *
+
+boolean: get and set boolean values for each instance or class
+
+=item *
+
+hash: get and set values in a hash refered to in each instance
+
+=back
+
+
+=head1 SEE ALSO
+
+See L<Class::MakeMethods> for general information about this distribution.
+
+=cut
diff --git a/lib/Class/MakeMethods/Docs/Changes.pod b/lib/Class/MakeMethods/Docs/Changes.pod
new file mode 100644
index 0000000..8b01f0a
--- /dev/null
+++ b/lib/Class/MakeMethods/Docs/Changes.pod
@@ -0,0 +1,661 @@
+=head1 NAME
+
+Class::MakeMethods::Docs::Changes - History of Class::MakeMethods
+
+=head1 SYNOPSIS
+
+Revision history for Class::MakeMethods.
+
+=head1 CHANGES
+
+=head2 Version 1.010
+
+=over 4
+
+=item 2004/09/06
+
+Moved get_declarations() and associated documentation from Standard module to superclass.
+
+=item 2004/09/03
+
+Developed test.pl test harness with recursive file search to fix Windows "command line too long" errors.
+
+=item 2004/09/01
+
+Moved Template::TextBuilder and Template::DiskCache into Utility:: namespace.
+
+Added support for defaults with -- and -param to Standard get_declarations().
+
+=item 2004/08/12
+
+Began testing and integrating tied-value patches from Dominique Dumont.
+
+=item 2004/04/27
+
+Added method types to Evaled::Hash.
+
+=item 2004/04/23
+
+Added skeleton of a new Evaled::Hash class.
+
+=back
+
+=head2 Version 1.009
+
+=over 4
+
+=item 2003/09/25
+
+Added Emulator::mcoder and compatibility tests.
+
+Released to CPAN as Class-MakeMethods-1.009.tar.gz.
+
+=item 2003/09/22
+
+Added support for lvalue methods to Template and Template::Generic. Added a few tests to demonstrate they're working. Added an example to Docs::Examples.
+
+Added Emulator::accessors and compatibility tests.
+
+Minor documentation improvements.
+
+=back
+
+=head2 Version 1.008
+
+=over 4
+
+=item 2003/09/05
+
+Adjusted layout of test directories in another attempt to solve a MakeMaker/shell-glob issue on Windows that was preventing make test from running correctly.
+
+Removed Template::PseudoHash, since this package never really worked, as pointed out by a question from Mike Castle. Management of array-based objects can be handled by any of the existing ::Array subclasses, and support for pseudo-hashes would not provide any useful new capabilities.
+
+Added support for "Template::Universal:forward_methods -delegate" and "Template::Generic:object --soft_delegate" based on a suggestion from Peter Chen. Extended behavior of Template -subs handling to make it easy to add such functionality in the future.
+
+Released to CPAN as Class-MakeMethods-1.008.tar.gz.
+
+=item 2003/09/02
+
+Adjusted DESTROY behavior of Template::InsideOut and cleaned up documentation.
+
+=back
+
+=head2 Version 1.007
+
+=over 4
+
+=item 2003/09/01
+
+Made Template definitions automatically import their class's generic
+definitions, if present. This eliminates the need for Generic
+subclasses to explicitly redeclare every method it inherits, and
+should obviate the "missing declaration" problems referenced below.
+
+Updated the names of several Template subclasses, with stubs at
+the old names for backwards compatibility: Flyweight becomes
+InsideOut, Static becomes Global, and Struct becomes Array.
+
+Added Template::Inheritable and basic tests for it.
+
+Eliminated use of legacy Test.pm from remaining tests, except for
+MethodMaker emulation.
+
+Rearranged test directories in an effort to avoid a reported bug
+with the test path of t/*/*.t under Windows.
+
+Released to CPAN as Class-MakeMethods-1.007.tar.gz.
+
+=item 2003/08/27
+
+Added section to Class::MakeMethods/EXTENDING documentation based
+on question from Terrence Brannon.
+
+=item 2003/02/07
+
+Fixed missing declaration of Template::Hash:instance, reported via RT.
+
+=back
+
+=head2 Version 1.006
+
+=over 4
+
+=item 2003/01/26
+
+Additional documentation touch-ups. Moved miscellaneous POD files into the Docs directory.
+
+Added new test scripts from Class-MethodMaker-1.08, although we
+don't yet pass them. In particular, I need to add support for the
+new method types added in 1.04: tie_scalar, tie_list, object_tie_list,
+object_tie_hash
+
+Also need to compare against the changes included in Class-MethodMaker-1.09 and 1.10, which don't seem to include any new test code, but do include functionality changes.
+
+=item 2002/12/12
+
+Re-integrated Template and Emulator packages; the separate distribution
+turned out to be a hastle rather than a convenience. However, in
+order to keep test scripts for each subsystem separate, I'm now
+using a Makefile.PL attribute to specify a two-level deep directory
+tree of test scripts; I hope this doesn't break on Windows...
+
+Fixed possible "use of undefined as a reference" problem in
+Standard::*::array method generators, reported by Jared Rhine.
+
+Tried to improve documentation, based on feedback from Jared Rhine.
+Expunged ReadMe.pod. Extracted method catalogs into Catalog.pod.
+Moved examples to new Example.pod, although that underlines how
+few examples there are.
+
+=back
+
+
+=head2 Version 1.005
+
+=over 4
+
+=item 2002/06/06
+
+Added Autoload interface.
+
+Modifed Attribute interface to add "inheritable" default logic for
+Maker class parameter. (Suggested by Malcolm Cook.)
+
+Fixed typo in documentation for Standard::Universal. (Spotted by
+Malcolm Cook.)
+
+=back
+
+
+=head2 Version 1.004
+
+=over 4
+
+=item 2002/03/23
+
+Released to CPAN as Class-MakeMethods-1.004.tar.gz.
+
+=item 2002/03/16
+
+Allow double-colons between package name and method generator name.
+
+=item 2002/02/19
+
+Fixed related use of undef in Standard::*:hash methods.
+
+=item 2002/02/14
+
+Adjusted Standard::*:hash methods to avoid assuming that the hashref
+already exists.
+
+=item 2002/02/07
+
+Added missing *_reset => clear to Template number --counter interface.
+
+=item 2002/02/02
+
+Adjusted error message in Utility::ArraySplicer
+
+=item 2002/01/26
+
+Applied small documentation corrections suggested by Adam Spiers.
+
+Added Standard::Universal:alias.
+
+=back
+
+=head2 Version 1.003
+
+=over 4
+
+=item 2002/01/24
+
+Folded "Getting Started Guide" POD into main module documentation.
+
+Renamed Utility::TakeName to Emulator.
+
+Split Template and Emulator packages into their own distributions.
+
+B<Please Note:> This means that to fully upgrade you must retrieve
+all three of these files:
+
+ Class-MakeMethods-1.003.tar.gz
+ Class-MakeMethods-Template-1.003.tar.gz
+ Class-MakeMethods-Emulator-1.003.tar.gz
+
+Of course, if you're not using the Template or Emulator classes,
+there's no need to download them...
+
+
+=item 2002/01/21
+
+Started bumping sub-version numbers and not using sub-sub-versions,
+to shorten distribution names and more closely match standard
+practice.
+
+Added Composite::Inheritable:hook and matching test. Added
+Composite->CurrentResults method to easily access, update composite
+method results.
+
+=back
+
+=head2 Version 1.000.*
+
+=over 4
+
+=item v1.000.16 - 2002/01/21
+
+Released to CPAN as v1.000.016.
+
+=item v1.000.16 - 2002/01/20
+
+Adjusted the hash and array methods in the Standard::* and Composite::*
+packages to properly accept a set-contents call with a single
+reference argument, and to return contents rather than ref in list
+context.
+
+=item v1.000.16 - 2002/01/14
+
+Fixed a subtle bug in a test script inherited from Class::MethodMaker:
+4_Template_hash_hash_array.t and 7_MethodMaker_hash_of_lists.t both
+relied on "keys %hash" returning the keys in a particular order,
+which *almost* always worked, but caused failures on one or more
+Perl version/platform combinations.
+
+
+=item v1.000.15 - 2002/01/14
+
+Released to CPAN as v1.000.015.
+
+=item v1.000.15 - 2002/01/12
+
+Renamed Basic::Static to Basic::Global for consistency with Standard
+and Composite. Hopefully, there aren't many users of this module
+yet; please accept my apologies if this breaks your code.
+
+Eliminated "local @_ = ...", which appears to cause a scoping
+problem on Perl 5.6. Thanks to Adam Spiers for a thorough bug
+report. (See http://www.perlmonks.org/index.pl?node_id=138370 for
+details.)
+
+Extended Template::Generic to support "array --get_set_ref" method
+style requested by Adam Spiers.
+
+Various documentation tweaks, including feedback from Adam Spiers:
+Adjusted documentation to downplay Basic::* modules as a starting
+point, in favor of Standard::* ones. Trimmed out some duplicated
+documentation in favor of more "See LE<lt>...E<gt>" links. Adjusted
+documentation of *::Inheritable packages in an attempt to clarify
+the way in which the inheritance tree is searched for a value.
+
+Factored out common code from Standard::Inheritable and
+Composite::Inheritable to new module, Utility::Inheritable. Factored
+out common code from Standard::Hash and Standard::Array to new
+module, Utility::ArraySplicer. Factored out common code from
+Template::Universal to new module, Utility::Ref. Renamed
+Emulator::TakeName to Utility::TakeName (this is internal use only,
+so there should be no public impact).
+
+
+=item v1.000.15 - 2001/12/01
+
+Adjusted Template::Universal's code for _CALL_METHODS_FROM_HASH_,
+to ensure that method/arg pairs are called in order they were passed
+in.
+
+=item v1.000.15 - 2001/07/04, 2001/07/19
+
+Minor additions to documentation of various method types.
+
+
+=item v1.000.14 - 2001/07/01
+
+Released as v1.000.014.
+
+
+=item v1.000.14 - 2001/06/25, 2001/06/29, 2001/07/01
+
+Removed Makefile rule from Makefile.PL to avoid warnings when used
+with recent versions of ExtUtils::MakeMaker, which also define a
+similar rule. (Based on bug report from Ron Savage.)
+
+Fixed test failure for machines with P5.6 but no Attribute::Handlers.
+(Reported by Ron Savage, Jay Lawrence.)
+
+Added Template::Flyweight:string_index. (But still needs test
+script.)
+
+Added Standard::Universal. (But still needs test scripts.)
+
+Minor touch-ups to ReadMe and Guide documentation.
+
+
+=item v1.000.13 - 2001/05/16, 2001/05/18, 2001/05/20, 2001/06/02, 2001/06/22, 2001/06/24
+
+To date, this module has been circulated under several provisional
+names: it was originally floated as a possible version-2 rewrite
+of Class::MethodMaker, then renamed to Class::Methods when it forked
+from that project, and then briefly to Class::MethodGenerator.
+(Note that it can be surprisingly difficult to comply with both of
+these L<perlmodlib> guidelines: "To be portable each component of
+a module name should be limited to 11 characters. [...] Always
+try to use two or more whole words.") In the end, I selected
+Class::MakeMethods, as it is two whole words, and is reminiscent
+of Class::MethodMaker without being confusing (I hope!), and I
+believe this issue is now settled.
+
+Standardized syntax for global options; renamed -implementation to
+-MakerClass and -target_class to -TargetClass. Moved $TargetClass
+and other context information into %CONTEXT with _context accessor.
+Added ForceInstall.
+
+Completed re-simplification of build directories; we're back to a
+single Makefile, which avoids a warning in P5.6.0.
+
+Added Attribute interface for use with P5.6 and later, based on
+Attribute::Handlers.
+
+Renamed "Simple" subclasses to "Basic". Added documentation and
+initial tests.
+
+Added Standard subclasses with parameter parsing and more powerful
+accessors.
+
+Modified Emulator::Struct to use Standard::* methods. Found struct
+test from P5.7, and added auto_init functionality to match.
+
+Added Composite::* subclasses.
+
+Added Emulator::AccessorFast.
+
+Added Class::MakeMethods::Guide with introduction and examples.
+
+Continued clean-up effort on Template documentation. Renamed Template
+"attributes" to "method parameters" to avoid confusion with Perl
+attributes. Retitled Template naming rules from "templates" to
+"interfaces".
+
+Changed initialization code expressions of Template::Class in hopes
+of P5.6.1 compatibility. (Problem reported by M Schwern.)
+
+Added 'Template::Generic:new --and_then_init' based on feedback
+from Jay Lawrence.
+
+=back
+
+=head2 Early 1.000 versions
+
+=over 4
+
+=item v1.000.12 - 2001/05/14
+
+Renamed module to Class::MethodGenerator, although naming questions
+remain.
+
+Moved Template subclasses into Template::* namespace. Simplified
+build directory and makefile structure.
+
+Changed initialization code expressions of Template::PackageVar,
+ClassVar for P5.6.0 compatibility. (Reported by M Schwern.)
+
+
+=item v1.000.11 - 2001/05/07, 2001/05/12
+
+Eliminated Bundle file. Moved general documentation to cm_base.
+
+Renamed Class::Methods::Base to Class::Methods::Generator.
+
+Extracted code for Template declarations to new Class::Methods::Template
+module. Extracted disk-caching to new Template::DiskCache module.
+Moved TextBuilder into the Template:: tree.
+
+Moved _namespace_capture code to new package
+Class::Methods::Emulator::TakeName.
+
+Added Simple::Hash subclass.
+
+
+=item v1.000.10 - 2001/04/26, 2001/05/02, 2001/05/04
+
+Moved _namespace_capture and _namespace_release to Class::Methods::Base.
+
+Additional doc tweakage. Moved ReadMe documentation to
+Bundle::ClassMethods. Merged Extending documentation into Base.
+
+Removed spurious uses of -default => 'default' in templates.
+
+Added new ClassInherit subclass and Emulator::Inheritable.
+
+Expunged Index subclass in favor of boolean_index and string_index
+types on Generic.
+
+Moved Struct:builtin_isa type to new package, StructBuiltin.
+
+Refactored code templating function as Class::Methods::Base::TextBuilder.
+
+
+=item v1.000.9 - 2001/03/24
+
+Reversed sense of - and --, as it was in 1.000.1.
+
+Separated source files into separate directories with distinct
+Makefiles and test hierarchies. This should clarify the boundaries
+between the core method-generation code, the common constructor/accessor
+methods, and the various emulator and experimental packages.
+
+
+=item v1.000.8 - 2001/01/19
+
+Following receipt of a suggestion to fork from the maintainer of
+Class::MethodMaker, renamed packge from Class::MethodMaker v2.0 to
+Class::Methods v1.000.
+
+Adjusted documentation to reflect fork, although additional cleanup
+is still needed.
+
+Moved backward compatibility to Emulator::MethodMaker subclass.
+
+Added Generic -compatibility array index_* and hash_of_arrays *_last
+and *_set methods to match changes in Class::MethodMaker v1.02.
+Added Emulator::MethodMaker support for the '-static' flag. The
+emulator now completely satisfies the enclosed test suites, from
+Class::MethodMaker v0.92 and v1.02.
+
+
+=item v1.000.7 - 2001/01/05, 2001/01/06, 2001/01/07
+
+Moved core code and internal code to Internals.pm. MethodMaker.pm
+now contains only some require statements and the general user
+guide documentation.
+
+Moved ReadMe.pod, Changes.pod, and ToDo.pod into MethodMaker
+directory. Separated Catalog.pod, Extending.pod, RelatedModules.pod.
+
+Included version 1 docs as Class::Methods::OriginalDocs; minor
+revisions for clarity.
+
+Renamed Package subclass to PackageVar, Class to ClassVar.
+
+Added Emulation::Struct subclass.
+
+Added support for shifting targets with make( -target_class =>
+Package, ... ).
+
+Extended ClassName subclass to handle requiring, rather than creating
+subclases.
+
+
+=item v1.000.6 - 2000/12/29, 2001/01/02, 2001/01/04
+
+Restored -sugar import option for compatibility with earlier
+versions.
+
+Added plural names to "Generic:hash -compatibility" to support
+v0.92 usage.
+
+Replaced use of substr(..., 0, 1) with ... =~ s/^-// for P5.004
+compatibility; problem found by Scott Godin.
+
+Copy @_ before splicing and pushing on to it for P5.004 compatibility.
+
+Expunged duplicate lines from Generic.pm's array_of_objects; found
+by Ron Savage.
+
+Renamed Hash.pm's delete and exists behaviors to avoid possible
+run-time import conflict with Generic.pm's behaviors; failure
+reported by Ron Savage.
+
+Added _STATIC_ATTR_{return_value_undefined} attributes to Generic
+string and number to allow overrides of this functionality.
+
+Minor doc touchups and expanded examples section.
+
+
+=item v1.000.5 - 2000/11/28, 2000/12/16, 2000/12/28
+
+Added Universal -warn_calls modifier.
+
+Folded various pod files together into main module's inline
+documentation. Updated catalog of existing implementations in
+documentation. Added pointers to some tutorials and books which
+discuss Class::Methods.
+
+Standardized naming of test scripts.
+
+Can now specify default template name, via -default=>"foo".
+
+
+=item v1.000.4 - 2000/11/22
+
+Separated string, number, and boolean from the Generic scalar
+methods.
+
+Provide _disk_cache to shortcut the lengthy _interpret_text_builder
+process.
+
+Fixes to ClassName implementation.
+
+Change to forward methods to provide better error messages when
+object is empty.
+
+
+=item v1.000.3 - 2000/11/03
+
+Rearranged documentation into separate files in the pod/ directory.
+
+Collapsed find_target_class and make functionality into import;
+moved support for the old functions to the Compatibility module.
+
+Adjusted tests to generally use standard syntax, and not Compatibility
+hooks.
+
+
+=item v1.000.2.1 - 2000/10/23
+
+Moved commonly-accessible information to Universal.
+
+Added block{...} replacement for enhanced behavior templating.
+
+Added modifier mechanism to support -private and -protected.
+
+May need to be able to specify import ordering so that modifiers
+are applied in the right order. This hasn't bit me yet, but it's
+there. Darn.
+
+
+=item v1.000.2 - 2000/10/22
+
+Completed generalization of Generic methods from Static and Hash.
+Rewrote ClassVar and PackageVar to use Generic framework.
+
+Attribute expansion can now substitute values besides name, using
+*{attr}.
+
+Added _diagnostics function and documentation of all failure
+messages.
+
+Added SEE ALSO section to documentation, brief review of Class::*
+on CPAN. Stumbled across Damian Conway's very nice Class::Contract
+module.
+
+Added Scalar and Flyweight implementations.
+
+
+=item v1.000.1.1 - 2000/10/21
+
+Rolled back change from yesterday; can still pick templates like
+'-java'. Allow attributes to be specified as '--foo'=>'bar' or
+'--'=>{foo=>'bar'}
+
+Automated caching for meta-method definition hashes.
+
+Generalized several Static and Hash interfaces into Generic templates.
+Added Static:array and Static:code support.
+
+Allow global -import to set default sources for templates, exprs,
+behaviors.
+
+
+=item v1.000.1 - 2000/10/19
+
+Support inheritance of templates between meta-methods with -import.
+
+Made "template" an attribute, rather than a special state variable.
+
+Allow any attribute to be specified as -foo=>'bar'. Changed
+selection of standard templates from '-java' to '--java'.
+
+Initial support for string-eval behaviors and code_exprs, and
+Generic.pm
+
+
+=item v1.000.0 - 2000/10/14, 2000/10/15
+
+Completed initial pass of full rewrite.
+
+Assorted cleanup of syntax and documentation.
+
+Moved Hash, Static, and Index implementations into separate packages.
+
+
+=item v0.9.3 - 2000/09/30
+
+Refactored subclass_name and class_registry.
+
+Folded in some misc improvements from Class::MethodMaker 1.0.
+
+
+=item v0.97x - 2000/08/04 to 2000/08/13
+
+Forked from Class::MethodMaker 0.96. Substantial rewrite started
+
+Created build_meta_method and refactored many methods to use it.
+
+Added new_hash, hash_init, new_from_prototype.
+
+Extended arg format. Added -template=>behavior_name. Added support
+for array-of-names arguments.
+
+Performance tuning. Additional refactoring to support AutoSplit
+functionality.
+
+Also folded in some older changes and additions from Evolution's
+internal collection of MethodMaker subclasses:
+
+=back
+
+=head2 Class::MethodMaker::Extensions
+
+Change notes from unreleased collection of extensions to Class::MethodMaker that were later folded into Class::MakeMethods:
+
+ 2000/01/12 Added set_foo, clear_foo to class_var hashes.
+ 1999/07/27 Added subclass_name.
+ 1999/04/15 Changed class_var to use symbol table lookups, not eval "".
+ 1999/04/05 Changed determine_once to check again if undefined.
+ 1999/03/25 Added singleton method.
+ 1998/09/18 Finished integration of class_registry handlers.
+ 1998/07/31 Added class_var and classnames handlers.
+ 1998/06/12 Added lookup handlers.
+ 1998/05/09 Created no_op and determine_once method groups.
+
+=cut
diff --git a/lib/Class/MakeMethods/Docs/Examples.pod b/lib/Class/MakeMethods/Docs/Examples.pod
new file mode 100644
index 0000000..787ace7
--- /dev/null
+++ b/lib/Class/MakeMethods/Docs/Examples.pod
@@ -0,0 +1,554 @@
+=head1 NAME
+
+Class::MakeMethods::Docs::Examples - Sample Declarations and Usage
+
+=head1 EXAMPLES
+
+The following examples indicate some of the capabilities of
+Class::MakeMethods.
+
+=head2 A Contrived Example
+
+Object-oriented Perl code is widespread -- you've probably seen code like the below a million times:
+
+ my $obj = MyStruct->new( foo=>"Foozle", bar=>"Bozzle" );
+ if ( $obj->foo() =~ /foo/i ) {
+ $obj->bar("Barbados!");
+ }
+
+Here's a possible implementation for the class whose interface is
+shown above:
+
+ package MyStruct;
+
+ sub new {
+ my $callee = shift;
+ my $self = bless { @_ }, (ref $callee || $callee);
+ return $self;
+ }
+
+ sub foo {
+ my $self = shift;
+ if ( scalar @_ ) {
+ $self->{'foo'} = shift();
+ } else {
+ $self->{'foo'}
+ }
+ }
+
+ sub bar {
+ my $self = shift;
+ if ( scalar @_ ) {
+ $self->{'bar'} = shift();
+ } else {
+ $self->{'bar'}
+ }
+ }
+
+Class::MakeMethods allows you to simply declare those methods to
+be of a predefined type, and it generates and installs the necessary
+methods in your package at compile-time.
+
+Here's the equivalent declaration for that same basic class:
+
+ package MyStruct;
+ use Class::MakeMethods::Standard::Hash (
+ 'new' => 'new',
+ 'scalar' => 'foo',
+ 'scalar' => 'bar',
+ );
+
+=head2 A Typical Example
+
+The following example shows a common case of constructing a class with several types of accessor methods
+
+ package MyObject;
+ use Class::MakeMethods::Standard::Hash (
+ new => 'new',
+ scalar => [ 'foo', 'bar' ],
+ array => 'my_list',
+ hash => 'my_index',
+ );
+
+This class now has a constructor named new, two scalar accessors named foo and bar, and a pair of reference accessors named my_list and my_index. Typical usage of the class might include calls like the following:
+
+ my $obj = MyObject->new( foo => 'Foozle' );
+ print $obj->foo();
+
+ $obj->bar('Barbados');
+ print $obj->bar();
+
+ $obj->my_list(0 => 'Foozle', 1 => 'Bang!');
+ print $obj->my_list(1);
+
+ $obj->my_index('broccoli' => 'Blah!', 'foo' => 'Fiddle');
+ print $obj->my_index('foo');
+
+=head2 Lvalue Accessors
+
+The Template subclasses support an optional "--lvalue" modifer that causes your accessors method to be marked as returning an lvalue which can be assigned to. (This feature is only available on Perl 5.6 or later.)
+
+ package MyStruct;
+ use Class::MakeMethods::Template::Hash (
+ 'new' => 'new',
+ 'scalar --get --lvalue' => 'foo',
+ 'array --get --lvalue' => 'bar',
+ );
+
+ $obj->foo = "Foozle";
+ print $obj->foo;
+
+ $obj->bar = ( 'baz', 'beep', 'boop' );
+ print $obj->bar->[1]; # beep
+
+=head2 String and Numeric Accessors
+
+In addition to the C<scalar> accessor supported by the C<Standard::*> classes, the Template subclasses also provide specialized accessors that can facilitate the use of specific types of data.
+
+For example, we could declare the following class to hold information
+about available Perl packages:
+
+ package MyVersionInfo;
+ use Class::MakeMethods::Template::Hash (
+ 'new' => 'new',
+ 'string' => 'package',
+ 'number' => 'version',
+ );
+
+ sub summary {
+ my $self = shift;
+ return $self->package() . " is at version " . $self->version()
+ }
+
+You could use this class as follows:
+
+ package main;
+ use MyVersionInfo;
+
+ my $obj = MyVersionInfo->new( package=>"Class::MakeMethods");
+ $obj->version( 2.0 );
+ print $obj->summary();
+
+These accessors will provide a bit of diagnostic type checking;
+an attempt to call C<$obj-E<gt>version("foo")> will cause your
+program to croak.
+
+
+=head2 String Concatenation Interface
+
+The following defines a get_concat method C<i>, and specifies
+a string to use when joining additional values when this method is
+called.
+
+ use Class::MakeMethods::Template::Hash
+ 'string' => [ '--get_concat', 'i', { join => ' - ' } ];
+
+(See L<Class::MakeMethods::Template::Generic> for information about the C<string> C<get_concat> interface.)
+
+
+=head2 Access Control Example
+
+The following defines a secret_password method, which will croak
+if it is called from outside of the declaring package.
+
+ use Class::MakeMethods::Composite::Hash
+ 'scalar' => [ 'secret_password' => { permit => 'pp' } ];
+
+(See L<Class::MakeMethods::Composite> for information
+about the C<permit> modifier.)
+
+For template classes, the same thing is accomplished with '--private':
+
+ use Class::MakeMethods::Template::Hash
+ 'scalar' => [ '--private', 'secret_password' ];
+
+(See L<Class::MakeMethods::Template::Universal> for information
+about the C<private> modifier.)
+
+
+=head2 Lazy-Init Interface
+
+Templapte scalar accessors declared with the "init_and_get" interface
+can be used for "memoization" or lazy-evaluation for object
+attributes. If the current accessor value is undefined, they will
+first call a user-provided init_* method and save its value.
+
+ package MyWidget;
+ use Class::MakeMethods::Template::Hash (
+ 'new --with_values' => [ 'new' ],
+ 'scalar --init_and_get' => [ 'foo', 'count', 'result' ],
+ );
+
+ sub init_foo {
+ return 'foofle';
+ }
+
+ sub init_count {
+ return '3';
+ }
+
+ sub init_result {
+ my $self = shift;
+ return $self->foo x $self->count;
+ }
+ ...
+
+ my $widget = MyWidget->new();
+ print $widget->result; # output: fooflefooflefoofle
+
+ # if values are predefined, the init methods are not used
+ my $other_widget = MyWidget->new( foo => 'bar', count => 2 );
+ print $widget->result; # output: barbar
+
+(See L<Class::MakeMethods::Template::Generic> for more information about
+C<init_and_get>. This interface is also supported by all of Generic's
+subclasses, so you can add lazy-init methods for global data, class
+data, array objects, etc. Unfortunately, to date it is only supported
+for scalar-value accessors...)
+
+
+=head2 Helper Methods
+
+Template methods often include similarly-named "helper" methods. For example, specifying the "--with_clear" interface for Template::*:scalar methods creates an extra method for each accessor x named clear_x.
+
+ package MyClass;
+ use Class::MakeMethods::Template::Hash('scalar --with_clear' => 'foo');
+
+ my $obj = MyClass->new;
+ $obj->foo(23);
+ $obj->clear_foo;
+ print $obj->foo();
+
+
+=head2 Reference Accessor and Helper Methods
+
+For references to arrays and hashes, the Template subclasses provide
+accessors with extra "helper methods" to facilitate method-based
+interaction.
+
+Here's a class whose instances each store a string and an array
+reference, along with a method to search the directories:
+
+ package MySearchPath;
+ use Class::MakeMethods::Template::Hash (
+ 'new' => 'new',
+ 'string' => 'name',
+ 'array' => 'directories',
+ );
+
+ sub search {
+ my $self = shift;
+ my $target = shift;
+ foreach my $dir ( $self->directories ) {
+ my $candidate = $dir . '/' . $target;
+ return $candidate if ( -e $candidate );
+ }
+ return;
+ }
+
+Note that the directories accessor returns the contents of the
+array when called in a list context, making it easier to loop over.
+
+And here's a sample usage:
+
+ package main;
+ use MySearchPath;
+
+ my $libs = MySearchPath->new( name=>"libs", directories=>['/usr/lib'] );
+ $libs->push_directories( '/usr/local/lib' );
+
+ print "Searching in " . $libs->count_directories() . "directories.\n";
+ foreach ( 'libtiff', 'libjpeg' ) {
+ my $file = $libs->search("$_.so");
+ print "Checking $_: " . ( $file || 'not found' ) . "\n";
+ }
+
+Note the use of the push_* and count_* "helper" accessor methods,
+which are defined by default for all 'Template::*:array' declarations.
+
+Consult L<Class::MakeMethods::Template::Generic> for more information about
+the available types of reference accessors, and the various methods
+they define.
+
+
+=head2 Object Accessors
+
+There's also a specialized accessor for object references:
+
+ package MyStruct;
+ use Class::MakeMethods::Template::Hash (
+ 'new' => 'new',
+ 'object' => [ 'widget' => {class=>'MyWidgetClass', delegate=>"twiddle"} ],
+ );
+
+(Note that the C<class> and C<delegate> values specified above are
+method parameters, which provide additional information about the
+C<widget> declaration; see L<"Standard Declaration Syntax"> for more information.)
+
+The above declaration creates methods equivalent to the following:
+
+ package MyStruct;
+
+ sub widget {
+ my $self = shift;
+ if ( scalar @_ ) {
+ if (ref $_[0] and UNIVERSAL::isa($_[0], 'MyWidgetClass')) {
+ $self->{widget} = shift;
+ } else {
+ $self->{widget} = MyWidgetClass->new(@_);
+ }
+ } else {
+ return $self->{widget};
+ }
+ }
+
+ sub clear_widget {
+ my $self = shift;
+ $self->{widget} = undef;
+ }
+
+ sub twiddle {
+ my $self = shift;
+ my $obj = $self->widget()
+ or Carp::croak("Can't forward twiddle because widget is empty");
+ $obj->twiddle(@_)
+ }
+
+
+=head2 Mixing Object and Global Methods
+
+Here's a package declaration using two of the included subclasses, C<Standard::Hash>, for creating and accessing hash-based objects, and C<Basic::Global>, for simple global-value accessors:
+
+ package MyQueueItem;
+
+ use Class::MakeMethods::Standard::Hash (
+ new => { name => 'new', defaults=>{ foo => 'Foozle' } },
+ scalar => [ 'foo', 'bar' ],
+ hash => 'history'
+ );
+
+ use Class::MakeMethods::Basic::Global (
+ scalar => 'Debug',
+ array => 'InQueue',
+ );
+
+ sub AddQueueItem {
+ my $class = shift;
+ my $instance = shift;
+ $instance->history('AddQueueItem' => time());
+ $class->InQueue([0, 0], $instance);
+ }
+
+ sub GetQueueItem {
+ my $class = shift;
+ $class->InQueue([0, 1], []) or $class->new
+ }
+
+=head2 Adding Custom Initialization to Constructors
+
+Frequently you'll want to provide some custom code to initialize new objects of your class. Most of the C<*:new> constructor methods provides a way to ensure that this code is consistently called every time a new instance is created.
+
+=over 4
+
+=item Composite::Hash:new { post_rules => [] }
+
+The Composite classes allow you to add pre- and post-operations to any method, so you can pass in a code-ref to be executed after the new() method.
+
+ package MyClass;
+
+ sub new_post_init {
+ my $self = ${(pop)->{result}}; # get result of original new()
+ length($self->foo) or $self->foo('FooBar'); # default value
+ warn "Initialized new object '$self'";
+ }
+
+ use Class::MakeMethods (
+ 'Composite::Hash:new' => [
+ 'new' => { post_rules=>[ \&new_post_init ] }
+ ],
+ 'Composite::Hash:scalar' => 'foo;,
+ );
+ ...
+ package main;
+ my $self = MyClass->new( foo => 'Foozle' )
+
+=item Template::Hash:new --and_then_init
+
+Use 'Template::Hash:new --and_then_init', which will first create the object and initialize it with the provided values, and then call an init() method on the new object before returning it.
+
+ package MyClass;
+ use Class::MakeMethods::Template::Hash (
+ 'new --and_then_init' => 'new'
+ 'string' => 'foo'
+ );
+ sub init {
+ my $self = shift;
+ length($self->foo) or $self->foo('FooBar'); # default value
+ warn "Initialized new object '$self'";
+ }
+ ...
+ package main;
+ my $self = MyClass->new( foo => 'Foozle' )
+
+=item Template::Hash:new --with_init
+
+If you don't want your constructor to use the default hash-of-method-names style of initialization, use 'Template::Hash:new --with_init', which will create an empty object, pass its arguments to the init() method on the new object, and then return it.
+
+ package MyClass;
+ use Class::MakeMethods::Template::Hash (
+ 'new --with_init' => 'new'
+ 'string' => 'foo'
+ );
+ sub init {
+ my $self = shift;
+ $self->foo( shift || 'FooBar' ); # init with arg or default
+ warn "Initialized new object '$self'";
+ }
+ ...
+ package main;
+ my $self = MyClass->new( 'Foozle' )
+
+=back
+
+Some additional notes about these constructors:
+
+=over 4
+
+=item *
+
+The C<Template::*:new> methods allow you to specify a name for your method other than C<init> by passing the C<init_method> parameter:
+
+ use Class::MakeMethods::Template::Hash (
+ 'new --and_then_init' => [
+ 'new' => { init_method => 'my_init' }
+ ],
+ );
+
+=item *
+
+If you know that you're not going to have a complex class hierarchy, you can reduce resource consumption a bit by changing the above declarations from "*::Hash" to "*::Array" so your objects end up as blessed arrays rather than blessed hashes.
+
+=back
+
+
+=head2 Changing Method Names
+
+The Template subclasses allow you to control the names assigned to
+the methods you generate by selecting from several naming interfaces.
+
+For example, the accessors declared above use a default, Perl-ish
+style interface, in which a single method can be called without an
+argument to retrieve the value, or with an argument to set it.
+However, you can also select a more Java-like syntax, with separate
+get* and set* methods, by including the '--java' template specification:
+
+ package MyStruct;
+ use Class::MakeMethods::Template::Hash (
+ 'new' => 'new',
+ 'scalar' => '--java Foo',
+ );
+
+(Note that the declaration of Foo could also have been written as
+C<'scalar --java' =E<gt> 'Foo'> or C<'scalar' =E<gt> ['--java',
+'Foo']>, or C<'scalar' =E<gt> [ 'foo' => { 'interface'=>'java' }
+], all of which are interpreted identically; see the
+L<Class::MakeMethods> section on "Argument Normalization" for
+details.)
+
+Usage of this accessor would then be as follows:
+
+ package main;
+ use MyStruct;
+
+ my $obj = MyStruct->new( setFoo => "Foozle" );
+ print $obj->getFoo();
+ $obj->setFoo("Bozzle");
+
+
+=head2 Selecting Specific Helper Methods
+
+You can use the ability to specify interfaces to select specific helper methods rather than getting the default collection.
+
+For example, let's say you wanted to use a Template::Hash:array, but you only wanted two methods to be installed in your class, a foo() accessor and a shift_foo() mutator. Any of the below combinations of syntax should do the trick:
+
+ use Class::MakeMethods::Template::Hash
+ 'array' => [
+ 'foo' => { interface=>{'foo'=>'get_set', 'shift_foo'=>'shift'} },
+ ];
+
+If you're going to have a lot of methods with the same interface, you could pre-declare a named interface once and use it repeatedly:
+
+ BEGIN {
+ require Class::MakeMethods::Template::Hash;
+ Class::MakeMethods::Template::Hash->named_method('array')->
+ {'interface'}->{'my_get_set_shift'} =
+ { '*'=>'get_set', 'shift_*'=>'shift' };
+ }
+
+ use Class::MakeMethods::Template::Hash
+ 'array --my_get_set_shift' => [ 'foo', 'bar' ];
+
+
+=head2 Tree Structure Example
+
+In this example we will create a pair of classes with references
+to other objects.
+
+The first class is a single-value data object implemented as a
+reference to a scalar.
+
+ package MyTreeData;
+ use Class::MakeMethods::Template::Scalar (
+ 'new' => 'new',
+ 'string' => 'value',
+ );
+
+The second class defines a node in a tree, with a constructor, an
+accessor for a data object from the class above, and accessors for
+a list of child nodes.
+
+ package MyTreeNode;
+ use Class::MakeMethods::Template::Hash (
+ 'new' => 'new',
+ 'object -class MyTreeData' => 'data',
+ 'array_of_objects -class MyTreeNode' => 'children',
+ );
+
+ sub depth_first_data {
+ my $self = shift;
+ return $self->data, map { $_->depth_first_data() } $self->children;
+ }
+
+Here's a sample of how the above classes could be used in a program.
+
+ package main;
+ use MyTreeData;
+ use MyTreeNode;
+
+ my $node = MyTreeNode->new(
+ data => { value=>'data1' },
+ children => [ { value=>'data3' } ]
+ );
+ $node->push_children( MyTreeNode->new( data => { value=>'data2' } ) );
+
+ foreach my $data ( $node->depth_first_data ) {
+ print $data->value();
+ }
+
+
+=head1 SEE ALSO
+
+See L<Class::MakeMethods> for general information about this distribution.
+
+=head2 Annotated Tutorials
+
+Ron Savage has posted a pair of annotated examples, linked to below.
+Each demonstrates building a class with MakeMethods, and each
+includes scads of comments that walk you through the logic and
+demonstrate how the various methods work together.
+
+ http://savage.net.au/Perl-tutorials.html
+ http://savage.net.au/Perl-tutorials/tut-33.tgz
+ http://savage.net.au/Perl-tutorials/tut-34.tgz
+
+=cut
diff --git a/lib/Class/MakeMethods/Docs/ReadMe.pod b/lib/Class/MakeMethods/Docs/ReadMe.pod
new file mode 100644
index 0000000..6fd7890
--- /dev/null
+++ b/lib/Class/MakeMethods/Docs/ReadMe.pod
@@ -0,0 +1,279 @@
+=head1 NAME
+
+Class::MakeMethods::Docs::ReadMe - About Class::MakeMethods
+
+
+=head1 DESCRIPTION
+
+This is an updated release of Class::MakeMethods, for distribution through
+CPAN.
+
+This distribution includes the Class::MakeMethods::Template and
+Class::MakeMethods::Emulator modules which were packaged sepearately in some
+previous releases.
+
+
+=head1 MOTIVATION
+
+By passing arguments to "use Class::MakeMethods ..." statements, you can
+select from a library of hundreds of common types of methods, which are
+dynamically installed as subroutines in your module, simplifying the code
+for your class.
+
+
+=head1 DISTRIBUTION AND INSTALLATION
+
+=head2 Version
+
+This is Class::MakeMethods v1.010, intended for general use.
+
+This module's CPAN registration should read:
+
+ Name DSLIP Description
+ -------------- ----- ---------------------------------------------
+ Class::
+ ::MakeMethods RdpOp Generate common types of methods
+
+=head2 Prerequisites
+
+In general, this module should work with Perl 5.003 or later,
+without requring any modules beyond the core Perl distribution.
+
+The following optional feature may not be available on some platforms:
+
+=over 4
+
+=item *
+
+Class::MakeMethods::Attribute: The C<:MakeMethod> subroutine
+attribute requires Perl version 5.6 and the Attribute::Handlers
+module (from CPAN).
+
+=item *
+
+Class::MakeMethods::Template C<--lvalue>: The lvalue modifier
+provided by the Template generator subclasses will only work on
+Perl version 5.6 or later.
+
+=item *
+
+Some third-party tests used to check the compliance of Emulator modules
+require Test::More and will be automatically skipped on machines which do
+not have this installed.
+
+=back
+
+=head2 Installation
+
+You should be able to install this module using the CPAN shell interface:
+
+ perl -MCPAN -e 'install Class::MakeMethods'
+
+Alternately, you may retrieve this package from CPAN or from the author's site:
+
+=over 2
+
+=item *
+
+http://search.cpan.org/~evo/
+
+=item *
+
+http://www.cpan.org/modules/by-authors/id/E/EV/EVO
+
+=item *
+
+http://www.evoscript.org/Class-MakeMethods/dist/
+
+=back
+
+After downloading the distribution, follow the normal procedure to unpack and install it, using the commands shown below or their local equivalents on your system:
+
+ tar xzf Class-MakeMethods-*.tar.gz
+ cd Class-MakeMethods-*
+ perl Makefile.PL
+ make test && sudo make install
+
+Thanks to the kind generosity of other members of the Perl community,
+this distribution is also available repackaged in the FreeBSD
+"ports" and Linux RPM formats. This may simplify installation for
+some users, but be aware that these alternate distributions may
+lag a few versions behind the latest release on CPAN.
+
+=over 2
+
+=item *
+
+http://www.freebsd.org/cgi/ports.cgi?query=Class-MakeMethods
+
+=item *
+
+http://www.rpmfind.net/linux/rpm2html/search.php?query=perl-Class-MakeMethods
+
+=back
+
+=head2 Tested Platforms
+
+This release has been tested succesfully on the following platforms:
+
+ 5.6.1 on darwin
+
+Earlier releases have also tested OK on the following platforms:
+
+ IP30-R12000-irix
+ OpenBSD.i386-openbsd
+ i386-freebsd / i386-freebsd-thread-multi
+ i386-linux
+ i386-netbsd / i386-netbsd-thread-multi
+ i586-linux / i586-linux-thread-multi-ld
+ i686-linux / i686-pld-linux-thread-multi
+ ia64-linux
+ ppc-linux
+ sparc-linux
+ sparc-netbsd
+ sun4-solaris
+
+Some earlier versions failed to "make test" on MSWin32, although
+a forced installation would still work; that problem should be
+fixed in the most recent releases.
+
+You may also review the current test results from CPAN-Testers:
+
+=over 2
+
+=item *
+
+http://testers.cpan.org/show/Class-MakeMethods.html
+
+=back
+
+=head1 SUPPORT
+
+=head2 Release Status
+
+This module has been used in a variety of production systems and
+has been available on CPAN for over two years, with several other
+distributions dependant on it, so it would be fair to say that it
+is fully released.
+
+However, while the commonly-used portions are well tested, some of
+the more obscure combinations of options are less so, and new bug
+reports do trickle in occasionally. If you do encounter any problems,
+please inform the author and I'll endeavor to patch them promptly.
+
+Additional features have been outlined for future development, but
+the intent is support these by adding more options to the declaration
+interface, while maintaining backward compatibility.
+
+See L<Class::MakeMethods::Docs::ToDo> for other outstanding issues
+and development plans.
+
+=head2 Support
+
+If you have questions or feedback about this module, please feel
+free to contact the author at the below address. Although there is
+no formal support program, I do attempt to answer email promptly.
+
+I would be particularly interested in any suggestions towards
+improving the documentation and correcting any Perl-version or platform
+dependencies, as well as general feedback and suggested additions.
+
+Bug reports that contain a failing test case are greatly appreciated,
+and suggested patches will be promptly considered for inclusion in
+future releases.
+
+To report bugs via the CPAN web tracking system, go to
+C<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Class-MakeMethods> or send mail
+to C<Dist=Class-MakeMethods#rt.cpan.org>, replacing C<#> with C<@>.
+
+=head2 Community
+
+If you've found this module useful or have feedback about your
+experience with it, consider sharing your opinion with other Perl
+users by posting your comment to CPAN's ratings system:
+
+=over 2
+
+=item *
+
+http://cpanratings.perl.org/rate/?distribution=Class-MakeMethods
+
+=back
+
+For more general discussion, you may wish to post a message on PerlMonks or the comp.lang.perl.misc newsgroup:
+
+=over 2
+
+=item *
+
+http://www.perlmonks.org/index.pl?node=Seekers%20of%20Perl%20Wisdom
+
+=item *
+
+http://groups.google.com/groups?group=comp.lang.perl.misc
+
+=back
+
+
+=head1 CREDITS AND COPYRIGHT
+
+=head2 Author
+
+Developed by Matthew Simon Cavalletto at Evolution Softworks.
+More free Perl software is available at C<www.evoscript.org>.
+
+You may contact the author directly at C<evo@cpan.org> or C<simonm@cavalletto.org>.
+
+=head2 Feedback and Suggestions
+
+Thanks to the following people for bug reports, suggestions, and other feedback:
+
+ Martyn J. Pearce
+ Scott R. Godin
+ Ron Savage
+ Jay Lawrence
+ Adam Spiers
+ Malcolm Cook
+ Terrence Brannon
+ Jared Rhine
+ Peter Chen
+ Mike Castle
+
+=head2 Source Material
+
+This package was inspired by the ground-breaking original closure-generating method maker module:
+
+ Class::MethodMaker, by Peter Seibel.
+
+Additional inspiration, cool tricks, and blocks of useful code for
+this module were extracted from the following CPAN modules:
+
+ Class::Accessor, by Michael G Schwern
+ Class::Contract, by Damian Conway
+ Class::SelfMethods, by Toby Everett
+
+=head2 Copyright
+
+Copyright 2002, 2003 Matthew Simon Cavalletto.
+
+Portions copyright 1998, 1999, 2000, 2001 Evolution Online Systems, Inc.
+
+Based on Class::MethodMaker, originally developed by Peter Seibel. Portions Copyright 1996 Organic Online. Portions Copyright 2000 Martyn J. Pearce.
+
+Class::MakeMethods::Emulator::accessors is based on accessors. Portions by Steve Purkis.
+
+Class::MakeMethods::Emulator::AccessorFast is based on Class::Accessor::Fast. Portions Copyright 2000 Michael G Schwern.
+
+Class::MakeMethods::Emulator::Inheritable is based on Class::Data::Inheritable. Portions Copyright 2000 Damian Conway and Michael G Schwern.
+
+Class::MakeMethods::Emulator::mcoder is based on mcoder. Portions Copyright 2003 by Salvador Fandiņo.
+
+Class::MakeMethods::Emulator::Singleton is based on Class::Singleton, by Andy Wardley. Portions Copyright 1998 Canon Research Centre Europe Ltd.
+
+Class::MakeMethods::Utility::Ref is based on Ref.pm. Portions Copyright 1994 David Muir Sharnoff.
+
+=head2 License
+
+You may use, modify, and distribute this software under the same terms as Perl.
+
+=cut
diff --git a/lib/Class/MakeMethods/Docs/RelatedModules.pod b/lib/Class/MakeMethods/Docs/RelatedModules.pod
new file mode 100644
index 0000000..93ef930
--- /dev/null
+++ b/lib/Class/MakeMethods/Docs/RelatedModules.pod
@@ -0,0 +1,962 @@
+=head1 NAME
+
+Class::MakeMethods::Docs::RelatedModules - Survey of Class Builders
+
+
+=head1 SYNOPSIS
+
+ http://search.cpan.org/search?mode=module&query=Class
+
+
+=head1 DESCRIPTION
+
+There are a variety of modules on CPAN dedicated to the purpose of
+generating common constructor and accessor methods. Below, I survey
+several of these, summarizing some basic features and technical
+approaches, and comparing them to Class::MakeMethods and other
+modules.
+
+
+=head2 Caution
+
+B<Please note that these comments are for basic comparison purposes
+only and may be incorrect or out of date.> Please consult the
+documentation from a current version of each module for more specific
+details. Corrections and clarifications would by welcomed by the author at the email address below.
+
+
+=head2 Points of Comparison
+
+In general, I compared the following characteristics:
+
+=over 4
+
+=item Distribution
+
+Is it included with Perl, or on CPAN? Is it being actively maintained?
+
+=item Usage
+
+How do you go about declaring your class's methods?
+
+=item Mechanism
+
+How are they generated and delivered?
+
+=item Instance type
+
+Are the objects of your class blessed hashes, or something else?
+
+=item Core Methods
+
+Does the module provide a constructor and basic accessors? Are there specialized methods for hash-ref, array-ref, and object-ref accessors?
+
+=item Extensible
+
+Can you subclass the package to create new types of methods, or is there some other way to extend it?
+
+=item Other Methods
+
+Other types of methods provided.
+
+=item Emulator
+
+Does Class::MakeMethods provide a drop-in replacement for this module?
+
+=item Comments
+
+Other characteristics or features of note.
+
+=back
+
+
+=head1 RELATED MODULES
+
+=head2 accessors
+
+=over 4
+
+=item Distribution
+
+CPAN. Uploaded Sep 2003.
+
+=item Comments
+
+I have not yet reviewed this module in detail.
+
+=item Example
+
+ package MyObject;
+ use accessors qw( foo bar baz );
+
+=back
+
+=head2 Attribute::Property
+
+=over 4
+
+=item Distribution
+
+CPAN.
+
+=item Comments
+
+I have not yet reviewed this module in detail.
+
+=back
+
+
+=head2 Class::Accessor
+
+=over 4
+
+=item Distribution
+
+CPAN. Last update 4/01.
+
+=item Usage
+
+Inherit and call function with declaration arguments
+
+=item Mechanism
+
+Generates and installs closures
+
+=item Instance Type
+
+Hash.
+
+=item Subclasses Cleanly
+
+Cleanly.
+
+=item Standard Methods
+
+Scalar accessors.
+
+=item Extensible
+
+Yes.
+
+=item Comments
+
+Accessor methods call overwritable C<self-E<lt>get(I<key>)> and
+C<self-E<lt>set(I<key>, I<value>)> methods.
+
+Also includes Class::Accessor::Fast, which creates direct hash keys accessors without calling get and set methods.
+
+=item Emulator
+
+Yes, but only for the Fast variation; see Class::MakeMethods::Emulator::AccessorFast.
+
+=item Example
+
+ package MyObject;
+ @ISA = qw(Class::Accessor);
+ MyObject->mk_accessors(qw( simple ordered mapping obj_ref ));
+
+=back
+
+
+=head2 Class::Class
+
+=over 4
+
+=item Distribution
+
+CPAN. Last update 1/00.
+
+=item Usage
+
+Inherit and fill %MEMBERS hash; methods created when first object is created
+
+=item Mechanism
+
+Generates and installs closures
+
+=item Instance Type
+
+Hash.
+
+=item Subclasses Cleanly
+
+Yes.
+
+=item Standard Methods
+
+Constructor and various accessors.
+
+=item Extensible
+
+No.
+
+=item Example
+
+Usage is similar to Class::Struct:
+
+ package MyObject;
+ use Class::Class;
+ @ISA = qw(Class::Class);
+ %MEMBERS = (
+ simple => '$',
+ ordered => '@',
+ mapping => '%',
+ obj_ref => 'FooObject'
+ );
+
+=item Other Method Types
+
+Provides a polymorph() method that is similar to Class::Method's "ClassName:class_name -require".
+
+=back
+
+
+=head2 Class::Constructor
+
+=over 4
+
+=item Distribution
+
+CPAN. Last update 11/01.
+
+=item Usage
+
+Inherit and call function with declaration arguments
+
+=item Mechanism
+
+Generates and installs closures
+
+=item Instance Type
+
+Hash.
+
+=item Subclasses Cleanly
+
+Cleanly.
+
+=item Standard Methods
+
+Hash constructor, with bells.
+
+=item Extensible
+
+No.
+
+=item Emulator
+
+No, but possible.
+
+=item Example
+
+ package MyObject;
+ @ISA = qw(Class::Constructor);
+ MyObject->mk_constructor( Name => 'new' );
+
+=back
+
+
+=head2 Class::Classgen
+
+=over 4
+
+=item Distribution
+
+CPAN. Last update 12/00.
+
+=item Usage
+
+Pre-processor run against declaration files.
+
+=item Mechanism
+
+Assembles and saves code file
+
+=item Instance Type
+
+Hash.
+
+=item Subclasses Cleanly
+
+Yes. (I think.)
+
+=item Standard Methods
+
+Constructor and various accessors.
+
+=item Extensible
+
+No. (I think.)
+
+=item Example
+
+ header:
+ package MyObject;
+ variables:
+ $simple
+ @ordered
+ %mapping
+ $obj_ref
+
+=back
+
+
+=head2 Class::Contract
+
+=over 4
+
+=item Distribution
+
+CPAN. Last update 5/01.
+
+=item Usage
+
+Call function with declaration arguments
+
+=item Mechanism
+
+Generates and installs closures
+
+=item Instance Type
+
+Scalar reference with external data storage.
+
+=item Subclasses Cleanly
+
+Yes.
+
+=item Standard Methods
+
+Constructor and various accessors.
+
+=item Extensible
+
+Yes. (I think.)
+
+=item Comments
+
+Supports pre- and post-conditions, class invariants, and other
+software engineering goodies.
+
+=item Example
+
+ package MyObject;
+ use Class::Contract;
+ contract {
+ ctor 'new';
+ attr 'simple' => SCALAR;
+ attr 'ordered' => ARRAY;
+ attr 'mapping' => HASH;
+ attr 'obj_ref' => 'FooObject';
+ }
+
+=back
+
+
+=head2 Class::Data::Inheritable
+
+=over 4
+
+=item Distribution
+
+CPAN. Last update 4/00.
+
+=item Usage
+
+Inherit and call function with declaration arguments
+
+=item Mechanism
+
+Generates and installs closures
+
+=item Instance Type
+
+Class data, with inheritance.
+
+=item Subclasses Cleanly
+
+Yes, specifically.
+
+=item Standard Methods
+
+Scalar accessors.
+
+=item Extensible
+
+No.
+
+=item Example
+
+Usage is similar to Class::Accessor:
+
+ package MyObject;
+ @ISA = qw(Class::Data::Inheritable);
+ MyObject->mk_classdata(qw( simple ordered mapping obj_ref ));
+
+=item Emulator
+
+Yes, Class::MakeMethods::Emulator::Inheritable, passes original test suite.
+
+=back
+
+
+=head2 Class::Delegate
+
+=over 4
+
+=item Distribution
+
+CPAN. Uploaded 12/0.
+
+=item Comments
+
+I have not yet reviewed this module in detail.
+
+=back
+
+=head2 Class::Delegation
+
+=over 4
+
+=item Distribution
+
+CPAN. Uploaded 12/01.
+
+=item Comments
+
+I have not yet reviewed this module in detail.
+
+=back
+
+=head2 Class::Generate
+
+=over 4
+
+=item Distribution
+
+CPAN. Last update 11/00.
+
+=item Usage
+
+Call function with declaration arguments
+
+=item Mechanism
+
+Assembles and evals code string, or saves code file.
+
+=item Instance Type
+
+Hash.
+
+=item Subclasses Cleanly
+
+Yes.
+
+=item Standard Methods
+
+Constructor and accessors (scalar, array, hash, object, object array, etc).
+
+=item Extensible
+
+Unknown.
+
+=item Comments
+
+Handles private/protected limitations, pre and post conditions,
+assertions, and more.
+
+=item Example
+
+Usage is similar to Class::Struct:
+
+ package MyObject;
+ use Class::Generate;
+ class MyObject => [
+ simple => '$',
+ ordered => '@',
+ mapping => '%',
+ obj_ref => 'FooObject'
+ ];
+
+=back
+
+=head2 Class::Hook
+
+=item Distribution
+
+CPAN. Uploaded 12/01.
+
+=item Comments
+
+I have not yet reviewed this module in detail.
+
+
+=head2 Class::Holon
+
+=over 4
+
+=item Distribution
+
+CPAN. Experimental/Alpha release 07/2001.
+
+=item Instance Type
+
+Hash, array, or flyweight-index.
+
+=item Subclasses Cleanly
+
+No. (I think.)
+
+=item Standard Methods
+
+Constructor and scalar accessors; flywieght objects also get scalar mutator methods.
+
+=item Extensible
+
+No. (I think.)
+
+=item Comments
+
+I'm not sure I understand the intent of this module; perhaps future versions will make this clearer....
+
+=back
+
+
+=head2 Class::MethodMaker
+
+=over 4
+
+=item Distribution
+
+CPAN. Last update 1/01.
+
+=item Usage
+
+Import, or call function, with declaration arguments
+
+=item Mechanism
+
+Generates and installs closures
+
+=item Instance Type
+
+Hash, Static.
+
+=item Subclasses Cleanly
+
+Yes.
+
+=item Standard Methods
+
+Constructor and various accessors.
+
+=item Extensible
+
+Yes.
+
+=item Example
+
+Usage is similar to Class::MakeMethods:
+
+ package MyObject;
+ use Class::MethodMaker (
+ new => 'new',
+ get_set => 'simple',
+ list => 'ordered',
+ hash => 'mapping',
+ object => [ 'FooObject' => 'obj_ref' ],
+ );
+
+=item Emulator
+
+Yes, Class::MakeMethods::Emulator::MethodMaker, passes original test suite.
+
+=back
+
+
+=head2 Class::MakeMethods
+
+=over 4
+
+=item Distribution
+
+CPAN.
+
+=item Usage
+
+Import, or call function, with declaration arguments; or if desired, make methods on-demand with Autoload, or declare subroutines with a special Attribute.
+
+=item Mechanism
+
+Generates and installs closures
+
+=item Instance Type
+
+Hash, Array, Scalar, Static, Class data, others.
+
+=item Subclasses Cleanly
+
+Yes.
+
+=item Standard Methods
+
+Constructor and various accessors.
+
+=item Extensible
+
+Yes.
+
+=item Example
+
+Usage is similar to Class::MethodMaker:
+
+ package MyObject;
+ use Class::MakeMethods::Hash (
+ new => 'new',
+ scalar => 'simple',
+ array => 'ordered',
+ hash => 'mapping',
+ object => [ 'obj_ref', { class=>'FooObject' } ],
+ );
+
+=back
+
+
+=head2 Class::Maker
+
+=over 4
+
+=item Distribution
+
+CPAN. Last update 7/02.
+
+=item Usage
+
+Call function with declaration arguments.
+
+=item Mechanism
+
+Generates and installs closures (I think).
+
+=item Instance Type
+
+Hash (I think).
+
+=item Subclasses Cleanly
+
+Unknown.
+
+=item Standard Methods
+
+Constructor and various scalar and reference accessors.
+
+=item Extensible
+
+Unknown.
+
+=item Comments
+
+I haven't yet reviewed this module closely.
+
+=back
+
+
+=head2 Class::SelfMethods
+
+=over 4
+
+=item Distribution
+
+CPAN. Last update 2/00.
+
+=item Usage
+
+Inherit; methods created via AUTOLOAD
+
+=item Mechanism
+
+Generates and installs closures (I think)
+
+=item Instance Type
+
+Hash.
+
+=item Subclasses Cleanly
+
+Yes.
+
+=item Standard Methods
+
+Constructor and scalar/code accessors (see Comments).
+
+=item Extensible
+
+No.
+
+=item Comments
+
+Individual objects may be assigned a subroutine that will be called as a method on subsequent accesses. If an instance does not have a value for a given accessor, looks for a method defined with a leading underscore.
+
+=back
+
+
+=head2 Class::Struct
+
+=over 4
+
+=item Distribution
+
+Included in the standard Perl distribution. Replaces Class::Template.
+
+=item Usage
+
+Call function with declaration arguments
+
+=item Mechanism
+
+Assembles and evals code string
+
+=item Instance Type
+
+Hash or Array
+
+=item Subclasses Cleanly
+
+No.
+
+=item Standard Methods
+
+Constructor and various accessors.
+
+=item Extensible
+
+No.
+
+ package MyObject;
+ use Class::Struct;
+ struct(
+ simple => '$',
+ ordered => '@',
+ mapping => '%',
+ obj_ref => 'FooObject'
+ );
+
+=item Emulator
+
+Yes, Class::MakeMethods::Emulator::Struct.
+
+=back
+
+
+=head2 Class::StructTemplate
+
+=over 4
+
+=item Distribution
+
+CPAN. Last update 12/00.
+
+No documentation available.
+
+=item Usage
+
+Unknown.
+
+=item Mechanism
+
+Unknown.
+
+=back
+
+
+=head2 Class::Template
+
+=over 4
+
+=item Distribution
+
+CPAN. Out of date.
+
+=item Usage
+
+Call function with declaration arguments (I think)
+
+=item Mechanism
+
+Assembles and evals code string (I think)
+
+=item Instance Type
+
+Hash.
+
+=item Subclasses Cleanly
+
+Yes. (I think.)
+
+=item Standard Methods
+
+Constructor and various accessors.
+
+=item Extensible
+
+No. (I think.)
+
+=item Example
+
+Usage is similar to Class::Struct:
+
+ package MyObject;
+ use Class::Template;
+ members MyObject {
+ simple => '$',
+ ordered => '@',
+ mapping => '%',
+ obj_ref => 'FooObject'
+ };
+
+=back
+
+
+=head2 Class::Virtual
+
+Generates methods that fail with a message indicating that they were not implemented by the subclass. (Cf. 'Template::Universal:croak -abstract'.)
+
+Also provides a list of abstract methods that have not been implemented by a subclass.
+
+=over 4
+
+=item Distribution
+
+CPAN. Last update 3/01.
+
+=item Extensible
+
+Unknown.
+
+=item Mechanism
+
+Uses Class::Data::Inheritable and installs additional closures.
+
+=back
+
+
+=head2 CodeGen::PerlBean
+
+=over 4
+
+=item Distribution
+
+CPAN.
+
+=item Usage
+
+Call function with declaration arguments.
+
+=item Mechanism
+
+Generates and writes source code to a file.
+
+=item Instance Type
+
+Hash (I think).
+
+=item Subclasses Cleanly
+
+Unknown.
+
+=item Standard Methods
+
+Constructor and various scalar and reference accessors.
+
+=item Extensible
+
+Unknown.
+
+=item Comments
+
+I haven't yet reviewed this module closely.
+
+=back
+
+
+=head2 HTML::Mason::MethodMaker
+
+=over 4
+
+=item Distribution
+
+CPAN.
+
+=item Usage
+
+Package import with declaration arguments
+
+=item Mechanism
+
+Generates and installs closures
+
+=item Instance Type
+
+Hash.
+
+=item Standard Methods
+
+Scalar accessors.
+
+=item Extensible
+
+No.
+
+=item Example
+
+ use HTML::Mason::MethodMaker (
+ read_write => [ qw( simple ordered mapping obj_ref ) ]
+ );
+
+=back
+
+
+=head1 TO DO
+
+The following modules are relevant but have not yet been cataloged above.
+
+=head2 Attribute::Property
+
+=head2 Class::Accessor::Chained
+
+=head2 Class::Accessor::Lvalue
+
+=head2 Class::Accessor::Ref
+
+=head2 Class::AutoClass
+
+=head2 Class::Builder
+
+=head2 Class::Member
+
+=head2 Class::Trigger
+
+
+=head1 SEE ALSO
+
+See L<Class::MakeMethods> for general information about this distribution.
+
+
+=head1 CREDITS AND COPYRIGHT
+
+=head2 Developed By
+
+ M. Simon Cavalletto, simonm@cavalletto.org
+ Evolution Softworks, www.evoscript.org
+
+=head2 Copyright
+
+Copyright 2002 Matthew Simon Cavalletto.
+
+Portions copyright 2000, 2001 Evolution Online Systems, Inc.
+
+=head2 License
+
+You may use, modify, and distribute this document under the same terms as Perl.
+
+=cut
diff --git a/lib/Class/MakeMethods/Docs/ToDo.pod b/lib/Class/MakeMethods/Docs/ToDo.pod
new file mode 100644
index 0000000..312bdc0
--- /dev/null
+++ b/lib/Class/MakeMethods/Docs/ToDo.pod
@@ -0,0 +1,296 @@
+=head1 NAME
+
+Class::MakeMethods::Docs::ToDo - Ideas, problems, and suggestions
+
+
+=head1 SYNOPSIS
+
+There are lots of things that could be done to improve this module.
+
+
+=head1 DISTRIBUTION ISSUES
+
+Issues about the distribution and supporting files, rather than the code:
+
+=head2 Documentation
+
+=over 4
+
+=item *
+
+Make sure that the documentation is broken up into appropriately-sized
+chunks, and that people will know which section to look at.
+
+=item *
+
+As user questions arrive, add the answers as documentation points or examples.
+
+=item *
+
+Assemble annotated examples and tutorials, and either link to or distribute them.
+
+=item *
+
+Finish overhauling Template documentation.
+
+=item *
+
+Include Global and InsideOut uses in the EXAMPLES section
+
+=item *
+
+Template Internals: Finish documenting disk-based meta-method code-caching.
+
+=back
+
+=head2 Tests
+
+=over 4
+
+=item *
+
+Use Devel::Coverage to measure test coverage, and fill in missing
+cases.
+
+=item *
+
+Finish tests for Standard and Composite modules.
+
+=back
+
+
+=head1 GENERAL ISSUES
+
+=over 4
+
+=item *
+
+It does not appear to be possible to assign subroutine names to
+closures within Perl. As a result, debugging output from Carp and
+similar sources will show all generated methods as "ANON()" rather
+than "YourClass::methodname()".
+
+UPDATE: There now seem to be fixes for this which should be integrated: See the new Sub::Name module and http://perlmonks.org/index.pl?node_id=304883
+
+=item *
+
+For scalar methods (and others) it would be nice to have a simple
+bounds-checking interface to approve or reject (with an exception)
+new values that were passed in.
+
+As pointed out by Terrence Brannon, the right interface to
+adopt is probably that of Attribute::Types:
+
+ use Class::MakeMethods::Standard::Hash (
+ 'scalar' => [ 'count' => { TYPE => 'INTEGER' } ],
+ 'scalar' => [ 'name' => { TYPE => qr/^[A-Z]\w*$/ } ],
+ 'scalar' => [ 'account' => { TYPE => &checksum_account_number } ]
+ );
+
+=item *
+
+Improve use of _diagnostic hooks for debugging. Add various "(Q)"
+debug diagnostics.
+
+=item *
+
+Finish building Inheritable array and object accessors.
+
+=item *
+
+Finish building Composite::* packages.
+
+=item *
+
+Resolve DESTROY-time issues with Standard::Inheritable, Composite::Inheritable, and Template::InsideOut.
+
+=item *
+
+Add slice and splice functionality to Standard::*:hash and Composite::*:hash.
+
+=back
+
+
+=head1 TEMPLATE CLASSES
+
+=head2 Template::Generic
+
+=over 4
+
+=item *
+
+Allow untyped object accesors if C<class> attribute is not set.
+(Suggested in Jan-01 NY Perl Seminar discussion.)
+
+=item *
+
+Standardize naming templates for array, hash, other method types.
+
+Deprecate verb_x methods? Or at last make them consistently available both ways.
+
+Make list methods consistent with hash_of_lists methods, in action, and
+in name (x_verb). Also for others (e.g., set_ clear_ boolean)
+
+=item *
+
+Should default object template provide auto-create behavior on ->get()?
+
+=item *
+
+Generalize the "Generic:scalar -init_and_get" interface to support
+memoizing values for other accessor types.
+
+=item *
+
+Consider adding hash each and array iterator methods, using a closure
+to provide iteration.
+
+=item *
+
+Add support for tied arrays & scalars, a la tiedhash
+
+=item *
+
+Add string_multiple_index.
+
+=item *
+
+Extend index methods to support weak indexes with WeakRef. Perhaps
+just have it accept a hash ref to use as the index, and then allow
+people to pass in tied hashes?
+
+=item *
+
+Maybe make private or protected method croak if they were called by a
+method_init method which was called by an outside package.
+
+Not entirely clear what the right semantics or security precautions are here...
+
+=back
+
+
+=head2 Template::Generic Subclasses
+
+=over 4
+
+=item *
+
+Finish building code_or_scalar meta-method.
+
+=item *
+
+Finish building Class::MakeMethods::ClassInherit subclass.
+
+Need to work out how to capture changes for non-scalar values. For
+example, if a subclass inherits an array accessor and then pops
+it, is there some way to provide them with copy-on-write?
+
+=item *
+
+Add enumerated string/number type.
+
+Provide helper methods with map of associated values (ex $o->port
+= 80 ... $o->port_readable eq 'HTTP' ). Cf. code for earlier
+unpublished 'lookup' method type.
+
+=item *
+
+For StructBuiltin:
+
+Add -fatal flag to die if core func returns false / undef
+Add call method to recall method with alternative arguments.
+Add -nocall flag to not call core func on new.
+
+=item *
+
+Replace ClassName:static_hash_classname with Class:indexed_string.
+
+=back
+
+
+=head2 Template Internals
+
+=over 4
+
+=item *
+
+Figure out which modules, if any, should actually be using AutoLoader.
+Probably just Template::Generic?
+
+=item *
+
+Give users a way to do meta-method code-caching in Perl library
+hierarchy, rather than in /tmp/auto or other user-specified
+directory..
+
+Provide mechanism for pre-generating these at install time.
+
+Perhaps load these via do, rather than open/read/eval?
+
+Perhaps pre-generate expanded libs with all of the -imports resolved?
+
+=item *
+
+Support generating code files and loading them as needed.
+
+This would be similar to Class::Classgen, except that we'd do the
+generation at run-time the first time it was required, rather than
+in a separate pass.
+
+For example, given the following declaration:
+
+ package Foo::Bar;
+ Class::MakeMethods::Template::Hash->import(-codecache=>'auto', scalar=>'foo');
+
+We should be able to write out the following file:
+
+ cat 'auto/Foo/Bar/methods-line-2.pl'
+ # NOTE: Generated for Foo::Bar by the Class::MakeMethods module.
+ # Changes made here will be lost when Foo::Bar is modified.
+ package Foo::Bar;
+ sub foo {
+ my $self = shift;
+ if ( scalar @_ ) {
+ $self->{'foo'} = shift();
+ }
+ $self->{'foo'}
+ }
+
+Then on subsequent uses, we can just re-load the generated code:
+
+ require "auto/Foo/Bar/methods-line-2.pl";
+
+To do this, we need to:
+
+=over 4
+
+=item *
+
+Provide an option to select this if desired; maybe ...
+import('-cache' => 'auto/', ...)?
+
+=item *
+
+Figure out which directory we can/should write into.
+
+=item *
+
+Re-evaluate the textual code templates, without generating the
+closures. Substitute in any _STATIC_ATTR_ values. Make other _ATTR_
+values point to some public lookup table or package scalar.
+
+=item *
+
+Notice if the source file (or Class::MakeMethods modules) has
+been updated more recently than the generated file.
+
+=back
+
+=back
+
+
+=head1 SEE ALSO
+
+See L<Class::MakeMethods> for general information about this distribution.
+
+=cut
generated by cgit v1.2.3 (git 2.25.1) at 2026-03-04 19:51:35 +0000