Code Index:

package UR::ModuleBase
package UR::ModuleBase::Message
__END__
EOF

NAME

UR::ModuleBase - Error, status, and warning messaging for derived packages

SYNOPSIS

    # common usage

    sub foo {
        my $self = shift;
        ...
        if ($problem) {           
            $self->error_message("Something went wrong...");
            return;
        }
        return 1;
    }

    unless ($obj->foo) {
        print STDERR $obj->error_string;
    }

    # A complete object is made with each error, staus,
    # or warning message with detail about the context in 
    # which it was created.

    # Some of the details are accessible directly on the object/class:
    $string       = $obj->error_string;
    $text         = $obj->error_text;
    $package_name = $obj->error_package;
    @call_stack   = $obj->error_call_stack;
    $time         = $obj->error_time;

    # The developer can also get the message object directly
    # and examine the properties.
    $msg_obj      = $obj->error_object;
        $string         = $msg_obj->string; 
        $text           = $msg_obj->text;
        $package_name   = $msg_obj->package_name;
        @call_stack     = $msg_obj->call_stack;
        $time           = $msg_obj->time;
        $type           = $msg_obj->type;  # "error"
        $owner          = $msg_obj->owner; # $obj

    # WARNING: error_message will return the last error specified
    # on that object/class.  It is not automatically reset when
    # other methods are called which work without error.

    # When no error is explicitly found, a check is made against
    # the last error in general (UR::ModuleBase->error_message)
    # and call stacks are compared.  If it occurred in something    
    # called by the caller.

DESCRIPTION

This is a base class for packages, classes, and objects which need to set/get error, warning, debug, and status messages on themselves, their class, and their parent class(es).

METHODS

These methods create and change message handlers.

  $class = $obj->class;

This returns the class name of a class or an object. It is exactly equivalent to:

    (ref($self) ? ref($self) : $self)

  $obj->super_class->super_class_method1();
  $obj->super_class->super_class_method2();

This returns the super-class name of a class or an object. It is exactly equivalent to: $self->class . "::SUPER"

Note that MyClass::SUPER is specially defined to include all of the items in the classes in @MyClass::ISA, so in a multiple inheritance scenario:

  $obj->super_class->super_class_method1();
  $obj->super_class->super_class_method2();

...could have super_class_method1() in one parent class and super_class_method2() in another parent class.

  $sub_ref = $obj->super_can('func');

This method determines if any of the super classes of the $obj object can perform the method func. If any one of them can, reference to the subroutine that would be called (determined using a depth-first search of the @ISA array) is returned. If none of the super classes provide a method named func, undef is returned.

  @classes = $obj->inheritance;

This method returns a depth-first list of all the classes (packages) that the class that $obj was blessed into inherits from. This order is the same order as is searched when searching for inherited methods to execute. If the class has no super classes, an empty list is returned. The UNIVERSAL class is not returned unless explicitly put into the @ISA array by the class or one of its super classes.

  MyClass->parent_classes;

This returns the immediate parent class, or parent classes in the case of multiple inheritance. In no case does it follow the inheritance hierarchy as ->inheritance() does.

  MyModule->base_dir;

This returns the base directory for a given module, in which the modules's supplemental data will be stored, such as config files and glade files, data caches, etc.

It uses %INC.

This package impliments AUTOLOAD so that derived classes can use AUTOSUB instead of AUTOLOAD.

When a class or object has a method called which is not found in the final class or any derived classes, perl checks up the tree for AUTOLOAD. We impliment AUTOLOAD at the top of the tree, and then check each class in the tree in order for an AUTOSUB method. Where a class implements AUTOSUB, it will recieve a function name as its first parameter, and it is expected to return either a subroutine reference, or undef. If undef is returned then the inheritance tree search will continue. If a subroutine reference is returned it will be executed immediately with the @_ passed into AUTOLOAD. Typically, AUTOSUB will be used to generate a subroutine reference, and will then associate the subref with the function name to avoid repeated calls to AUTOLOAD and AUTOSUB.

Why not use AUTOLOAD directly in place of AUTOSUB?

On an object with a complex inheritance tree, AUTOLOAD is only found once, after which, there is no way to indicate that the given AUTOLOAD has failed and that the inheritance tree trek should continue for other AUTOLOADS which might impliment the given method.

Example:

    package MyClass;
    our @ISA = ('UR');
    ##- use UR;    

    sub AUTOSUB
    {
        my $sub_name = shift;        
        if ($sub_name eq 'foo')
        {
            *MyClass::foo = sub { print "Calling MyClass::foo()\n" };
            return \&MyClass::foo;
        }
        elsif ($sub_name eq 'bar')
        {
            *MyClass::bar = sub { print "Calling MyClass::bar()\n" };
            return \&MyClass::bar;
        }
        else
        { 
            return;
        }
    }

    package MySubClass;
    our @ISA = ('MyClass');

    sub AUTOSUB
    {
        my $sub_name = shift;
        if ($sub_name eq 'baz')
        {
            *MyClass::baz = sub { print "Calling MyClass::baz()\n" };
            return \&MyClass::baz;
        }
        else
        { 
            return;
        }
    }

    package main;

    my $obj = bless({},'MySubClass');    
    $obj->foo;
    $obj->bar;
    $obj->baz;

  MyClass->can('some_subroutine_name');

The normal version of can() is in UNIVERSAL. We override it here so that functions implimented by AUTOSUB will be found where UNIVERSAL::can() would fail to do so.

Undocumented.

  return MyClass->context_return(@return_values);

Attempts to return either an array or scalar based on the calling context. Will die if called in scalar context and @return_values has more than 1 element.

message_types

  @types = UR::ModuleBase->message_types;
  UR::ModuleBase->message_types(@more_types);

With no arguments, this method returns all the types of messages that this class handles. With arguments, it adds a new type to the list.

Note that the addition of new types is not fully supported/implemented yet.

message_callback

  $sub_ref = UR::ModuleBase->message_callback($type);
  UR::ModuleBase->message_callback($type, $sub_ref);

This method returns and optionally sets the subroutine that handles messages of a specific type.