NAME

Basicos::Config - Carga de archivos de configuración y parámetros de llamada

SYNOPSIS

    use English;
    use Basicos::Config;
    use Pod::Usage;
    use Data::Dumper;

    my %values = eval {
       _configure( 
            file        =>  '/etc/myprogram.conf',
            env         =>  'MYPROGRAMCONF',
            perms       =>  0400,
            croak       =>  0,
            merge       =>  1,
            getopt      =>  {
                help        =>  undef,
                man         =>  sub { pod2usage(2) },
                version     =>  sub { print "myprograma - version 14.3.1\n"; }
                },
            variables   =>  {
                host    =>  [ 'host=s', undef, 'server.host', 'localhost' ],
                port    =>  [ 'port=i', undef, 'server.port', '33333' ]
                },
            defaults    =>  {
                user    =>  q(root),
                }
            )
        };

    if ($EVAL_ERROR) {
        die $EVAL_ERROR;
    }        
    else {
        #   mostramos los valores expresamente indicados 
        print "Server: " . $values{server};
        print "Port: " . $values{port};
        print "User: " . $values{user};

        #   y un volcado de todo junto (incluyendo el archivo de
        #   configuración)
        print Dumper( \%values );
    }
    
=head1 DESCRIPTION

Este módulo proporciona funciones globales para leer archivos de configuración y analizar parámetros de llamada del programa.

__top

SUBRUTINES/METHODS

_configure( %options )

Este método intenta rellenar un hash con valores procedentes de varias fuentes, y en un orden concreto. Primero utiliza los parámetros de llamada mediante the Getopt::Long manpage, luego las variables de entorno, prosigue cargando un archivo de configuración con the Config::General manpage y, por último, aplica valores por defecto.

Las opciones son las siguientes:

file: Ruta de acceso al archivo de configuración.
env: Nombre de la variable de entorno que contiene el nombre del archivo de configuración.
perms: Máscara de permisos de acceso que debe tener el archivo de configuración. En caso contrario el programa aborta la ejecución.
croak: Si este indicador no está activo, el módulo capturará todas las llamadas a die/croak, de manera que serán necesarias varias comprobaciones más tras la llamada para saber con exactitud qué ha podido fallar (ó, en otras palabras, por qué no están los valores donde deberían :-) El valor predeterminado es uno, lo que deja en manos de esta función la terminación prematura del programa.
merge: Este indicador determina si los valores leídos exclusivamente del archivo de configuración se incluyen en una entrada propia, bajo la clave CONFIG, ó se fusionan con todos los demás para retornar un hash único. El valor predeterminado es cero, i<no fusionar>.
getopt: Hash con diferentes valores para afinar la lectura de parámetros de llamada:
variables: Hash con la definición de las variables que queremos obtener en la llamada a la función.; Cada elemento puede contener una de estas tres cosas:
Referencia a un hash: El módulo acepta esta entrada, pero termina tomando los valores del hash y ordenándolos como en la opción anterior. Las entradas del hash que se tienen en cuenta son: getopt, env, config y default.
defaults: Referencia a un hash con valores predeterminados que se mezclarán con los del archivo de configuración cuando éste es leído. Las claves que aquí aparecen no tienen por qué estar declaradas anteriormente, y la función no las buscará en el entorno ó en los parámetros de llamada.

El archivo de configuración

El módulo utiliza la librería the Config::General manpage para leer el archivo de configuración, y deja una copia de todo su contenido en la entrada CONFIG del hash retornado.

Para indicar que una variable debe tomar su valor de una entrada de dicho fichero se debe utilizar la nomenclatura [seccion.]nombre como en el siguiente ejemplo:

    <server>
        host    =   machine
    </server>

    localhost => [ undef, undef, "server.host", "localhost" ]

__top

DIAGNOSTICS

Si se habilita la opción croak en la llamada, el módulo no captura ninguna de las posibles excepciones que surjan, por lo que pueden acontecer las siguientes:

invalid definition for ?: Se produce cuando en la definición de una variable el valor de la entrada no es un valor escalar, ni una refernencia a un hash ó a un array.
unexpected value: ?: Esta es una situación que no debería producirse, pero que saltaría cuando se llama a la función _show_info con un parámetro about que no corresponde a version, help ó man.
could not read file ...: No hay permisos suficientes para leer el archivo de configuración.
bad perms in config file ...: El archivo de configuración no tiene los permisos de acceso indicados en la entrada perms de los parámetros de llamada. Se considera que si esta entrada existe el riesgo de seguridad es alto, por lo que no se continúa si los permisos no concuerdan.

Además de esta lista, es conveniente mirar la documentación de the Getopt::Long manpage y the Config::General manpage porque ambos pueden alzar excepciones por varios motivos.

__top

DEPENDENCIES

Config::General
Getopt::Long
Pod::Usage
Basicos

__top

BUGS AND LIMITATIONS

There are no known bugs in this module.

Please report problems to authors.

__top

AUTHOR

Víctor Moral <victor@taquiones.net>, Angel Ortega <angel@triptico.com>

__top

LICENCE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

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.

__top

Basicos::Config - Carga de archivos de configuración y parámetros de llamada