NAME

Legacy - Describes Class::IntrospectionMethods legacy API

SYNOPSIS

 None

DESCRIPTION

This man page describes the legacy API of Class::IntrospectionMethods that's provided for backward compatibility with Class::MethodMaker v1.08.

CLASS INTROSPECTION

slot query: the catalog option

The catalog feature keeps a catalog in the object of all the slots that are defined with MethodMaker. This feature enables the user to query a class created by MethodMaker to retrieved all available slots.

The -catalog option must be used with a catalog name (i.e. -catalog => foo. You can use several catalog names.

When used, the -catalog option will add 4 methods to the CMMed class:

• A CMM_CATALOG_LIST method to retrieve a list of all catalogs. Also available as a class method.

• A CMM_CATALOG method to retrieve a list of the slot of a catalog. Also available as a class method.

• A CMM_SLOT_CATALOG method that takes a slot name and returns the name of its catalog . Also available as a class method.

• A CMM_SLOT_DETAIL method to retrieve the details of a given slot. Also available as a class method.

  The details are returned in an array that contains:

  • The slot type: i.e. either slot_type => scalar, slot_type => array or slot_type => hash.

  • If the index is tied (for array or hash slot type), the array will contain: tie_index => $tie_class. If some constructor arguments are used, the array will also contain tie_index_args => \@args.

  • If the target value (i.e. the scalar) is tied (for all slot types), the array will contain: tie_scalar => $tie_class. If some constructor arguments are used, the array will also contain tie_scalar_args => \@args.

  • If the target value (i.e. the scalar) is a plain object (for all slot types), the array will contain: class => $class. If some constructor arguments are used, the array will also contain class_args => \@args.

When the -catalog => cat_name option is used, the slot names defined after the option are stored in a catalog using the specified catalog name. For instance, the following code will store slot fooa and foob in the my_foo_cat catalog, bar1 and bar2 in the my_bar_cat catalog, and hidden_slot will not be cataloged:

 package MyClass ; 
 use Class::MethodMaker 
  -catalog => 'my_foo_cat', 
  get_set => [qw/fooa foob/],
  -catalog => undef,
  get_set => 'hidden_slot',
  -catalog => 'my_bar_cat',
  get_set => [qw/bar1 bar2/] ;
  object_tie_hash => 
  [
   {
    slot => 'a',
    tie_hash => ['myHash', dummy => 'booh'],
    class => ['myObj', 'a' => 'foo']
   },
  ]

To retrieve the list of catalogs defined for each object:

 my @catalog = $obj->CMM_CATALOG_LIST ; # gives 'my_foo_cat','my_bar_cat'

To retrieve the catalog of a MyClass object $obj:

 my @foo_slots = $obj ->CMM_CATALOG('my_foo_cat');
 my $foo_slots = $obj ->CMM_CATALOG('my_foo_cat'); # array ref

 my @bar_slots = $obj ->CMM_CATALOG('my_bar_cat');
 my $bar_slots = $obj ->CMM_CATALOG('my_bar_cat'); # array ref

 my @all_slots = $obj->CMM_CATALOG('my_foo_cat','my_bar_cat') ;
 my @all_slots = $obj->CMM_CATALOG() ; # as above

These methods also work as Class methods:

 &MyClass::CMM_CATALOG_LIST ; # gives 'my_foo_cat','my_bar_cat'
 &MyClass::CMM_CATALOG('my_foo_cat'); # gives qw/fooa foob/

 &MyClass::CMM_SLOT_DETAIL('a'); 

returns

  [ 
    'scalar' ,
    tie_index      => 'myHash', 
    tie_index_args => [ dummy => 'booh' ],
    class          => 'myObj',
    class_args     => [ 'a' => 'foo']
  ]

By the way, the CMM_* names are ugly, but they should not clash with user design ;-) .

Note: does not work yet for all slots types.

From slot to object: the parent option.

If you use tied scalars (with the tied_scalar or tie_tie_hash method types), or object method type, your tied scalars or objects may need to call the parent CMMed object.

