Class::MakeMethods::Composite::Inheritable - Overridable data


NAME

Class::MakeMethods::Composite::Inheritable - Overridable data


SYNOPSIS

  package MyClass;
  use Class::MakeMethods( 'Composite::Inheritable:scalar' => 'foo' );
  # We now have an accessor method for an "inheritable" scalar value

  MyClass->foo( 'Foozle' );   # Set a class-wide value
  print MyClass->foo();       # Retrieve class-wide value

  my $obj = MyClass->new(...);
  print $obj->foo();          # All instances "inherit" that value...

  $obj->foo( 'Foible' );      # until you set a value for an instance.
  print $obj->foo();          # This now finds object-specific value.
  ...

  package MySubClass;
  @ISA = 'MyClass';

  print MySubClass->foo();    # Intially same as superclass,
  MySubClass->foo('Foobar');  # but overridable per subclass,
  print $subclass_obj->foo(); # and shared by its instances
  $subclass_obj->foo('Fosil');# until you override them... 
  ...

  # Similar behaviour for hashes and arrays is currently incomplete
  package MyClass;
  use Class::MakeMethods::Composite::Inheritable (
    array => 'my_list',
    hash => 'my_index',
  );

  MyClass->my_list(0 => 'Foozle', 1 => 'Bang!');
  print MyClass->my_list(1);

  MyClass->my_index('broccoli' => 'Blah!', 'foo' => 'Fiddle');
  print MyClass->my_index('foo');


DESCRIPTION

The MakeMethods subclass provides accessor methods that search an inheritance tree to find a value. This allows you to set a shared or default value for a given class, optionally override it in a subclass, and then optionally override it on a per-instance basis.

Note that all MakeMethods methods are inheritable, in the sense that they work as expected for subclasses. These methods are different in that the data accessed by each method can be inherited or overridden in each subclass or instance. See Class::MakeMethods::Utility::Inheritable for more about this type of ``inheritable'' or overridable`` data.

Class::MakeMethods Calling Interface

When you use this package, the method declarations you provide as arguments cause subroutines to be generated and installed in your module.

See Calling Conventions in the Class::MakeMethods::Standard manpage for more information.

Class::MakeMethods::Standard Declaration Syntax

To declare methods, pass in pairs of a method-type name followed by one or more method names.

See the ``METHOD GENERATOR TYPES'' section below for a list of the supported values of generator_type.

See Declaration Syntax in the Class::MakeMethods::Standard manpage and Parameter Syntax in the Class::MakeMethods::Standard manpage for more information.


METHOD GENERATOR TYPES

scalar - Overrideable Accessor

For each method name passed, uses a closure to generate a subroutine with the following characteristics:

Sample declaration and usage:

  package MyClass;
  use Class::MakeMethods::Composite::Inheritable (
    scalar => 'foo',
  );
  ...

  # Store value
  MyClass->foo('Foozle');

  # Retrieve value
  print MyClass->foo;

array - Overrideable Ref Accessor

For each method name passed, uses a closure to generate a subroutine with the following characteristics:

Sample declaration and usage:


  package MyClass;
  use Class::MakeMethods::Composite::Inheritable (
    array => 'bar',
  );
  ...

  # Clear and set contents of list
  print MyClass->bar([ 'Spume', 'Frost' ] );

  # Set values by position
  MyClass->bar(0 => 'Foozle', 1 => 'Bang!');

  # Positions may be overwritten, and in any order
  MyClass->bar(2 => 'And Mash', 1 => 'Blah!');

  # Retrieve value by position
  print MyClass->bar(1);

  # Direct access to referenced array
  print scalar @{ MyClass->bar() };

There are also calling conventions for slice and splice operations:

  # Retrieve slice of values by position
  print join(', ', MyClass->bar( undef, [0, 2] ) );

  # Insert an item at position in the array
  MyClass->bar([3], 'Potatoes' );

  # Remove 1 item from position 3 in the array
  MyClass->bar([3, 1], undef );

  # Set a new value at position 2, and return the old value 
  print MyClass->bar([2, 1], 'Froth' );

NOTE: THIS METHOD GENERATOR HAS NOT BEEN WRITTEN YET.

hash - Overrideable Ref Accessor

For each method name passed, uses a closure to generate a subroutine with the following characteristics:

Sample declaration and usage:

  package MyClass;
  use Class::MakeMethods::Composite::Inheritable (
    hash => 'baz',
  );
  ...

  # Set values by key
  MyClass->baz('foo' => 'Foozle', 'bar' => 'Bang!');

  # Values may be overwritten, and in any order
  MyClass->baz('broccoli' => 'Blah!', 'foo' => 'Fiddle');

  # Retrieve value by key
  print MyClass->baz('foo');

  # Retrive slice of values by position
  print join(', ', MyClass->baz( ['foo', 'bar'] ) );

  # Direct access to referenced hash
  print keys %{ MyClass->baz() };

  # Reset the hash contents to empty
  @{ MyClass->baz() } = ();

NOTE: THIS METHOD GENERATOR IS INCOMPLETE.

hook - Overrideable array of subroutines

A hook method is called from the outside as a normal method. However, internally, it contains an array of subroutine references, each of which are called in turn to produce the method's results.

Subroutines may be added to the hook's array by calling it with a blessed subroutine reference, as shown below. Subroutines may be added on a class-wide basis or on an individual object.

You might want to use this type of method to provide an easy way for callbacks to be registered.

  package MyClass;
  use Class::MakeMethods::Composite::Inheritable ( 'hook' => 'init' );

  MyClass->init( Class::MakeMethods::Composite::Inheritable->Hook( sub { 
      my $callee = shift;
      warn "Init...";
  } );

  my $obj = MyClass->new;
  $obj->init();

object - Overrideable Ref Accessor

For each method name passed, uses a closure to generate a subroutine with the following characteristics:

Sample declaration and usage:

  package MyClass;
  use Class::MakeMethods::Composite::Inheritable (
    object => 'foo',
  );
  ...

  # Store value
  MyClass->foo( Foozle->new() );

  # Retrieve value
  print MyClass->foo;

NOTE: THIS METHOD GENERATOR HAS NOT BEEN WRITTEN YET.


SEE ALSO

See the Class::MakeMethods manpage for general information about this distribution.

See the Class::MakeMethods::Composite manpage for more about this family of subclasses.

 Class::MakeMethods::Composite::Inheritable - Overridable data