NAME
UI::Various::core - core functions of UI::Various
SYNOPSIS
# This module should never be used directly!
# It is used indirectly via the following:
use UI::Various;ABSTRACT
This module is the main worker module for the UI::Various package.
DESCRIPTION
The documentation of this module is mainly intended for developers of the package itself.
Basically the module is a singleton providing a set of functions to be used by the other modules of UI::Various.
EXPORT
No data structures are exported, the core module is only accessed via its functions (and initialised with the import method indirectly called via use UI::Various;).
METHODS and FUNCTIONS
import - initialisation of UI::Various package
Otherwise this method just exports the core functions to our other modules.
language - get or set currently used language
internal implementation of UI::Various::language
logging - get or set currently used logging-level
internal implementation of UI::Various::logging
stderr - get or set currently used handling of output
internal implementation of UI::Various::stderr
using - get currently used UI as text string
internal implementation of UI::Various::using
ui - get currently used UI
$interface = UI::Various::core::ui();example:
$_ = UI::Various::core::ui() . '::Main::_init';
{ no strict 'refs'; &$_($self); }description:
This function returns the full name of the currently used user interface, e.g. to access its methods.
returns:
full name of UI
fatal - abort with error message
fatal($message_id, @message_data);example:
fatal('bad_usage_of__1_as__2', __PACKAGE__, $pkg);
fatal('UI__Various__core_must_be_1st_used_from_UI__Various');parameters:
$message_id ID of the text or format string in language module
@message_data optional additional text data for format stringdescription:
This function looks up the format (or simple) string passed in $message_id in the text hash of the currently used language, formats it together with the @message_data with sprintf and passes it on to croak.
error / warning / info - print error / warning / info message
error($message_id, @message_data);
warning($message_id, @message_data);
info($message_id, @message_data);example:
warning(1, 'message__1_missing_in__2', $message_id, $UI->{language});parameters:
$message_id ID of the text or format string in language module
@message_data optional additional text data for format stringdescription:
If the current logging level is lower than ERROR / WARNING / INFO these function do nothing. Otherwise they print the formatted message using _message.
_message has logging level to be printed as additional 1st parameter. It checks the logging level, looks up the format (or simple) string passed in $message_id in the text hash of the currently used language, formats the latter together with the @message_data with sprintf and passes it on to carp (in case of errors or warnings) or warn (in case of informational messages).
returns:
always undef (to allow something like return error(...); indicating the error to the caller)
debug - print debugging message
debug($level, @message);example:
debug(1, TODO);parameters:
$level debug-level of the message (>= 1)
@message the text to be printeddescription:
If the current logging level is lower than DEBUG_n (with n being the $level specified in the call) this function does nothing. Otherwise it prints the given text. Note that debugging messages are always English, so they can be added / removed / changed anytime without bothering about the UI::Various::language modules. Also note that debug messages are printed with warn and prefixed with DEBUG and some blanks according to the debug-level.
msg - look-up text for currently used language
$message = msg($message_id);example:
$_ = sprintf(msg($message_id), @_);parameters:
$message_id ID of the text or format string in language moduledescription:
This method looks up the format (or simple) string passed in $message_id in the text hash of the currently used language and returns it.
construct - common constructor for UI elements
$ui_element = UI::Various::Element->new(%attributes);example:
$ui_element = UI::Various::Element->new();
$ui_element = UI::Various::Element->new(attr1 => $val1, attr2 => $val2);
$ui_element = UI::Various::Element->new({attr1 => $val1, attr2 => $val2});parameters:
%attributes optional hash with initial attribute valuesdescription:
This function contains the common constructor code of all UI element classes ( UI::Various::[A-Z]*). Initial values can either be passed as an array of key/value pairs or as a single reference to a hash containing those key/value pairs. Note that if the class defines a (private) setter method _attr (tried 1st) or a (public) accessor attr (tried 2nd), it is used to assign the value before falling back to a simple assignment.
The internal implementation has the following interface:
$self = construct($attributes, $re_allowed_params, $self, @_);It is used like this:
sub new($;\[@$])
{
return construct({ DEFAULT_ATTRIBUTES },
'^(?:' . join('|', ALLOWED_PARAMETERS) . ')$',
@_);
}The additional parameters are:
$attributes reference to hash with default attributes
$re_allowed_params regular expression matching all allowed parameters
$self name of class or reference to other element of class
@_ parameters passed to caller's C<new>returns:
blessed new UI element
access - common accessor for UI elements
$value = $ui_element->attribute();
$ui_element->attribute($value);parameters:
$value optional value to be setdescription:
This function contains the common accessor code of all UI element classes ( UI::Various::[A-Z]*) aka implementing a combined standard getter / setter. When it's called with a value, the attribute is set. In all cases the current (after modification, if applicable) value is returned. If the value is a SCALAR reference it is stored as reference but returned as value.
The internal implementation has the following interface:
$value = access($attribute, $sub_set, $self, $new_value);It is used like this:
sub attribute($;$)
{
return access('attribute', sub{ ... }, @_);
}
or simply
sub attribute($;$)
{
return access('attribute', undef, @_);
}The additional parameters are:
$attribute name of the attribute
$sub_set optional reference to a subroutine called when
the function is used as a setter (see below)
$self reference to the class object
@_ the optional new value and possible other parameters
passed to C<$sub_set>The optional subroutine gets the new value passed in $_ and must return the value to be set in $_ as well. To allow for complicated tests and/or side-effects it gets $self and possible additional parameters passed in @_. The return value of the subroutine itself decides, if the attribute is modified: If it's undef, the previous value is kept. In all other cases the attribute gets the new value as defined in $_. Note that the subroutine gets the value even in case of a SCALAR reference.
If no additional code is needed, the parameter can be undef as in the 2nd example above.
returns:
the current value of the attribute (SCALAR references are dereferenced)
set - common setter for UI elements
$ui_element->attribute($value);parameters:
$value mandatory value to be setdescription:
This function contains the common setter code of all UI element classes ( UI::Various::[A-Z]*). Basically it's an accessor with a mandatory value to be set. Like access it returns the updated value. If the value is a SCALAR reference it is stored as reference but returned as value.
The internal implementation has the following interface:
$value = set($attribute, $sub_set, $self, $new_value);It is used like this:
sub _attribute($$)
{
return set('attribute', sub{ ...; }, @_);
}
or simply
sub _attribute($$)
{
return set('attribute', undef, @_);
}The additional parameters are:
$attribute name of the attribute
$sub_set optional reference to a subroutine called within the
setter
$self name of class or reference to other element of class
@_ the new value and possible other parameters passed
to C<$sub_set>The optional subroutine gets the new value passed in $_ and must return the value to be set in $_ as well. To allow for complicated tests and/or side-effects it gets $self and possible additional parameters passed in @_. The return value of the subroutine itself decides, if the attribute is modified: If it's undef, the previous value is kept. In all other cases the attribute gets the new value as defined in $_. Note that the subroutine gets the value even in case of a SCALAR reference.
If no additional code is needed, the parameter can be undef as in the 2nd example above.
returns:
the new value of the attribute (SCALAR references are dereferenced)
get - common getter for UI elements
$value = $ui_element->attribute();description:
This function contains the common getter code of all UI element classes ( UI::Various::[A-Z]*), implementing a very simple getter returning the current value of the attribute (but still with all sanity checks). Note that if the attribute is a SCALAR reference it is nonetheless returned as value. (If you really need the reference itself, access it directly as $ui_element-{attribute}>.)
The internal implementation has the following interface:
$value = get($attribute, $self);It is used like this:
sub attribute($) { return get('attribute', @_); }The additional parameters are:
$attribute name of the attribute
$self name of class or reference to other element of classreturns:
the current value of the attribute (SCALAR references are dereferenced)
dummy_varref - create a dummy SCALAR reference
$scalar = dummy_varref();description:
This function returns a SCALAR reference to a dummy variable initialised with an empty string. Note that each call returns a reference to a different variable. The function can be used to initialise use constant constants.
returns:
a scalar reference to an empty variable
SEE ALSO
LICENSE
Copyright (C) Thomas Dorner.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See LICENSE file for more details.
AUTHOR
Thomas Dorner <dorner@cpan.org>