Provided by: libcipux-perl_3.4.0.13-4.1_all bug

NAME

       CipUX - Common CipUX functions

VERSION

       version 3.4.0.13

SYNOPSIS

         use CipUX;

         my $cipux = $CipUX->new();

         my $max = $cipux->max(5,6);

       Or use as base class:

         use base(CipUX);

         my $max = $self->max(5,6);

DESCRIPTION

       Provides functions common to all CipUX classes and scripts.

CONSTRUCTOR

   new
       Constructor

         my $cipux = CipUX->new();

SUBROUTINES/METHODS

       The following functions will be exported by CipUX.

   get_linewidth
       Returns the CipUX line width.

   perr
       Prints an exception that variable name VARNAME was not used in subroutine API. This is
       used to discover internal programming errors.

         $cipux->perr('<NAME OF PARAMETER>');
         $cipux->perr('<NAME OF PARAMETER>','<LINE NUMBER>');

       Example:

         $cipux->perr('parameter_x');
         $cipux->perr('parameter_x', 98);

   exc
       Prints a CipUX default exception on STDERR and exits.

        $self->exc({nr=>$nr, value=>$value, msg=>$msg });

   config
       Central function to retrieve config space.

         my ($x_hr, $y_hr, $z_hr) = $self->config({config_ar=>$config_ar});

       Local <NAME>_config subroutine should be use to fill $config_ar

         Example:

         sub task_config {
             my $config_ar = [];
             push @{$config_ar}, '/home/dummmy/cipux-task.conf';
             my ($x_hr, $y_hr, $z_hr) =
               $self->config({config_ar=>$config_ar});
             return ($x_hr, $y_hr, $z_hr);
         }

   source
       Incorporates a config file.

   store_mattrvalue
       Helper function for multiple getopt parameter with values.

   store_attrvalue
       Helper function for single getopt parameter with value.

   homedir
       This is an auxiliary method replacing ~ with $ENV{HGOME}.

       Syntax:

        my $file1  =  $common->homedir($file2);

       Example:

        if $file1  =  ~/.cipux/cipux-object.conf
        and $ENV{HOME} = /root
        then file2 =  /root/.cipux/cipux-object.conf

   lf
       Laundering LDAP filter.

   lp
       Laundering passwords.

   li
       Laundering integer values.

   l
       Laundering of a scalar

        my $scalar = $self->l($input);

   h
       Check if type is hash or hash reference.

        my $hash_hr = $self->a($input_hr);

   a
       Check if type is array or array reference.

        my $array_ar = $self->a($input_ar);

   test_cli_option
       Executes some basic test on command line option regarding a hash.

   date_time
       returns date time format of today

   latin1_to_utf8
       Converts latin to UTF-8 encoding.

   login_prompt
       Prints a login prompt on STDOUT.

   password_prompt
       Prints a password prompt on STDOUT.

   random_password
       Calculates and returns a relatively random password.

   hash_password
       Calculates and returns a hashed password.

   min
       Calculate the minimum of two integer values.

   max
       Calculate the maximum of two integer values.

   out
       Prints content to STDOUT.

   _merge_array
       Helper subroutine for _hash_merge_setup. It uses Array::Unique to return a merged unique
       array reference.

   _hash_merge_setup
       Perform setup for Hash::Merge. The main change is that Arrays are also merged with uniq
       values.

   cfg_ext
       Gets all supported extensions from Config::Any and remove non supported extensions.

   cfg
       Query the CipUX config space to load configuration in various formats.

        0. Set cfgbase to "cipux" (+ "-$submodule" if not core module)

        1. Set cfgpaths to...:
           1. /usr/share/cipux/etc/$cfgbase.$ext
           2. /usr/share/cipux/etc/$cfgbase.d/*.$ext
           3. /etc/cipux/$cfgbase.$ext
           4. /etc/cipux/$cfgbase.d/*.$ext
           5. ~/.cipux/$cfgbase.$ext

        2. Possible $ext are: cnf .conf .json .jsn .xml .yml .yaml .ini .pl .perl

        #3. Optionally parse and validate uppercase "$cfgbase_cfg" environment
            variable [fail if validation fails]

        #4. Optionally parse and validate "cfg" commandline option
            [fail if validation fails]

        5. Resolve configfile list as cfgpaths, with "$cfgbase_cfg" and "cfg" appended
           if there

        6. Resolve bootstrap file through parsing and validating "bootstrap" option
           from all available files in cfgpaths, later declaration overriding earlier
           ones

        7. Resolve all options through executing bootstrap file

        #8. Optionally override subset of options through parsing and validating
           environment variables starting with uppercase "$cfgbase_"
           [fail if any validation fails]

        9. Optionally override subset of options through parsing and validating all
           options from all available files in cfgpaths [fail if any validation fails]

       Notes about the above:

        * Number with leading "#" are not implemented.

        * config files are "layered", allowing overrides. Personal configfile
          is included last, not first, and more locations are supported.

        #* (subset of) options can be provided through ENV

        #* commandline and environment options are validated as part of parsing

       Recommendation:

       Even if several formats are supported, that does not mean they are all suited for this
       task.

        * Some configuration formats for example are too simple to express the complex
          cipux-task.perl configuration.

        * The CPAN Perl modules used for this configuration space are rather young
          Config::Any 2006 - 2009, Hash::Merge 2001 - 2009  and not every
          configuration file type mixture was tested. As a recommendation, you should
          not mix to many files and formats.

   create_cache_dir_if_not_present
       Creates a directory 'cipux' under /var/cache if not present. This is used to store
       serialized objects.

   iterate_config_space
       Takes a single config file $cfg (can be undef, but must be present) and a string
       representing the configuration base $cfgbase. It will then just use $cfg or it will find
       out regarding to $cfgbase what files should be considered.

         my $loadcfg_ar = $self->iterate_config_space(
             {
                 cfg     => $cfg,
                 cfgbase => $cfgbase,
             }
         );

       returns a list of all configuration files which should be evaluated.

   evaluate_config_space
       Takes a araay ref to a list of configuration files $loadcfg_ar, preferably cunstructed by
       iterate_config_space. It also taks a string $cache_dir to the temporary location of a
       cache_dir. This value can be empty but not undef and has to be provided. It also require
       the $cfgbase string, the "domain" of the configuration.

       It will calculate for every config file the MD5sum for later comparison.

               my $clean = $self->evaluate_config_space(
                   {
                       loadcfg_ar => $loadcfg_ar,
                       cache_dir  => $cache_dir,
                       cfgbase    => $cfgbase,
                   }
               );

       It will return 0 if changed files are found and 1 if no changed files are found.

DIAGNOSTICS

       This module generates the following exceptions:

       TODO

CONFIGURATION AND ENVIRONMENT

       Not applicable.

DEPENDENCIES

        Array::Unique
        Carp
        Class::Std
        Config::Any
        Data::Dumper
        Date::Manip
        English
        File::Basename
        File::Glob
        File::Path
        Hash::Merge
        Log::Log4perl
        Pod::Usage
        Readonly
        Storable
        Term::ReadKey
        Unicode::String
        version

INCOMPATIBILITIES

       Not known.

BUGS AND LIMITATIONS

       Not known.

SEE ALSO

       See the CipUX web page and the manual at <http://www.cipux.org>

       See the mailing list <http://sympa.cipworx.org/wws/info/cipux-devel>

AUTHOR

       Christian Kuelker  <christian.kuelker@cipworx.org>

LICENSE AND COPYRIGHT

       Copyright (C) 2007 - 2009 by Christian Kuelker

       This program is free software; you can redistribute it and/or modify it under the terms of
       the GNU General Public License as published by the Free Software Foundation; either
       version 2, or (at your option) any later version.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License along with this program;
       if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
       MA 02111-1307 USA