NAME
    Object::LocalVars - Outside-in objects with local aliasing of $self and
    object variables

SYNOPSIS
      package My::Object;
      use strict;
      use Object::LocalVars;
     
  give_methods our $self;  # this exact line is required
     
  our $field1 : Prop;
      our $field2 : Prop;
     
  sub as_string : Method { 
        return "$self has properties '$field1' and '$field2'";
      }

DESCRIPTION
    Do not use for production purposes!

    *This is a experimental module I developed when exploring inside-out
    objects. It is no longer supported, but is left on CPAN as an example of
    the kind of strange OO approaches that are possible with Perl.*

    This module helps developers create "outside-in" objects. Properties
    (and $self) are declared as package globals. Method calls are wrapped
    such that these globals take on a local value that is correct for the
    specific calling object and the duration of the method call. I.e. $self
    is locally aliased to the calling object and properties are locally
    aliased to the values of the properties for that object. The package
    globals themselves only declare properties in the package and hold no
    data themselves. Data are stored in a separate namespace for each
    property, keyed off the reference memory addresses of the objects.

    Outside-in objects are similar to "inside-out" objects, which store data
    in a single lexical hash (or closure) for each property, which is keyed
    off the reference memory addresses of the objects. Both differ from
    classic Perl objects, which hold data for the object directly using a
    blessed reference or closure to a data structure, typically a hash. For
    both outside-in and inside-out objects, data are stored centrally and
    the blessed reference is simply a key to look up the right data in the
    central data store.

    The use of package variables for outside-in objects allows for the use
    of dynamic symbol table manipulation and aliasing. As a result,
    Object::LocalVars delivers a variety of features -- though with some
    corresponding drawbacks.

  Features
    *   Provides $self automatically to methods without '"my $self = shift"'
        and the like

    *   Provides dynamic aliasing of properties within methods -- methods
        can access properties directly as variables without the overhead of
        calls to accessors or mutators, eliminating the overhead of these
        calls in methods

    *   Array and hash properties may be accessed via direct dereference of
        simple variables, allowing developers to push, pop, splice, etc.
        without the usual tortured syntax to dereference an accessor call

    *   Properties no longer require accessors to have compile time syntax
        checking under strictures (i.e. '"use strict"'); 'public' properties
        have accessors automatically provided as needed

    *   Uses attributes to mark properties and methods, but only in the
        BEGIN phase so should be mod_perl friendly (though this has not been
        tested yet)

    *   Provides attributes for public, protected and private properties,
        class properties, and methods

    *   Orthogonality -- can subclass just about any other class, regardless
        of implementation.

    *   Multiple inheritance supported in initializers and destructors
        (though only one superclass can be of a special, orthogonal type)

    *   Minimally thread-safe -- objects are safely cloned across thread
        boundaries (or a pseudo-fork on Win32)

    *   Achieves these features without source filtering

  Drawbacks
    *   Method inefficiency -- wrappers around methods create extra overhead
        on method calls

    *   Accessor inefficiency -- privacy checks and extra indirection
        through package symbol tables create extra overhead (compared to
        direct hash dereferencing of classic Perl objects)

    *   Minimal encapsulation -- data are hidden but still publically
        accessible, unlike approaches that use lexicals or closures to
        create strong encapsulation; (will be addressed in a future release)

    *   Does not support threads::shared -- objects existing before a new
        thread is created will persist into the new thread, but changes in
        an object cannot be reflected in the corresponding object in the
        other thread

  Design principles
    *Simplicity*

    Object::LocalVars was written to simplify writing classes in Perl by
    removing the need for redundant and awkward code. E.g.:

     sub foo {
         my $self = shift;                 # e.g. repetitive
         push @{$self->some_list}, "foo";  # e.g. awkward
     }

    Instead, Object::LocalVars uses a more elegant, readable and minimalist
    approach:

     our $some_list : Prop;
     
 sub foo : Method {
         push @$some_list, "foo";
     }

    As with Perl, "easy things should be easy; difficult things should be
    possible" and there should be a smooth learning curve from one to the
    other.

    *Accessors and mutators*

    A major objective of Object::LocalVars is a significant reduction in the
    need for accessors (and mutators). In general, accessors break the OO
    encapsulation paradigm by revealing or allowing changes to internal
    object state. However, accessors are common in Perl for two big reasons:

    *   Accessors offer typo protection. Compare:

         $self->{created}; # correct
         $self->{craeted}; # typo
         $self->craeted(); # typo, but caught at compile time

    *   Automatically generating accessors is easy

    As a result, the proliferation of accessors opens up the class internals
    unless additional protections are added to the accessors to make them
    private.

    With Object::LocalVars's aliasing, properties stay private by default
    and don't *need* an accessor for typo safety. If protected or public
    accessors are needed for subclasses or external code to check state,
    these can be requested as needed.

  Terminology
    Object-oriented programming suffers from a plethora of terms used to
    describe certain features and characteristics of classes and objects.
    Perl further complicates this by using these or related terms for other
    features entirely (e.g. attributes). (And Perl 6 swaps around these
    definitions again.) Within this documentation, terms are used as
    follows:

    *   *class* -- represents a model of associated states and behaviors in
        terms of *properties* and *methods*; in Perl, a *class* is
        represented by a "package"

    *   *object* -- represents a specific instance of a *class*; in Perl, an
        *object* is represented by a reference to a data structure blessed
        into a particular "package"

    *   *property* -- represents a particular state of a *class* or
        *object*; *properties* which are common to all *objects* of a
        *class* are referred to as *class properties*; *properties* which
        can be unique to each *object* of a *class* are referred to as
        *object properties*; in Object::LocalVars, *properties* are
        represented by package variables marked with an appropriate
        *attribute*

    *   *method* -- represents a behavior exhibited by a *class*; *methods*
        which do not depend on *object properties* are referred to as *class
        methods*; *methods* which depends on *object properties* are
        referred to as *object methods*; in Object::LocalVars, *methods* are
        represented by subroutines marked with an appropriate *attribute*

    *   *accessors* -- used generically to refer to both 'accessors' and
        'mutators', *methods* which respectively read and change
        *properties*.

    *   *attribute* -- code that modifies variable and subroutine
        declarations; in Perl, *attributes* are separated from variable or
        subroutine declarations with a colon (e.g. '"our $name : Prop"');
        see perldoc for attributes for more details