For instance, if you want to implement error handling in your tied scalar or objects that will call the parent CMMed object or display error messages giving back to the user the slot name containing the faulty object.

SO if you need to query the slot name, or index value (for tie_tie_hash method types), or be able to call the parent object, you can use the -parent option when creating the parent CMMed class:

 package FOO ;
 use Class::MethodMaker
   '-parent' ,
   object => [ 'Y' => [qw/g h j/ ]];

Using this option will graft the following attributes (with their accessor method) in each object created using the slots that follow the -parent option until the next -noparent option.

CMM_PARENT

Reference of the parent object.

CMM_SLOT_NAME

slot name to use to get the child object from the parent.

CMM_INDEX_VALUE

index value (for tie_tie_hash method type) to use to get the child object from the parent.

When using the -parent option, a CMM_PARENT, CMM_SLOT_NAME and CMM_INDEX_VALUE methods are also grafted to the child's class.

Here is an example to retrieve a parent object :

 package FOO ;
 use ExtUtils::testlib;
  '-parent' ,
  object_tie_hash =>
  [
   {
    slot => 'bar',
    tie_hash => ['MyHash'],
    class => ['MyObj', 'a' => 'foo']
   }
  ],
  new => 'new';

In the MyObj implementation you can do :

 $daddy  = $self -> CMM_PARENT ; 
 $d_slot = $self -> {CMM_SLOT_NAME} ; # 'bar'
 $d_idx  = $self -> {CMM_INDEX_VALUE} ;

The object hidden behind the tied hash can also use the parent functions. In the MyHash implementation, you can do:

 $parent = $self-> CMM_PARENT ; 
 $slot =   $self -> {CMM_SLOT_NAME} ; # 'bar'

But, obviously, you cannot query CMM_INDEX_VALUE in the tied hash class.

LEGACY METHOD TYPES

object

This method is supported by Class::IntrospectionMethods with a different API. Nevertheless, the old API still works. Here's the old API doc.

object creates methods for accessing a slot that contains an object of a given class as well as methods to automatically pass method calls onto the object stored in that slot.

    object => [
               'Foo' => 'phooey',
               'Bar' => [ qw / bar1 bar2 bar3 / ],
               'Baz' => {
                         slot => 'foo',
                         comp_mthds => [ qw / bar baz / ],
                         constructor_args => [ set => 'it' ]
                        },
               'Fob' => [
                         {
                          slot => [qw/dog fox/],
                          comp_mthds => 'bark',
                         },
                         {
                          slot => 'cat',
                          comp_mthds => 'miaow',
                         },
                        ];
              ];

The main argument should be a reference to an array. The array should contain pairs of class => sub-argument pairs. The sub-arguments parsed thus:

Hash Reference

See Baz above. The hash should contain the following keys:

slot

The name of the instance attribute (slot). This can be an array ref if you want to specify several slots the same way (but then you cannot use comp_mthds).

constructor_args

A array ref containing arguments that are passed to the new constructor.

Array Reference

As for String, for each member of the array. Also works if each member is a hash reference (see Fob above).

String

The name of the instance attribute (slot).

tie_scalar

Supported without much change. Generated methods tied_xx and xx_tied are deprecated in favor of tied_storage_xx

hash

Supported and vastly extended. But older API will still work.

# ----------------------------------------------------------------------------

tie_hash

Deprecated. Use hash instead.

Much like hash, but uses a tied hash instead.

Takes a list of pairs, where the first is the name of the component, the second is a hash reference. The hash reference recognizes the following keys:

tie

Required. The name of the class to tie to. Make sure you have used the required class.

args

Required. Additional arguments for the tie, as an array ref.

The first argument can also be an arrayref, specifying multiple components to create.

Example:

   tie_hash     => [
                    hits        => {
                                    tie => qw/ Tie::RefHash /,
                                    args => [],
                                   },
                   ],

object_tie_hash

Deprecated. Use hash instead.

Functions like tie_hash, but maintains an array of referenced objects in each slot.

 object_tie_hash =>
  [
    {
      slot => xxx, # or [ ... , ... ]
      tie_hash => [ 'HashName', args ,...] ,
      class => ['ObjName', @constructor_args ]
    },
    ...
  ]

