Jifty::Config - the configuration handler for Jifty

    # in your application
    my $app_name = Jifty->config->framework('ApplicationName');
    my $frobber  = Jifty->config->app('PreferredFrobnicator');

    # sub classing
    package MyApp::Config;
    use base 'Jifty::Config';

    sub post_load {
        my $self = shift;
        my $stash = $self->stash; # full config in a hash

        ... do something with options ...

        $self->stash( $stash ); # save config
    }

    1;

    Jifty->config->framework('ApplicationName')

    Jifty->config->framework('MyOption');

    contextual_get('/framework/Database', 'Driver')

  Jifty->config

    sub post_load {
        my $self = shift;
        $self->post_load( @_ );
        ...
    }

    {
        framework => {
            ...
        },
        application => {
            ...
        },
    }

    $config->stash( $new_stash );

use warnings;
use strict;

package Jifty::Config;

use Jifty::Util;
use Jifty::YAML;

use Hash::Merge;
Hash::Merge::set_behavior('RIGHT_PRECEDENT');

use base qw/Class::Accessor::Fast/;
__PACKAGE__->mk_accessors(qw/stash/);

use vars qw/$CONFIG/;

sub framework { return shift->_get( framework => @_ ) }

sub app { return shift->_get( application => @_ ) }

# A teeny helper for framework and app
sub _get { return $_[0]->stash->{ $_[1] }{ $_[2] } }

sub contextual_get {
    my $self    = shift;
    my $context = shift;
    my $field   = shift;

    my $pointer = $self->stash;

    my @fragments = grep { length } split '/', $context;
    for my $fragment (@fragments) {
        $pointer = $pointer->{$fragment} || return;
    }

    return $pointer->{$field};
}

sub new {
    my $proto = shift;
    my %args = ( load_config => 1,
                 @_ 
             );
    my $self  = {};
    bless $self, $proto;

    # Setup the initially empty stash
    $self->stash( {} );

    # Load from file unless they tell us not to
    $self->load() if ($args{'load_config'});
    return $self;
}

sub load {
    my $self = shift;

    # Add the default configuration file locations to the stash
    $self->merge( $self->_default_config_files );

    # Calculate the location of the application etc/config.yml
    my $file = $ENV{'JIFTY_CONFIG'} || Jifty::Util->app_root . '/etc/config.yml';

    my $app;

    # Start by loading application configuration file
    if ( -f $file and -r $file ) {
        # Load the $app so we know where to find the vendor config file
        $self->merge( $self->load_file($file) );
    }

    # Load the vendor configuration file
    my $vendor = $self->load_file(
        Jifty::Util->absolute_path(
            $self->framework('VendorConfig') || $ENV{'JIFTY_VENDOR_CONFIG'}
        )
    );

    # Merge the app config with vendor config, vendor taking precedent
    $self->merge( $vendor );

    # Load the site configuration file
    my $site = $self->load_file(
        Jifty::Util->absolute_path(
            # Note: $ENV{'JIFTY_SITE_CONFIG'} is already considered
            #       in ->_default_config_files(), but we || here again
            #       in case someone overrided _default_config_files().
            $self->framework('SiteConfig') || $ENV{'JIFTY_SITE_CONFIG'}
        )
    );

    # Merge the app, vendor, and site config, site taking precedent
    $self->merge( $site );

    # Load the test configuration file
    my $test = $self->load_file(
        Jifty::Util->absolute_path(
            $self->framework('TestConfig') || $ENV{'JIFTY_TEST_CONFIG'}
        )
    );

    # Merge the app, vendor, site and test config, test taking precedent
    $self->merge( $test );

    # Merge guessed values in for anything we didn't explicitly define
    # Whatever's in the stash overrides anything we guess
    $self->merge( $self->stash, $self->guess );
    
    # There are a couple things we want to guess that we don't want
    # getting stuck in a default config file for an app
    $self->merge( $self->stash, $self->defaults );

    # Bring old configurations up to current expectations
    $self->stash($self->update_config($self->stash));

    # check for YourApp::Config
    my $app_class = $self->framework('ApplicationClass') . '::Config';
    # we have no class loader at this moment :(
    my $found = Jifty::Util->try_to_require( $app_class );
    if ( $found && $app_class->isa('Jifty::Config') ) {
        bless $self, $app_class;
    } elsif ( $found ) {
# XXX this warning is not always useful, sometimes annoying, 
# e.g. RT has its own config mechanism, we don't want to sub-class
# Jifty::Config at all.
#        warn "You have $app_class, however it's not an sub-class of Jifty::Config."
#            ." Read `perldoc Jifty::Config` about subclassing. Skipping.";
    }

    # post load hook for sub-classes
    $self->post_load;

    # Finally, check for global postload hooks (these are used by the
    # test harness)
    $self->$Jifty::Config::postload()
      if $Jifty::Config::postload;
}