USAGE
  Getting Started
    The most minimal usage of Object::LocalVars consists of importing it
    with "use" and calling the "give_methods" routine:

     use Object::Localvars;
     give_methods our $self;  # Required

    This automatically imports attribute handlers to mark properties and
    methods and imports several necessary, supporting subroutines that
    provide basic class functionality such as object construction and
    destruction. To support environments such as "mod_perl", which have no
    "CHECK" or "INIT" phases, all attributes take effect during the "BEGIN"
    phase when the module is compiled and executed. The "give_methods"
    subroutine provides the run-time setup aspect of this and must always
    appear as shown.

  Declaring Object Properties
    Properties are declared by specifying a package variable using the
    keyword "our" and an appropriate attribute. There are several attributes
    (and aliases for attributes) available which result in different degrees
    of privacy and different resulting rules for creating accessors.

    While properties are declared as an "our" variable, they are stored
    elsewhere in a private package namespace. When methods are called, a
    wrapper function temporarily *aliases* these package variables using
    "local" to their proper class or object property values. This allows for
    seamless access to properties, as if they were normal variables. For
    example, dereferencing a list property:

     our $favorites_list : Prop;  
     
 sub add_favorite : Method {
       my $new_item = shift;
       push @$favorites_list, $new_item;
     }

    Object::LocalVars provides the following attributes for object
    properties:

    *   :Prop or :Priv

          our $prop1 : Prop;
          our $prop2 : Priv;

        Either of these attributes declare a private property. Private
        properties are aliased within methods, but no accessors are created.
        This is the recommended default unless specific alternate
        functionality is needed. Of course, developers are free to write
        methods that act as accessors, and provide additional behavior such
        as argument validation.

    *   :Prot

          our $prop3 : Prot;

        This attribute declares a protected property. Protected properties
        are aliased within methods, and an accessor and mutator are created.
        However, the accessor and mutator may only be called by the
        declaring package or a subclass of it.

    *   :Pub

          our $prop4 : Pub;

        This attribute declares a public property. Public properties are
        aliased within methods, and an accessor and mutator are created that
        may be called from anywhere.

    *   :ReadOnly

          our $prop5 : ReadOnly;

        This attribute declares a readonly property. Readonly properties are
        aliased within methods, and an accessor and mutator are created. The
        accessor is public, but the mutator is protected.

  Declaring Class Properties
    Class properties work like object properties, but the value of a class
    property is the same in all object or class methods.

    Object::LocalVars provides the following attributes for class
    properties:

    *   :Class or :ClassPriv

          our $class1 : Class;
          our $class2 : ClassPriv;

        Either of these attributes declare a private class property. Private
        class properties are aliased within methods, but no accessors are
        created. This is the recommended default unless specific alternate
        functionality is needed.

    *   :ClassProt

          our $class3 : ClassProt;

        This attribute declares a protected class property. Protected class
        properties are aliased within methods, and an accessor and mutator
        are created. However, the accessor and mutator may only be called by
        the declaring package or a subclass of it.

    *   :ClassPub

          our $class4 : ClassPub;

        This attribute declares a public class property. Public class
        properties are aliased within methods, and an accessor and mutator
        are created that may be called from anywhere.

    *   :ClassReadOnly

          our $class5 : ClassReadOnly;

        This attribute declares a readonly class property. Readonly class
        properties are aliased within methods, and an accessor and mutator
        are created. The accessor is public, but the mutator is protected.

  Declaring Methods
      sub foo : Method {
        my ($arg1, $arg2) = @_;  # no need to shift $self
        # $self and all properties automatically aliased
      }

    As with properties, methods are indicated by the addition of an
    attribute to a subroutine declaration. When these marked subroutines are
    called, a wrapper function ensures that $self and all properties are
    aliased appropriately and passes only the remaining arguments to the
    marked subroutine. Class properties are always aliased to the current
    values of the class properties. If the method is called on an object,
    all object properties are aliased to the state of that object. These
    aliases are true aliases, not copies. Changes to the alias change the
    underlying properties.

    Object::LocalVars provides the following attributes for subroutines:

    *   :Method or :Pub

         sub fcn1 : Method { }
         sub fcn2 : Pub { }

        Either of these attributes declare a public method. Public methods
        may be called from anywhere. This is the recommended default unless
        specific alternate functionality is needed.

    *   :Prot

         sub fcn3 : Prot { }

        This attribute declares a protected method. Protected methods may be
        called only from the declaring package or a subclass of it.

    *   :Priv

         sub fcn4 : Priv { }

        This attribute declares a private method. Private methods may only
        be called only from the declaring package. See "Hints and Tips" for
        good style for calling private methods.

  Accessors and Mutators
     # property declarations
     
 our $name : Pub;   # :Pub creates an accessor and mutator
     our $age  : Pub;
     
 # elsewhere in code
     
 $obj->set_name( 'Fred' )->set_age( 23 );
     print $obj->name;

    Properties that are public or protected automatically have appropriate
    accessors and mutators generated. By default, these use an Eiffel-style
    syntax, e.g.: "$obj->x()" and "$obj->set_x()". Mutatators return the
    calling object, allowing method chaining.

    The prefixes for accessors and mutators may be altered using the
    "accessor_style()" class method.

  Constructors and Destructors
    Object::LocalVars automatically provides the standard constructor,
    "new", an initializer, "BUILDALL", and the standard destructor,
    "DESTROY". Each calls a series of functions to manage initialization and
    destruction within the inheritance model.

    When "new" is called, a new blessed object is created. By default, this
    object is an anonymous scalar. (See "CONFIGURATION OPTIONS" for how to
    use another type of object as a base instead.)

    After the object is created, "BUILDALL" is used to recursively
    initialize superclasses using their "BUILDALL" methods. A user-defined
    "PREBUILD" routine can modify the arguments passed to superclasses. The
    object is then initialized using a user-defined "BUILD". (This approach
    resembles the Perl6 object initialization model.)

    A detailed program flow follows:

    *   Within "new": The name of the calling class is shifted off the
        argument list

    *   Within "new": A reference to an anonymous scalar is blessed into the
        calling class

    *   Within "new": "BUILDALL" is called as an object method on the
        blessed reference with a copy of the arguments to "new"

    *   Within "BUILDALL": subroutine returns if initialization for the
        current class has already been done for this object

    *   Within "BUILDALL": for each superclass listed in @ISA, if the
        superclass can call "BUILDALL", then "PREBUILD" (if it exists) is
        called with the name of the superclass and a copy of the remaining
        argument list to "new". The superclass "BUILDALL" is then called as
        an object method using the new blessed reference and the results of
        the "PREBUILD". If "PREBUILD" does not exist, then any "BUILDALL" is
        called with a copy of the arguments to "new".

    *   Within "BUILDALL": if a "BUILD" method exists, it is called as a
        method using a copy of the arguments to "new"

    During object destruction, the process works in reverse. In "DESTROY",
    user-defined cleanup for the object's class is handled with "DEMOLISH"
    (if it exists). Then, memory for object properties is freed. Finally,
    "DESTROY" is called for each superclass in @ISA which can do "DESTROY".

    Both "BUILDALL" and "DESTROY" handle "diamond" inheritance patterns
    appropriately. Initialization and destruction will only be done once for
    each superclass for any given object.

  Hints and Tips
    *Calling private methods*

    Good style for private method calling in traditional Perl
    object-oriented programming is to call private methods directly,
    "foo($self,@args)", rather than with method lookup, "$self->foo(@args)".
    This avoids unintentionally calling a subclass method of the same name
    if a subclass happens to provide one.

    *Avoiding hidden internal data*

    For a package using Object::LocalVars, e.g. "My::Package", object
    properties are stored in "My::Package::DATA", class properties are
    stored in "My::Package::CLASSDATA", methods are stored in
    "My::Package::METHODS", and objects are tracked for cloning in
    "My::Package::TRACKER". Do not access these areas directly or overwrite
    them with other global data or unexpected results are guaranteed to
    occur.

    (In a future release of this module, this storage approach should be
    replaced by fully-encapsulated anonymous symbol tables.)

