[Catalyst-commits] r10153 - in trunk/Catalyst-Plugin-ConfigLoader: . lib/Catalyst/Plugin lib/Catalyst/Plugin/ConfigLoader

[t0m at dev.catalyst.perl.org]

Author: t0m
Date: 2009-05-14 09:22:44 +0000 (Thu, 14 May 2009)
New Revision: 10153

Modified:
   trunk/Catalyst-Plugin-ConfigLoader/Changes
   trunk/Catalyst-Plugin-ConfigLoader/lib/Catalyst/Plugin/ConfigLoader.pm
   trunk/Catalyst-Plugin-ConfigLoader/lib/Catalyst/Plugin/ConfigLoader/Manual.pod
Log:
Explain MYAPP_LOCAL_CONFIG_SUFFIX etc much more clearly, patch from mailing list

Modified: trunk/Catalyst-Plugin-ConfigLoader/Changes
===================================================================
--- trunk/Catalyst-Plugin-ConfigLoader/Changes	2009-05-14 08:25:54 UTC (rev 10152)
+++ trunk/Catalyst-Plugin-ConfigLoader/Changes	2009-05-14 09:22:44 UTC (rev 10153)
@@ -1,6 +1,8 @@
 Revision history for Perl extension Catalyst::Plugin::ConfigLoader.
 
 0.24  XXX
+    - Document CATALYST_CONFIG_LOCAL_SUFFIX and MYAPP_LOCAL_CONFIG_SUFFIX
+      much better (Louis Erickson)
     - Fix so that having CATALYST_CONFIG_LOCAL_SUFFIX set in $ENV{} doesn't
       cause the tests to break.
 

Modified: trunk/Catalyst-Plugin-ConfigLoader/lib/Catalyst/Plugin/ConfigLoader/Manual.pod
===================================================================
--- trunk/Catalyst-Plugin-ConfigLoader/lib/Catalyst/Plugin/ConfigLoader/Manual.pod	2009-05-14 08:25:54 UTC (rev 10152)
+++ trunk/Catalyst-Plugin-ConfigLoader/lib/Catalyst/Plugin/ConfigLoader/Manual.pod	2009-05-14 09:22:44 UTC (rev 10153)
@@ -187,5 +187,39 @@
         }
     } );
 
+=head2 Using a local configuration file
+
+When ConfigLoader reads configurations, it starts by reading the configuration
+file for C<myapp> with one of the supported extensions as listed
+L<above|/Config Formats>.
+
+For example, A L<Config::General> config file is C<myapp.conf>.
+
+If a configuration file called C<myapp_local> exists with one of the supported
+file extensions, it will also be read, and values from that file will
+override values from the main config file.
+
+A L<Config::General> local configuration file would be called
+C<myapp_local.conf>.
+
+The C<local> suffix can be changed.  See
+L<Catalyst::Plugin::ConfigLoader/get_config_local_suffix> for the details of
+how.
+
+This is useful because it allows different people or environments to have
+different configuration files.  A project with three developers,
+I<Tom>, I<Dick>, and I<Harry> as well as a production environment can have
+a C<myapp_tom.conf>, a C<myapp_dick.conf>, a C<myapp_harry.conf>, and a
+C<myapp_production.conf>.
+
+Each developer, and the web server, would set the environment variable
+to load their proper configuration file.  All of the configurations can
+be stored properly in source control.
+
+If there is no C<myapp.local>, and the individual configuration files contain
+something required to start the application, such as the Model's data source
+definition, the applicaton won't start unless the environment variable
+is set properly.
+
 =cut
 

Modified: trunk/Catalyst-Plugin-ConfigLoader/lib/Catalyst/Plugin/ConfigLoader.pm
===================================================================
--- trunk/Catalyst-Plugin-ConfigLoader/lib/Catalyst/Plugin/ConfigLoader.pm	2009-05-14 08:25:54 UTC (rev 10152)
+++ trunk/Catalyst-Plugin-ConfigLoader/lib/Catalyst/Plugin/ConfigLoader.pm	2009-05-14 09:22:44 UTC (rev 10153)
@@ -53,7 +53,9 @@
 
 To support the distinction between development and production environments,
 this module will also attemp to load a local config (e.g. myapp_local.yaml)
-which will override any duplicate settings.
+which will override any duplicate settings.  See
+L<get_config_local_suffix|/get_config_local_suffix>
+for details on how this is configured.
 
 =head1 METHODS
 
@@ -194,7 +196,8 @@
 =head2 get_config_local_suffix
 
 Determines the suffix of files used to override the main config. By default
-this value is C<local>, but it can be specified in the following order of preference:
+this value is C<local>, which will load C<myapp_local.conf>.  The suffix can
+be specified in the following order of preference:
 
 =over 4
 
@@ -206,6 +209,13 @@
 
 =back
 
+The first one of these values found replaces the default of C<local> in the
+name of the local config file to be loaded.
+
+For example, if C< $ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }> is set to C<testing>,
+ConfigLoader will try and load C<myapp_testing.conf> instead of
+C<myapp_local.conf>.
+
 =cut
 
 sub get_config_local_suffix {