NAME

Hook::Modular::Builder - domain-specific language for building configurations

SYNOPSIS

use Hook::Modular::Builder;

my $config = builder {
    global {
        log     => { level => 'error' },
          cache => { base  => '/tmp/test-hook-modular' },
    };

    # or:
    # log_level 'error';
    enable 'Some::Printer',
      indent => 4, indent_char => '*', text => 'this is some printer';
    enable 'Another::Plugin', foo => 'bar' if $ENV{BAZ};
};
main->bootstrap(config => $config);

DESCRIPTION

With this module you can use a domain-specific language (DSL) to build Hook::Modular configurations. The following functions are exported automatically:

FUNCTIONS

builder

Takes a block in which you can enable plugins and define global configuration. It is normal Perl code, so you could, for example, only enable a plugin if a certain environment variable is set:

my $config = builder {
    # ...
    enable 'Another::Plugin', foo => 'bar' if $ENV{BAZ};
};

It returns a configuration hash that can be passed to Hook::Modular objects.

enable

Adds a plugin to the configuration. It takes as arguments the plugin name and an optional list of plugin configuration arguments. Plugins are added in the order in which they are defined in the builder() block.

Example:

my $config = builder {
    enable 'Some::Printer',
      indent => 4, indent_char => '*', text => 'this is some printer';
};

This is equivalent to having the following in a YAML configuration file:

plugins:
  - module: Some::Printer
    config:
      indent: 4
      indent_char: '*'
      text: 'this is some printer'

If you call this function outside a builder() block, you will get an error.

global

Defines the global configuration. Takes as arguments a hash of options.

Example:

my $config = builder {
    global {
        log     => { level => 'error' },
          cache => { base  => '/tmp/test-hook-modular' };
    };

This is equivalent to having the following in a YAML configuration file:

global:
  log:
    level: error
  cache:
    base: /tmp/test-hook-modular

If you call this function outside a builder() block, you will get an error.

log_level

Takes as an argument a log level string - for example, error - and sets the global log level configuration value; any other global configuration is left untouched.

Example:

my $config = builder {
    log_level 'error';
};

This is equivalent to the following global() call:

my $config = builder {
    global {
        log => { level => 'error' },
    };

And it is equivalent to having the following in a YAML configuration file:

global:
  log:
    level: error

If you call this function outside a builder() block, you will get an error.

cache_base

Takes as an argument a path string and sets the global cache base configuration value; any other global configuration is left untouched.

Example:

my $config = builder {
    cache_base '/tmp/test-hook-modular';
};

This is equivalent to the following global() call:

my $config = builder {
    global {
        cache => { base => 'error' },
    };

And it is equivalent to having the following in a YAML configuration file:

global:
    cache:
        base: error

If you call this function outside a builder() block, you will get an error.

METHODS

This package is also a class in disguise. The following methods are not intended for public consumption, but they are documented nevertheless.

new

Creates a new object. This method is called by builder() so it can be used by functions like enable() and global().

do_enable

Does the actual work of the enable() function. It is called from enable() with the object constructed by builder().

do_global

Does the actual work of the global() function. It is called from global() with the object constructed by builder().

do_log_level

Does the actual work of the log_level() function. It is called from log_level() with the object constructed by builder().

do_cache_base

Does the actual work of the cache_base() function. It is called from cache_base() with the object constructed by builder().

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests through the web interface at http://rt.cpan.org.

INSTALLATION

See perlmodinstall for information and options on installing Perl modules.

AVAILABILITY

The latest version of this module is available from the Comprehensive Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find a CPAN site near you. Or see http://search.cpan.org/dist/Hook-Modular/.

AUTHORS

Tatsuhiko Miyagawa <miyagawa@bulknews.net>

Marcel Grünauer, <marcel@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2007-2009 by the authors.

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