METHODS TO BE WRITTEN BY A DEVELOPER
  "PREBUILD()"
     sub PREBUILD {
         my ($superclass, @args) = @_;
         # filter @args in some way
         return @args;
     }

    This subroutine may be written to filter arguments given to "BUILDALL"
    before passing them to a superclass "BUILDALL". *This must not be tagged
    with a ":Method" attribute* or equivalent as it is called before the
    object is fully initialized. The primary purpose of this subroutine is
    to strip out any arguments that would cause the superclass initializer
    to die and/or to add any default arguments that should always be passed
    to the superclass.

  "BUILD()"
     # Assuming our $counter : Class;
     sub BUILD : Method {
         my %init = ( %defaults, @_ );
         $prop1 = $init{prop1};
         $counter++;
     }

    This method may be written to initialize the object after it is created.
    If available, it is called at the end of "BUILDALL". The @_ array
    contains the original array passed to "BUILDALL".

  "DEMOLISH()"
      # Assume our $counter : Class;
     sub DEMOLISH : Method {
         $counter--;
     }

    This method may be defined to provide some cleanup actions when the
    object goes out of scope and is destroyed. If available, it is called at
    the start of the destructor (i.e "DESTROY").

METHODS AUTOMATICALLY EXPORTED
    These methods will be automatically exported for use. This export can be
    prevented by passing the method name preceded by a "!" in a list after
    the call to "use Object::LocalVars". E.g.:

      use Object::LocalVars qw( !new );

    This is generally not needed and is strongly discouraged, but is
    available should developers need some very customized behavior in "new"
    or "DESTROY" that can't be achieved with "BUILD" and "DEMOLISH".

  "give_methods()"
      give_methods our $self;

    Installs wrappers around all subroutines tagged as methods. This
    function (and the declaration of "our $self") *must* be used in all
    classes built with Object::LocalVars. It should only be called once for
    any class.

  "new()"
     my $obj = Some::Class->new( @arguments );

    The constructor. Classes built with Object::LocalVars have this
    available by default and do not need their own constructor.

  "caller()"
     my $caller = caller(0);

    This subroutine is exported automatically and emulates the built-in
    "caller" with the exception that if the caller is Object::LocalVars
    (i.e. from a wrapper function), it will continue to look upward in the
    calling stack until the first non-Object::LocalVars package is found.

  "BUILDALL()"
    The initializer. It is initially called by "new" and then recursively
    calls "BUILDALL" for all superclasses. Arguments for superclass
    initialization are filtered through "PREBUILD". It should not be called
    by users.

  "CLONE()"
    When threads are used, this subroutine is called by perl when a new
    thread is created to ensure objects are properly cloned to the new
    thread. Users shouldn't call this function directly and it must not be
    overridden.

  "DESTROY()"
    A destructor. This is not used within Object::LocalVars directly but is
    exported automatically when Object::LocalVars is imported. "DESTROY"
    calls "DEMOLISH" (if it exists), frees object property memory, and then
    calls "DESTROY" for every superclass in @ISA. It should not be called by
    users.

