Provided by: libur-perl_0.410-1_all bug

NAME

       UR::ModuleBase - Methods common to all UR classes and object instances.

DESCRIPTION

       This is a base class for packages, classes, and objects which need to manage basic
       functionality in the UR framework such as inheritance, AUTOLOAD/AUTOSUB methods,
       error/status/warning/etc messages.

       UR::ModuleBase is in the @ISA list for UR::Object, but UR::ModuleBase is not a formal UR
       class.

METHODS

       "class"
             $class = $obj->class;

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

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

       "super_can"
             $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.

       "inheritance"
             @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.

       "parent_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.

       "base_dir"
             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.

       methods
           Undocumented.

       "context_return"
             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.

"AUTOLOAD"

       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 receive 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;

MESSAGING

       UR::ModuleBase implements several methods for sending and storing error, warning and
       status messages to the user.

         # common usage

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

         unless ($obj->foo) {
             print LOG $obj->error_message();
         }

   Messaging Methods
       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.

           Standard message types are error, status, warning, debug and usage.

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

       For each message type, several methods are created for sending and retrieving messages,
       registering a callback to run when messages are sent, controlling whether the messages are
       printed on the terminal, and whether the messages are queued up.

       For example, for the "error" message type, these methods are created:

       error_message
               $obj->error_message("Something went wrong...");
               $msg = $obj->error_message();

           When called with one argument, it sends an error message to the object.  The
           error_message_callback will be run, if one is registered, and the message will be
           printed to the terminal.  When called with no arguments, the last message sent will be
           returned.  If the message is "undef" then no message is printed or queued, and the
           next time error_message is run as an accessor, it will return undef.

       dump_error_messages
               $obj->dump_error_messages(0);
               $flag = $obj->dump_error_messages();

           Get or set the flag which controls whether messages sent via "error_message()" is
           printed to the terminal.  This flag defaults to true for warning and error messages,
           and false for others.

       queue_error_messages
               $obj->queue_error_messages(0);
               $flag = $obj->queue_error_messages();

           Get or set the flag which control whether messages send via "error_message()" are
           saved into a list.  If true, every message sent is saved and can be retrieved with
           error_messages() or error_messages_arrayref().  This flag defaults to false for all
           message types.

       error_messages_callback
               $obj->error_messages_callback($subref);
               $subref = $obj->error_messages_callback();

           Get or set the callback run whenever an error_message is sent.  This callback is run
           with two arguments: The object or class error_message() was called on, and a string
           containing the message.  This callback is run before the message is printed to the
           terminal or queued into its list.  The callback can modify the message (by writing to
           $_[1]) and affect the message that is printed or queued.  If $_[1] is set to "undef",
           then no message is printed or queued, and the last recorded message is set to undef as
           when calling error_message with undef as the argument.

       error_messages
               @list = $obj->error_messages();

           If the queue_error_messages flag is on, then this method returns the entire list of
           queued messages.

       error_messages_arrayref
               $listref = $obj->error_messages_arrayref();

           If the queue_error_messages flag is on, then this method returns a reference to the
           actual list where messages get queued.  This list can be manipulated to add or remove
           items.

       error_message_source
               %source_info = $obj->error_message_source

           Returns a hash of information about the most recent call to error_message.  The key
           "error_message" contains the message.  The keys error_package, error_file, error_line
           and error_subroutine contain info about the location in the code where error_message()
           was called.

       error_package
       error_file
       error_line
       error_subroutine
           These methods return the same data as $obj->error_message_source().

SEE ALSO

       UR(3)