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:

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

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