CONFIGURATION OPTIONS
  "accessor_style()"
     package My::Class;
     use Object::LocalVars;
     BEGIN {
         Object::LocalVars->accessor_style( {
             get => 'get_',
             set => 'set_'
         });
     }

    This class method changes the prefixes for accessors and mutators. When
    called from within a "BEGIN" block before properties are declared, it
    will change the style of all properties subsequently declared. It takes
    as an argument a hash reference with either or both of the keys 'get'
    and 'set' with the values indicating the accessor/mutator prefix to be
    used.

    If the prefix is the same for both, an combined accessor/mutator will be
    created that sets the value of the property if an argument is passed and
    always returns the value of the property. E.g.:

     package My::Class;
     use Object::LocalVars;
     BEGIN {
         Object::LocalVars->accessor_style( {
             get => q{},
             set => q{}
         });
     }
     
 our $age : Pub;
     
 # elsewhere
     $obj->age( $obj->age() + 1 );  # increment age by 1

    Combined accessor/mutators are treated as mutators for the
    interpretation of privacy settings.

  "base_object()"
     package My::Class; 
     use Object::LocalVars; 
     Object::LocalVars->base_object( 'Another::Class' ); 
     give_methods our $self;

    This class method changes the basic blessed object type for the calling
    package from being an anonymous scalar to a fully-fledged object of the
    given type. This allows classes build with Object::LocalVars to subclass
    any type of class, regardless of its underlying implementation (e.g. a
    hash) -- though only a single class can be subclassed in such a manner.
    "PREBUILD" (if it exists) is called on the arguments to "new" before
    generating the base object using its constructor. The object is then
    re-blessed into the proper class. Other initializers are run as normal
    based on @ISA, but the base class is not intialized again.

    If the given base class does not already exist in @ISA, it is imported
    with "require" and pushed onto the @ISA stack, similar to the pragma
    base.

