view release on metacpan or  search on metacpan

IntrospectionMethods.pm  view on Meta::CPAN

A way to organize these slots in several catalogs.

=item *

When a slot contains object or tied scalars hashes or arrays, the
contained object can be queried for the container object.
In other words, the parent object (the one constructed by
C<Class::IntrospectionMethods> contains a child object in one of its
slots either as a plain object or an object hidden behind a tied
construct. C<Class::IntrospectionMethods> will provide the child
object a method to retrieve the parent object reference.

=back

For instance, you can use this module to create a tree where each node
or leaf is an object. In this case, this module provides methods to
navigate up the tree of objects with the installed "parent" method.

In other words, this module provides special methods to enable the
user to navigate up or down a tree (or directed graph) using
introspection (to go down) and the "parent" method to go up.

You may notice similarities between this module and
L<Class::MethodMaker>. In fact this module was written from
Class::MethodMaker v1.08, but it does not provide most of the fancy
methods of Class::MethodMaker. Only scalar, array and hash
accessors (with their tied and objects variants) are provided.

Originally, the introspection and "parent" functionalities were
implemented in Class::MethodMaker. Unfortunately, they were not
accepted by Class::MethodMaker's author since they did not fit his
own vision of his module (fair enough).

The old API of L<Class::MethodMaker> is provided as deprecated
methods. Using the new (and hopefully more consistent) API is
prefered.

=cut

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

use strict;
use warnings ;

# Inheritance -------------------------

#use AutoLoader;
#use vars qw( @ISA );
#@ISA = qw ( AutoLoader );

use vars qw( $VERSION @ISA @EXPORT_OK);

require Exporter;
@ISA = qw(Exporter);
@EXPORT_OK = qw(make_methods set_obsolete_behavior set_parent_method_name);

# Utility -----------------------------

# Necessary for parent feature
use Scalar::Util qw(isweak weaken) ;
use Class::IntrospectionMethods::Catalog 
  qw/set_global_catalog set_method_info set_method_in_catalog/;
use Class::IntrospectionMethods::Parent 
  qw/set_parent_method_name graft_parent_method/ ;

use Carp qw( carp cluck croak );

my $obsolete_behavior = 'carp' ;
my $support_legacy = 0 ;
my $legacy_object_init = 'cmm_init' ;

$VERSION = sprintf "%d.%03d", q$Revision: 1.5 $ =~ /(\d+)\.(\d+)/;

=head1 Transition from Class::MethodMaker

This module was forked from Class::MethodMaker v1.08. To ease
migration from older project (which include a proprietary project of
mine) using Class::MethodMaker to Class::IntrospectionMethods, a
compatiblity mode is provided. (although some features of
L<Class::MethodMaker> will not work. See
L<Class::IntrospectionMethods::Legacy> for details)

You can use the following function to finely tune the compatibility
behavior to either croak, carp (See L<Carp> for details) or be silent.

One note: I provide backward compatibility for Class::MethodMaker
v1.08 and the modification I made that were later refused. So you may
notice compatibility features that do not exist in Class::MethodMaker
v1.08.

=head2 set_obsolete_behavior ( behavior, provide_legacy_method)

C<behavior> is either C<skip>, C<carp> or C<croak>. (default is
C<carp>).

C<provide_legacy_method> is either 1 or 0. Default 0. When set to one,
this module will provide methods that were only available in the
modified version of Class::MethodMaker v1.08.

=cut

sub set_obsolete_behavior
  {
    ($obsolete_behavior, $support_legacy) = @_ ;
    Class::IntrospectionMethods::Parent::set_obsolete_behavior (@_) ;
    Class::IntrospectionMethods::Catalog::set_obsolete_behavior (@_) ;
  }

# internal
sub warn_obsolete
  {
    return if $obsolete_behavior eq 'skip' ;
    no strict 'refs' ;
    $obsolete_behavior->(@_) ;
  }

sub ima_method_maker { 1 };

sub find_target_class {
  # Find the class to add the methods to. I'm assuming that it would