NAME
    Clustericious::Config - configuration files for Clustericious nodes.

VERSION
    version 0.25

SYNOPSIS
    In your ~/etc/MyApp.conf file:

     ---
     % extends_config 'global';
     % extends_config 'hypnotoad', url => 'http://localhost:9999', app => 'MyApp';

     url : http://localhost:9999
     start_mode : hypnotoad
     hypnotoad :
        - heartbeat_timeout : 500
 
     arbitrary_key: value

    In your ~/etc/globa.conf file:

     ---
     somevar : somevalue

    In your ~/etc/hypnotoad.conf:

     listen :
        - <%= $url %>
     # home uses File::HomeDir to find the calling users'
     # home directory
     pid_file : <%= home %>/<%= $app %>/hypnotoad.pid
     env :
        MOJO_HOME : <%= home %>/<%= $app %>

    From a Clustericious::App:

     package MyApp;
 
     use Mojo::Base qw( Clustericious::App );
 
     package MyApp::Routes;
 
     use Clustericious::RouteBuilder;
 
     get '/' => sub {
       my $c = shift;
       my $config = $c; # $config isa Clustericious::Config
   
       # returns the value if it is defined, foo otherwise
       my $value = $config->arbitrary_key(default => 'foo');
     };

    From a script:

     use Clustericious::Config;
 
     my $c = Clustericious::Config->new("MyApp");
     my $c = Clustericious::Config->new( \$config_string );
     my $c = Clustericious::Config->new( \%config_data_structure );

     print $c->url;
     print $c->{url};

     print $c->hypnotoad->listen;
     print $c->hypnotoad->{listen};
     my %hash = $c->hypnotoad;
     my @ary  = $c->hypnotoad;

     # Supply a default value for a missing configuration parameter :
     $c->url(default => "http://localhost:9999");
     print $c->this_param_is_missing(default => "something_else");

     # Dump out the entire config as yaml
     print $c->dump_as_yaml;

DESCRIPTION
    Clustericious::Config reads configuration files which are
    Mojo::Template's of JSON or YAML files. There should generally be an
    entry for 'url', which may be used by either a client or a server
    depending on how this node in the cluster is being used.

    After rendering the template and parsing the JSON, the resulting object
    may be called using method calls or treated as hashes.

    Config files are looked for in the following places (in order, where
    "MyApp" is the name of the app) :

        $CLUSTERICIOUS_CONF_DIR/MyApp.conf
        $HOME/etc/MyApp.conf
        /util/etc/MyApp.conf
        /etc/MyApp.conf

    The helper "extends_config" may be used to read default settings from
    another config file. The first argument to extends_config is the
    basename of the config file. Additional named arguments may be passed to
    that config file and used as variables within that file. After reading
    another file, the hashes are merged (i.e. with Hash::Merge); so values
    anywhere inside the data structure may be overridden.

    YAML config files must begin with "---", otherwise they are interpreted
    as JSON.

    This module provides a number of helpers which can be used to get system
    details (such as the home directory of the calling user or to prompt for
    passwords). See Clustericious::Config::Helpers for details.

CONSTRUCTOR
  new
    Create a new Clustericious::Config object. See the SYNOPSIS for possible
    invocations.

METHODS
  $config->dump_as_yaml
    Returns a string with the configuration encoded as YAML.

  Clustericious::Config->set_singleton
    Cache a config object to be returned by the constructor. Usage:

     Clustericicious::Config->set_singleton(App => $object);

ENVIRONMENT
    If the environment variable HARNESS_ACTIVE is set, and the current
    module::build object tells us that the calling module is being tested,
    then an empty configuration is used. In this situation, however, if the
    CLUSTERICIOUS_CONF_DIR environment variable is set and if it is a
    subdirectory of the current directory, then it will be used. This allows
    unit tests to provide configuration directories, but avoids using
    configurations that are outside of the build tree during unit testing.

CAVEATS
    Some filesystems do not support filenames with a colon (:) character in
    them, so for apps with a double colon in them (for example
    Clustericious::HelloWorld), a single dash character will be substituted
    for the name (for example "Clustericious-HelloWorld.conf").

NOTES
    This is a beta release. The API may change without notice.

SEE ALSO
    Mojo::Template, Hash::Merge, Clustericious, Clustericious::Client,
    Clustericious::Config::Helpers

AUTHOR
    original author: Brian Duggan

    current maintainer: Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2013 by NASA GSFC.

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

