/ 
UI-Various-0.05
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, TODO);

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

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

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).

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

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@cpan.org>