The Perl and Raku Conference 2025: Greenville, South Carolina - June 27-29 Learn more

 / 
Class-IntrospectionMethods-1.003
River stage zero No dependents
/ Class::IntrospectionMethods::Catalog

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>