NAME

Class::IntrospectionMethods::Catalog - manage catalogs from IntrospectionMethods

SYNOPSIS

 No synopsis. Directly used by Class::IntrospectionMethods

DESCRIPTION

This class handles slot catalogs for Class::IntrospectionMethods.

Exported functions

set_method_info( target_class, method_name, info_ref )

Store construction info for method method_name of class target_class.

set_global_catalog (target_class, ...)

Store catalog informations. The first parameter is the class featuring the methods declared in the global catalog.

Following paramaters is a set of named paramaters (e.g. key => value):

name

Mandatory name for the global catalog

list

array ref containing the list of slot and catalog. E.g.:

 list => [
           [qw/foo bar baz/] => foo_catalog,
           [qw/a b z/]       => alpha_catalog,
           my_object         => my_catalog
         ],

isa

Optional hash ref declaring a containment for catalog. E.g:

  list => [ 'foo' => 'USER' ,
            'admin' => 'ROOT' ],
  isa  => { USER => 'ROOT' }

Then the 'ROOT' catalog will return 'foo', and the 'USER' catalog will return 'foo' and 'admin'.

help

Optional hash ref (slot_name => help). Store some help information for each slot.

set_global_catalog will construct:

• A ClassCatalog object containing the global catalog informations.

• A sub_ref containing the ClassCatalog object in a closure.

Returns ( slot_name, sub_ref ). The sub_ref is to be installed in the target class.

When called as a class method, the subref will return the ClassCatalog object. When called as a target class method, the subref will return an ObjectCatalog object associated to the ClassCatalog object stored in the closure.

These 2 object have the same API. ObjectCatalog is used to contain catalog changes that may occur at run-time. ClassCatalog informations will not change.

ClassCatalog or ObjectCatalog methods

catalog( slot_name )

Returns the catalogs names containing this slot (does not take into accounts the isa stuff)

Return either an array or an array ref depending on context.

slot ( catalog_name, ... )

Returns the slots contained in the catalogs passed as arguments. (takes into accounts the isa parameter)

all_slot()

Return a list of all slots (respecting the order defined in global_catalog).

all_catalog()

Returns a sorted list of all defined catalogs.

ObjectClass methods

Unknown methods will be forwarded to associated ClassCatalog object.

change( slot_name, catalog_name )

Move the slot into catalog catalog_name.

reset( slot_name )

Put back slot in catalog as defined by global_catalog (and as stored in ClassCatalog).

ClassCatalog methods

help ( slot_name )

Return the help info for slot_name that was given to set_global_catalog. Return an empty string if no help was provided. This help method is just a place holder, no fancy treatment is done.

info ( slot_name )

Returns construction informations of slot_name. This is handy for introspection of actual properties of slot slot_name.

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.

EXAMPLE

 package X ;
 use ExtUtils::testlib;
 
 use Class::IntrospectionMethods qw/make_methods set_obsolete_behavior/;
 
 make_methods
   (
    # slot order is important in global_catalog (and will be respected)
    global_catalog => 
    {
     name => 'metacat',
     list => [
             [qw/foo bar baz/]                 => foo_cat,
             [qw/a b z/]                       => alpha_cat,
             [qw/stdhash my_object my_scalar/] => my_cat
            ],
     isa => { my_cat => 'alpha_cat'} # my_cat includes alpha_cat
    },
    get_set => [qw/bar foo baz/],
 
    hash => 
    [
     a => {
           tie_hash      => ['MyHash', dummy => 'booh'],
           class_storage => ['MyObj', 'a' => 'foo']
          },
     [qw/z b/] => {
                   tie_hash => ['MyHash'],
                   class_storage => ['MyObj', 'b' => 'bar']
                  },
     stdhash => {
                 class_storage => ['MyObj', 'a' => 'foo']
                }
    ],
 
    object => [ 'my_object' => 'MyObj'  ],
    tie_scalar => [ 'my_scalar' => ['MyScalar' , foo => 'bar' ]] ,
    new => 'new' 
   );
 
 package main;
 
 # class catalog
 my $class_cat_obj = &X::metacat ;
 
 print $class_cat_obj->all_catalog];
 # -> alpha_cat foo_cat my_cat
 print $class_cat_obj->slot('foo_cat') ;
 # -> foo bar baz
 print $class_cat_obj->slot('alpha_cat');
 # -> a b z
 print $class_cat_obj->slot('my_cat');
 # -> a b z stdhash my_object my_scalar
 print $class_cat_obj->catalog('a');
 # -> alpha_cat
 print $class_cat_obj->info('my_object');
 # -> slot_type scalar class MyObj
 
 # more complex info result
 my @result = $class_cat_obj->info('a') ;
 
 # @result is :
 #        [
 #         'slot_type', 'hash',
 #         'class', 'MyObj',
 #         'class_args', ['a', 'foo'],
 #         'tie_index', 'MyHash',
 #         'tie_index_args', ['dummy', 'booh']
 #        ], 
 
 
 @result = $class_cat_obj->info('my_scalar') ;
 
 # @result is :
 #        [
 #         'slot_type', 'scalar',
 #         'tie_scalar', 'MyScalar',
 #         'tie_scalar_args', ['foo', 'bar']
 #        ], "test class_cat_obj->info('my_scalar')") ;
 
 # object catalog
 
 my $o = new X;
 my $cat_obj = $o->metacat ;
 
 print $cat_obj->all_catalog;
 # -> alpha_cat foo_cat my_cat
 print $cat_obj->slot('foo_cat');
 # -> foo bar baz
 
 # moving a slot
 print $class_cat_obj->catalog('stdhash') ;
 # -> my_cat
 
 $cat_obj->change('stdhash' => 'foo_cat') ;
 
 # class catalog has not changed
 print $class_cat_obj->catalog('stdhash') ;
 # -> my_cat
 
 # my_cat does no longer feature stdhash
 print $cat_obj->slot('my_cat');
 # -> a b z my_object my_scalar
 
 # stdhash is now in foo_cat
 print $cat_obj->slot('foo_cat') ;
 # -> foo bar baz stdhash
 
 print $cat_obj->catalog('stdhash');
 # -> foo_cat

COPYRIGHT

Copyright (c) 2004 Dominique Dumont. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

  L<Class::IntrospectionMethods>

cpanm Class::IntrospectionMethods

perl -MCPAN -e shell
install Class::IntrospectionMethods