NAME

User::Config - Handling the per-user configuration in multi-user applications

SYNOPSIS

  use User::Config;

  has_option foo => (
        isa => 'String',
        documentation => 'a sample option',
        default => 'foobar',
        dataclass => 'myclass',
        presets => {
                "Use this" => "value",
                "or this" => "another value",
                custom => undef,
        },
  );

  has_option bar => (
        isa => 'Integer',
        default => sub { return 28; },
        hidden => 1,
  );

  ...
        $setting = $self->foo;
                

DESCRIPTION

This primaly documents this modules interface. Please see User::Config::Manual for an in-depth discussion of the concepts.

EXPORTS

has_option name;

has_option is the way to declare new user-configurable options. To specify the behaviour of this modul, the extended syntax with parameters can be used. The following parameters are currently supported:

<anon_default = ($default|sub { ... })>>

Will be used as default, but only if no user logged in. If this isn't given, default is used.

<coerce = (1|0)>>

Use coercion. See "has" in Moose

<dataclass = $db_class>>

this entry might be used by the database-backend to decide how or where to save the entry

<default = ($default|sub { ... })>>

defines the default value for a given entry. If defined this either might be a scalar, which will be used as value for this option, as long as the user didn't set it to something else. Or it might be a CODE-ref. In this case the code will be executed the first time this option is read for a certain user. On this first time it automaticly will be set in the backend.

<documentation = "Documentative string">>

Document the option. This will be accessable as $self->item->documentation and may be used by UI-Generators.

<hidden = (1|0)>>

If this set to a true value, the corresponding item will be ignored by the UI-Generator.

<isa = $type_name>>

set up runtime constrain checking for this option using "has" in Moose.

<lazy = (1|0)>>

See "has" in Moose

<noset = (1|0)>>

If set to something true, a value set to this value will silently be ignored. This implies hidden. This might be useful in conjunction with default/anon_default, if a database-connection night not be available.

<range = [ $min, $max ]>>

if this is set, the UI-Generator will assure, that the user didn't set a value outside.

<references = 'Path::To::Modul::option_name'>>

this tells User::Config to access the option_name of the Modul Path::To::Modul, when this option is accessed. Thus both options always will have the same value. The UI-Generator will silently ignore this option and do not a display a corresponding entry to the user.

<trigger = sub { ... }>>

triggers the following code every time the option is set. See "has" in Moose for details.

<ui_type = 'String'>>

this will be used by the UI-Generator to provide a suitable element.

<validate = CODEREF>>

a code that will be executed, if the user set's a new value.

<weak_ref = (1|0)>>

See "has" in Moose

METHODS

$self->context({ User => 'foo' });

This can be used to set the global or module-wide context. See User::Config::Manual for more details.

my $uc = User::Config->instance

instance will always return a handle to the global over-all object handling with the database-backend and storing references to all configuration items

$uc->db("Interface", { parameters => "" })

To set the database used to make any user-configuration persistent, the database should be set using this method. The first argument specifies the interface to be used, the second contains arguments for this interface to initialize.

For a list of valid Interfaces see User::Config::DB

$uc->ui("Interface", { parmeters => "" })

This will return a new instance for generating a userinterface. There might be multiple interfaces supported. To choose one of them, provide the name of the Interface as first parameter. Valid names are any modules within User::Config::UI. The parameters to supply will depend on the interface in use, so please refer to it's documentation.

$uc->options

This will return a hash-ref containing all currently registered options. The content will look like the following example. The reference of a given option will be the same as used in has_option.

  $ perl ... -e "print Dumper $uc->options"
  $VAR1 = {
        My::Namespace => {
                option1 => {
                },
                option2 => {
                        hidden => 1,
                },
        };

SEE ALSO

User::Config::Manual - a introduction into the concept behind User::Config

User::Config::DB - for a Overview over the database-backends

User::Config::UI - for more information on generating User-Interfaces

AUTHOR

Benjamin Tietz, <benjamin@micronet24.de>

COPYRIGHT AND LICENSE

Copyright (C) 2011 by Benjamin Tietz

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.

cpanm User::Config

perl -MCPAN -e shell
install User::Config