UI::Various::core - core functions of UI::Various
# This module should never be used directly! # It is used indirectly via the following: use UI::Various;
This module is the main worker module for the UI::Various package.
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.
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;).
use UI::Various;
see UI::Various::import
Otherwise this method just exports the core functions to our other modules.
internal implementation of UI::Various::language
internal implementation of UI::Various::logging
internal implementation of UI::Various::stderr
internal implementation of UI::Various::using
$interface = UI::Various::core::ui();
$_ = UI::Various::core::ui() . '::Main::_init'; { no strict 'refs'; &$_($self); }
This function returns the full name of the currently used user interface, e.g. to access its methods.
full name of UI
fatal($message_id, @message_data);
fatal('bad_usage_of__1_as__2', __PACKAGE__, $pkg); fatal('UI__Various__core_must_be_1st_used_from_UI__Various');
$message_id ID of the text or format string in language module @message_data optional additional text data for format string
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.
$message_id
@message_data
croak
error($message_id, @message_data); warning($message_id, @message_data); info($message_id, @message_data);
warning(1, 'message__1_missing_in__2', $message_id, $UI->{language});
If the current logging level is lower than ERROR / WARNING / INFO these function do nothing. Otherwise they print the formatted message using _message.
ERROR
WARNING
INFO
_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).
carp
warn
always undef (to allow something like return error(...); indicating the error to the caller)
undef
return error(...);
debug($level, @message);
debug(1, TODO);
$level debug-level of the message (>= 1) @message the text to be printed
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.
DEBUG_n
n
$level
UI::Various::language
DEBUG
$message = msg($message_id);
$_ = sprintf(msg($message_id), @_);
$message_id ID of the text or format string in language module
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.
$ui_element = UI::Various::Element->new(%attributes);
$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});
%attributes optional hash with initial attribute values
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.
UI::Various::[A-Z]*
_attr
attr
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>
blessed new UI element
$value = $ui_element->attribute(); $ui_element->attribute($value);
$value optional value to be set
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.
$value = access($attribute, $sub_set, $self, $new_value);
sub attribute($;$) { return access('attribute', sub{ ... }, @_); } or simply sub attribute($;$) { return access('attribute', undef, @_); }
$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.
$_
$self
@_
If no additional code is needed, the parameter can be undef as in the 2nd example above.
the current value of the attribute (SCALAR references are dereferenced)
$ui_element->attribute($value);
$value mandatory value to be set
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.
access
$value = set($attribute, $sub_set, $self, $new_value);
sub _attribute($$) { return set('attribute', sub{ ...; }, @_); } or simply sub _attribute($$) { return set('attribute', undef, @_); }
$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 new value of the attribute (SCALAR references are dereferenced)
$value = $ui_element->attribute();
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}>.)
$ui_element-
$value = get($attribute, $self);
sub attribute($) { return get('attribute', @_); }
$attribute name of the attribute $self name of class or reference to other element of class
$scalar = dummy_varref();
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.
use constant
a scalar reference to an empty variable
UI::Various
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.
Thomas Dorner <dorner@cpan.org>
To install UI::Various, copy and paste the appropriate command in to your terminal.
cpanm
cpanm UI::Various
CPAN shell
perl -MCPAN -e shell install UI::Various
For more information on module installation, please visit the detailed CPAN module installation guide.