/ 
UI-Various-0.21
River stage one • 1 direct dependent • 1 total dependent
/ UI::Various::core

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

see UI::Various::import

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 string

description:

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 string

description:

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, __PACKAGE__, '::new');

parameters:

$level              debug-level of the message (>= 1)
@message            the text to be printed

description:

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 module

description:

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 values

description:

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 set

description:

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 set

description:

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 class

returns:

the current value of the attribute (SCALAR references are dereferenced)

access_varref - special accessor for UI elements needing SCALAR ref.

$value = $ui_element->attribute();
$ui_element->attribute(\$variable);

parameters:

$variable           optional SCALAR reference to be set

description:

This function contains a variant of the common accessor access that is used by attributes needing a SCALAR reference to a variable. Those still always return the current value of the variable when used as getter, but the setter directly uses the SCALAR reference.

The internal implementation has the following interface (note the missing subroutine):

$value = access_varref($attribute, $self, $new_value);

It is used like this:

sub attribute($;$)
{
    return access_varref('attribute', @_);
}

The additional parameters are:

$attribute            name of the attribute
$self                 reference to the class object
$r_variable           the optional SCALAR reference

returns:

the current value of the attribute (the SCALAR reference is 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

UI::Various

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 (at) cpan (dot) org>