sub merge {
    my $self = shift;
    my ($new, $fallback) = @_;
    $fallback ||= $self->stash;

    delete $fallback->{framework}{MailerArgs} if exists $new->{framework}{MailerArgs};
    delete $fallback->{framework}{View}{Handlers} if exists $new->{framework}{View}{Handlers};

    $self->stash(Hash::Merge::merge( $fallback, $new ));
}

# Sets up the initial location of the site configuration file
sub _default_config_files {
    my $self = shift;
    my $config  = {
        framework => {
            SiteConfig => (
                $ENV{JIFTY_SITE_CONFIG} || 'etc/site_config.yml'
            )
        }
    };
    return $self->_expand_relative_paths($config);
}

sub post_load {}

sub load_file {
    my $self = shift;
    my $file = shift;

    # only try to load files that exist
    return {} unless ( $file && -f $file );
    my $hashref = Jifty::YAML::LoadFile($file)
        or die "I couldn't load config file $file: $!";

    # Make sure %path% values are made absolute
    $hashref = $self->_expand_relative_paths($hashref);
    return $hashref;
}

# Does a DFS, turning all leaves that look like C<%paths%> into absolute paths.
sub _expand_relative_paths {
    my $self  = shift;
    my $datum = shift;

    # Recurse through each value in an array
    if ( ref $datum eq 'ARRAY' ) {
        return [ map { $self->_expand_relative_paths($_) } @$datum ];
    } 
    
    # Recurse through each value in a hash
    elsif ( ref $datum eq 'HASH' ) {
        for my $key ( keys %$datum ) {
            my $new_val = $self->_expand_relative_paths( $datum->{$key} );
            $datum->{$key} = $new_val;
        }
        return $datum;
    } 
    
    # Do nothing with other kinds of references
    elsif ( ref $datum ) {
        return $datum;
    } 
    
    # Check scalars for %path% and convert the enclosed value to an abspath
    else {
        if ( defined $datum and $datum =~ /^%(.+)%$/ ) {
            $datum = Jifty::Util->absolute_path($1);
        }
        return $datum;
    }
}

