.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "UR::ModuleBase 3pm"
.TH UR::ModuleBase 3pm "2019-01-02" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
UR::ModuleBase \- Methods common to all UR classes and object instances.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a base class for packages, classes, and objects which need to
manage basic functionality in the \s-1UR\s0 framework such as inheritance, 
\&\s-1AUTOLOAD/AUTOSUB\s0 methods, error/status/warning/etc messages.
.PP
UR::ModuleBase is in the \f(CW@ISA\fR list for UR::Object, but UR::ModuleBase is not
a formal \s-1UR\s0 class.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP """class""" 4
.el .IP "\f(CWclass\fR" 4
.IX Item "class"
.Vb 1
\&  $class = $obj\->class;
.Ve
.Sp
This returns the class name of a class or an object as a string.
It is exactly equivalent to:
.Sp
.Vb 1
\&    (ref($self) ? ref($self) : $self)
.Ve
.ie n .IP """super_can""" 4
.el .IP "\f(CWsuper_can\fR" 4
.IX Item "super_can"
.Vb 1
\&  $sub_ref = $obj\->super_can(\*(Aqfunc\*(Aq);
.Ve
.Sp
This method determines if any of the super classes of the \f(CW$obj\fR
object can perform the method \f(CW\*(C`func\*(C'\fR.  If any one of them can,
reference to the subroutine that would be called (determined using a
depth-first search of the \f(CW@ISA\fR array) is returned.  If none of the
super classes provide a method named \f(CW\*(C`func\*(C'\fR, \f(CW\*(C`undef\*(C'\fR is returned.
.ie n .IP """inheritance""" 4
.el .IP "\f(CWinheritance\fR" 4
.IX Item "inheritance"
.Vb 1
\&  @classes = $obj\->inheritance;
.Ve
.Sp
This method returns a depth-first list of all the classes (packages)
that the class that \f(CW$obj\fR 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 \f(CW\*(C`UNIVERSAL\*(C'\fR class is not returned unless explicitly
put into the \f(CW@ISA\fR array by the class or one of its super classes.
.ie n .IP """parent_classes""" 4
.el .IP "\f(CWparent_classes\fR" 4
.IX Item "parent_classes"
.Vb 1
\&  MyClass\->parent_classes;
.Ve
.Sp
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 \->\fBinheritance()\fR does.
.ie n .IP """base_dir""" 4
.el .IP "\f(CWbase_dir\fR" 4
.IX Item "base_dir"
.Vb 1
\&  MyModule\->base_dir;
.Ve
.Sp
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.
.Sp
It uses \f(CW%INC\fR.
.IP "methods" 4
.IX Item "methods"
Undocumented.
.ie n .IP """context_return""" 4
.el .IP "\f(CWcontext_return\fR" 4
.IX Item "context_return"
.Vb 1
\&  return MyClass\->context_return(@return_values);
.Ve
.Sp
Attempts to return either an array or scalar based on the calling context.
Will die if called in scalar context and \f(CW@return_values\fR has more than 1
element.
.ie n .SH """AUTOLOAD"""
.el .SH "\f(CWAUTOLOAD\fP"
.IX Header "AUTOLOAD"
This package implements \s-1AUTOLOAD\s0 so that derived classes can use
\&\s-1AUTOSUB\s0 instead of \s-1AUTOLOAD.\s0
.PP
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
\&\s-1AUTOLOAD.\s0  We implement \s-1AUTOLOAD\s0 at the top of the tree, and then
check each class in the tree in order for an \s-1AUTOSUB\s0 method.  Where a
class implements \s-1AUTOSUB,\s0 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 \f(CW@_\fR passed into \s-1AUTOLOAD.\s0  Typically, \s-1AUTOSUB\s0 will
be used to generate a subroutine reference, and will then associate
the subref with the function name to avoid repeated calls to \s-1AUTOLOAD\s0
and \s-1AUTOSUB.\s0
.PP
Why not use \s-1AUTOLOAD\s0 directly in place of \s-1AUTOSUB\s0?
.PP
On an object with a complex inheritance tree, \s-1AUTOLOAD\s0 is only found
once, after which, there is no way to indicate that the given \s-1AUTOLOAD\s0
has failed and that the inheritance tree trek should continue for
other \s-1AUTOLOADS\s0 which might implement the given method.
.PP
Example:
.PP
.Vb 3
\&    package MyClass;
\&    our @ISA = (\*(AqUR\*(Aq);
\&    ##\- use UR;    
\&    
\&    sub AUTOSUB
\&    {
\&        my $sub_name = shift;        
\&        if ($sub_name eq \*(Aqfoo\*(Aq)
\&        {
\&            *MyClass::foo = sub { print "Calling MyClass::foo()\en" };
\&            return \e&MyClass::foo;
\&        }
\&        elsif ($sub_name eq \*(Aqbar\*(Aq)
\&        {
\&            *MyClass::bar = sub { print "Calling MyClass::bar()\en" };
\&            return \e&MyClass::bar;
\&        }
\&        else
\&        { 
\&            return;
\&        }
\&    }
\&
\&    package MySubClass;
\&    our @ISA = (\*(AqMyClass\*(Aq);
\&    
\&    sub AUTOSUB
\&    {
\&        my $sub_name = shift;
\&        if ($sub_name eq \*(Aqbaz\*(Aq)
\&        {
\&            *MyClass::baz = sub { print "Calling MyClass::baz()\en" };
\&            return \e&MyClass::baz;
\&        }
\&        else
\&        { 
\&            return;
\&        }
\&    }
\&
\&    package main;
\&    
\&    my $obj = bless({},\*(AqMySubClass\*(Aq);    
\&    $obj\->foo;
\&    $obj\->bar;
\&    $obj\->baz;
.Ve
.SH "MESSAGING"
.IX Header "MESSAGING"
UR::ModuleBase implements several methods for sending and storing error, warning and
status messages to the user.
.PP
.Vb 1
\&  # 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();
\&  }
.Ve
.SS "Messaging Methods"
.IX Subsection "Messaging Methods"
.IP "message_types" 4
.IX Item "message_types"
.Vb 2
\&  @types = UR::ModuleBase\->message_types;
\&  UR::ModuleBase\->message_types(@more_types);
.Ve
.Sp
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.
.Sp
Standard message types are fatal, error, status, warning, debug and usage.
.Sp
Note that the addition of new types is not fully supported/implemented
yet.
.PP
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.
.PP
For example, for the \*(L"error\*(R" message type, these methods are created:
.IP "error_message" 4
.IX Item "error_message"
.Vb 3
\&    $obj\->error_message("Something went wrong...");
\&    $obj\->error_message($format, @list);
\&    $msg = $obj\->error_message();
.Ve
.Sp
When called with one or more arguments, 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 given a single argument, it will
be passed through unmodified.  When given multiple arguments, error_message will
assume the first is a format string and the remainder are parameters to
sprintf.  When called with no arguments, the last message sent will be
returned.  If the message is \f(CW\*(C`undef\*(C'\fR then no message is printed or queued, and
the next time error_message is run as an accessor, it will return
undef.
.Sp
Note that \f(CW\*(C`fatal_message()\*(C'\fR will throw an exception at the point it appears
in the program.  This exception, like others, is trappable bi \f(CW\*(C`eval\*(C'\fR.
.IP "dump_error_messages" 4
.IX Item "dump_error_messages"
.Vb 2
\&    $obj\->dump_error_messages(0);
\&    $flag = $obj\->dump_error_messages();
.Ve
.Sp
Get or set the flag which controls whether messages sent via \f(CW\*(C`error_message()\*(C'\fR
is printed to the terminal.  This flag defaults to true for warning and error
messages, and false for others.
.Sp
Note that \f(CW\*(C`fatal_message()\*(C'\fR messages and exceptions do not honor the value of
\&\f(CW\*(C`dump_fatal_messages()\*(C'\fR, and always print their message and throw their
exception unless trapped with an \f(CW\*(C`eval\*(C'\fR.
.IP "queue_error_messages" 4
.IX Item "queue_error_messages"
.Vb 2
\&    $obj\->queue_error_messages(0);
\&    $flag = $obj\->queue_error_messages();
.Ve
.Sp
Get or set the flag which control whether messages send via \f(CW\*(C`error_message()\*(C'\fR
are saved into a list.  If true, every message sent is saved and can be retrieved
with \fBerror_messages()\fR or \fBerror_messages_arrayref()\fR.  This flag defaults to
false for all message types.
.IP "error_messages_callback" 4
.IX Item "error_messages_callback"
.Vb 2
\&    $obj\->error_messages_callback($subref);
\&    $subref = $obj\->error_messages_callback();
.Ve
.Sp
Get or set the callback run whenever an error_message is sent.  This callback
is run with two arguments: The object or class \fBerror_message()\fR 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 \f(CW$_\fR[1]) and affect the message that is printed or
queued.  If \f(CW$_\fR[1] is set to \f(CW\*(C`undef\*(C'\fR, 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.
.IP "error_messages" 4
.IX Item "error_messages"
.Vb 1
\&    @list = $obj\->error_messages();
.Ve
.Sp
If the queue_error_messages flag is on, then this method returns the entire list
of queued messages.
.Sp
When called as an instance method, it returns the errors queued only on that
object.  When called as a class method, it returns the errors queued on that
class, all it's subclasses, and all instances of that class or subclasses.
.IP "error_messages_arrayref" 4
.IX Item "error_messages_arrayref"
.Vb 1
\&    $listref = $obj\->error_messages_arrayref();
.Ve
.Sp
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.
.IP "error_message_source" 4
.IX Item "error_message_source"
.Vb 1
\&    %source_info = $obj\->error_message_source
.Ve
.Sp
Returns a hash of information about the most recent call to error_message.
The key \*(L"error_message\*(R" contains the message.  The keys error_package,
error_file, error_line and error_subroutine contain info about the location
in the code where \fBerror_message()\fR was called.
.IP "error_package" 4
.IX Item "error_package"
.PD 0
.IP "error_file" 4
.IX Item "error_file"
.IP "error_line" 4
.IX Item "error_line"
.IP "error_subroutine" 4
.IX Item "error_subroutine"
.PD
These methods return the same data as \f(CW$obj\fR\->\fBerror_message_source()\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1\fBUR\s0\fR\|(3)