If you omit the 'tie_hash' parameter, a standard hash will be used to store the objects.

When xxx is called with more than one argument, xxx is treated as the key. If the second argument is a:

• An object of the class 'ObjName' then the object is the new value of the key 'xxx'.

• Anything else: A new object is created using the default constructor arguments.

Example, if the default constructor arguments of 'ObjName' are @c_args :

 xxx( 
     # xxx{foo} = $obj->isa('ObjName') ? $obj : croak
     foo => $obj,

     # xxx{foo2} = ObjName->new(@c_args, arg => 'bar') 
     foo2 => [ arg => 'bar'],

     # xxx{foo3} = ObjName->new(@constructor_arg)
     # xxx{foo4} = ObjName->new(@constructor_arg)
     qw/foo3 foo4/
    )

object_tie_hash provides a tied_foo method that return the tied object. This tied object is auto-vivified. I.e. tied_foo always return an object.

If the stored object features a cim_init method (either directly or through inheritance), this method will be called right after creation and installation of parent methods.

tie_tie_hash

Deprecated. Use hash instead.

Functions like tie_hash, but maintains an array of tied scalar in each slot.

 tie_tie_hash =>
  [
    {
      slot => xxx, # or [ ... , ... ]
      tie_hash   => [ 'HashName', args ,...] ,
      tie_scalar => ['ObjName', @constructor_args ]
    },
    ...
  ]

If you omit the 'tie_hash' parameter, a standard hash will be used to store the values.

If you omit the 'tie_scalar' parameter, a standard scalar will be used.

If the class used with the tie_hash parameter must either:

• Inherit Tie::StdHash

• Store the actual hash in $self->{data} or $self->{DATA} (like the example given in the camel book).

• Provide a get_data_ref method. This method accepts a key parameter and returns a ref to the value pointed by key. Something like:

   sub get_data_ref 
     {
       my ($self, $key) = @_ ;
       return \$self->{my_internal_hash}{$key} ;
     }

The tie_tie_hash provides the folowing methods:

tied_hash_x

Returns the object hidden behind the tied hash.

tied_scalar_x

Returns the object hidden behind the tied scalar.

list

Deprecated. Use array instead.

Creates several methods for dealing with slots containing list data. Takes a string or a reference to an array of strings as its argument.

tie_list

Deprecated. Use array instead.

Much like list, but can use a tied list instead.

Takes a list of pairs, where the first is the name of the component, the second is an array reference. The array reference takes the usual tie parameters.

For instance if Array_A and ArrayB are tied arrays, you can have:

  tie_list =>
  [
   foo => [ 'Array_A',   foo => 'x', bar => 'B' ],
   baz => [ 'ArrayB',    baz => 0]
  ],

object_list

Deprecated. Use array instead.

Functions like list, but maintains an array of referenced objects in each slot. Forwarded methods return a list of the results returned by mapping the method over each object in the array.

Arguments are like object.

When required, the xxx_index methods will auto-vivify the object held in the slot. Hence it can never return undef.

If the stored object features a cim_init method (either directly or through inheritance), this method will be called right after creation and installation of parent methods.

object_tie_list

Deprecated. Use array instead.

Functions like tie_list, but maintains an array of referenced objects in each slot.

 object_tie_list =>
  [
    {
      slot => xxx, # or [ ... , ... ]
      tie_array => [ 'ArrayName', args ,...] ,
      class => ['ObjName', constructor_args ]
    },
    ...
  ]

When xxx is called with one or several arguments, Each argument is:

• Stored in the array if the argument is an object of the class 'ObjName'.

• Used to create a new object of the class 'ObjName' if the argument is an array ref. The elements of the array ref are passed to the constructor *after* the default constructor arguments.

• Discarded if any other case. A new object is created using the default constructor arguments and stored in the array.

If the stored object features a cim_init method (either directly or through inheritance), this method will be called right after creation and installation of parent methods.

cpanm Class::IntrospectionMethods

perl -MCPAN -e shell
install Class::IntrospectionMethods