BENCHMARKING
    Forthcoming. In short, Object::LocalVars can be faster than traditional
    approaches if the ratio of property access within methods is high
    relative to number of method calls. It is slower than traditional
    approaches if there are many method calls that individually do little
    property access. In general, Object::LocalVars trades off coding
    elegance and clarity for speed of execution.

SEE ALSO
    These other modules provide similiar functionality and/or inspired this
    one. Quotes are from their respective documentations.

    *   Attribute::Property -- "easy lvalue accessors with validation"; uses
        attributes to mark object properties for accessors; validates lvalue
        usage with a hidden tie

    *   Class::Std -- "provides tools that help to implement the 'inside out
        object' class structure"; based on the book *Perl Best Practices*;
        nice support for multiple-inheritance and operator overloading

    *   Lexical::Attributes -- "uses a source filter to hide the details of
        the Inside-Out technique from the user"; API based on Perl6 syntax;
        provides $self automatically to methods

    *   Spiffy -- "combines the best parts of Exporter.pm, base.pm, mixin.pm
        and SUPER.pm into one magic foundation class"; "borrows ideas from
        other OO languages like Python, Ruby, Java and Perl 6"; optionally
        uses source filtering to provide $self automatically to methods

INSTALLATION
    The following commands will build, test, and install this module:

     perl Build.PL
     perl Build
     perl Build test
     perl Build install

BUGS
    Please report bugs using the CPAN Request Tracker at
    <http://rt.cpan.org/NoAuth/Bugs.html?Dist=/home/david/projects/Object-Lo
    calVars>

AUTHOR
    David A Golden (DAGOLDEN)

    dagolden@cpan.org

    http://dagolden.com/

COPYRIGHT
    Copyright (c) 2005 by David A Golden

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    The full text of the license can be found in the LICENSE file included
    with this module.