sub guess {
    my $self = shift;

    # First try at guessing the app name...
    my $app_name;

    # Was it passed to this method?
    if (@_) {
        $app_name = shift;
    }

    # Is it already in the stash?
    elsif ( $self->stash->{framework}->{ApplicationName} ) {
        $app_name = $self->stash->{framework}->{ApplicationName};
    }

    # Finally, just guess from the application root
    else {
        $app_name = Jifty::Util->default_app_name;
    }

    # Setup the application class name based on the application name
    my $app_class = $self->stash->{framework}->{ApplicationClass}
        || $app_name;
    $app_class =~ s/-/::/g;
    my $db_name = lc $app_name;
    $db_name =~ s/-/_/g;
    my $app_uuid = Jifty::Util->generate_uuid;

    # Build up the guessed configuration
    my $guess = {
        framework => {
            AdminMode         => 1,
            DevelMode         => 1,
            SkipAccessControl => 0,
            ApplicationClass  => $app_class,
            TemplateClass     => $app_class . "::View",
            ApplicationName   => $app_name,
            ApplicationUUID   => $app_uuid,
            LogLevel          => 'INFO',
            PubSub            => {
                Enable  => undef,
                Backend => 'Memcached',
            },
            Database => {
                AutoUpgrade     => 1,
                Database        => $db_name,
                Driver          => "SQLite",
                Host            => "localhost",
                Password        => "",
                User            => "",
                Version         => "0.0.1",
                RecordBaseClass => 'Jifty::DBI::Record::Cachable',
                CheckSchema     => '1'
            },
            Mailer     => 'Sendmail',
            MailerArgs => [],
            L10N       => { PoDir => "share/po", },

            View => {
                Handlers => [
                    'Jifty::View::Static::Handler',
                    'Jifty::View::Declare::Handler',
                    'Jifty::View::Mason::Handler'
                ]
            },
            Web => {
                Port             => '8888',
                BaseURL          => 'http://localhost',
                DataDir          => "var/mason",
                StaticRoot       => "share/web/static",
                TemplateRoot     => "share/web/templates",
                ServeStaticFiles => 1,
                MasonConfig      => {
                    autoflush            => 0,
                    error_mode           => 'fatal',
                    error_format         => 'text',
                    default_escape_flags => 'h',
                },
                Globals => [],
                PSGIStatic => 1,
            },
        },
    };

    # Make sure to handle any %path% values we may have guessed
    return $self->_expand_relative_paths($guess);
}

sub initial_config {
    my $self = shift;
    my $guess = $self->guess(@_);
    $guess->{'framework'}->{'ConfigFileVersion'} = 5;

    # These are the plugins which new apps will get by default
    $guess->{'framework'}->{'Plugins'} = [
        { AdminUI            => {}, },
        { CompressedCSSandJS => {}, },
        { ErrorTemplates     => {}, },
        { Halo               => {}, },
        { LetMe              => {}, },
        { OnlineDocs         => {}, },
        { REST               => {}, },
        { SkeletonApp        => {}, },
    ];

    return $guess;
}

sub update_config {
    my $self = shift;
    my $config = shift;

    # This app configuration predates the plugin refactor
    if ( $config->{'framework'}->{'ConfigFileVersion'} < 2) {

        # These are the plugins which old apps expect because their
        # features used to be in the core.
        unshift (@{$config->{'framework'}->{'Plugins'}}, 
            { AdminUI            => {}, },
            { CompressedCSSandJS => {}, },
            { ErrorTemplates     => {}, },
            { Halo               => {}, },
            { OnlineDocs         => {}, },
            { REST               => {}, },
            { SkeletonApp        => {}, },
        );
    }

    if ( $config->{'framework'}->{'ConfigFileVersion'} < 3) {
        unshift (@{$config->{'framework'}->{'Plugins'}}, 
            { CSSQuery           => {}, }
        );
    }

    if ( $config->{'framework'}->{'ConfigFileVersion'} < 4) {
        unshift (@{$config->{'framework'}->{'Plugins'}}, 
            { Prototypism        => {}, }
        );
    }

    if ( $config->{'framework'}->{'ConfigFileVersion'} < 5) {
        unshift (@{$config->{'framework'}->{'Plugins'}},
            { Compat        => {}, }
        );

        push (@{$config->{'framework'}->{'Plugins'}},
            { Deflater      => {}, }
        );
    }

    return $config;
}

sub defaults {
    my $self = shift;
    return {
        framework => {
            ConfigFileVersion => '1',
            L10N => {
                DefaultPoDir => Jifty::Util->share_root . '/po',
            },
            Web => {
                DefaultStaticRoot => Jifty::Util->share_root . '/web/static',
                DefaultTemplateRoot => Jifty::Util->share_root . '/web/templates',
                SessionCookieName => 'JIFTY_SID_$PORT',
            },
            CAS => {
                BaseClass => 'Jifty::CAS::Store',
                Memcached => {
                    servers     => [ '127.0.0.1:11211' ],
                    debug       => 0,
                    namespace   => $self->framework('ApplicationName').":",
                    compress_threshold => 10240,
                },
                MemcachedFallback => 1,
            },
        }
    };

}

1;