Add debugging when KELP_DEBUG is present

Changes

@@ -24,6 +24,7 @@
             - Fixed ::Null modules containing testing behavior - now they really do nothing
             - Repeatedly fetching parameters from json request with the param method is now much faster
             - Kelp::Module::Logger now sorts keys in Data::Dumper output
+            - Kelp can now be debugged using KELP_DEBUG environmental variable
             - Performance of accessors and request/response building was improved
             - Documentation was vastly improved
 

lib/Kelp.pm

@@ -51,15 +51,21 @@ sub new
 {
     my $self = shift->SUPER::new(@_);
 
+    Kelp::Base::_DEBUG(1 => 'Loading essential modules...');
+
     # Always load these modules, but allow client to override
     $self->_load_config();
     $self->_load_routes();
 
+    Kelp::Base::_DEBUG(1 => 'Loading modules from config...');
+
     # Load the modules from the config
     if (defined(my $modules = $self->config('modules'))) {
         $self->load_module($_) for (@$modules);
     }
 
+    Kelp::Base::_DEBUG(1 => 'Calling build method...');
+
     $self->build();
     return $self;
 }
@@ -104,6 +110,8 @@ sub _load_config
 {
     my $self = shift;
     $self->load_module($self->config_module, extra => $self->__config);
+
+    Kelp::Base::_DEBUG(config => 'Merged configuration: ', $self->config_hash);
 }
 
 sub _load_routes
@@ -146,6 +154,8 @@ sub load_module
         $args_from_config = $self->config("modules_init.$name") // {};
     }
 
+    Kelp::Base::_DEBUG(modules => "Loading $class module with args: ", {%$args_from_config, %args});
+
     $module->build(%$args_from_config, %args);
     return $module;
 }
@@ -205,6 +215,8 @@ sub run
     my $self = shift;
     my $app = sub { $self->psgi(@_) };
 
+    Kelp::Base::_DEBUG(1 => 'Running the application...');
+
     # Add middleware
     if (defined(my $middleware = $self->config('middleware'))) {
         for my $class (@$middleware) {
@@ -216,6 +228,9 @@ sub run
 
             my $mw = Plack::Util::load_class($class, 'Plack::Middleware');
             my $args = $self->config("middleware_init.$class") // {};
+
+            Kelp::Base::_DEBUG(modules => "Wrapping app in $mw middleware with args: ", $args);
+
             $app = $mw->wrap($app, %$args);
         }
     }

lib/Kelp/Base.pm

@@ -4,8 +4,24 @@ use strict ();
 use warnings ();
 use feature ();
 use Carp;
+use Data::Dumper ();
 use namespace::autoclean ();
 
+sub _DEBUG
+{
+    my ($stage, @messages) = @_;
+    my $env = $ENV{KELP_DEBUG};
+    return if !$env;
+    return if !grep { lc $env eq $_ } '1', 'all', lc $stage;
+
+    local $Data::Dumper::Sortkeys = 1;
+    my $message = join ' ', map {
+        ref $_ ? Data::Dumper::Dumper($_) : $_
+    } @messages;
+
+    print "DEBUG: $message\n";
+}
+
 sub import
 {
     my $class = shift;

lib/Kelp/Manual.pod

@@ -856,6 +856,33 @@ You no longer have to prefix destinations with the base controller class name.
 
 =head1 NEXT STEPS
 
+=head2 Debugging
+
+Kelp's configuration and building process can be easily debugged by setting
+C<KELP_DEBUG> environmental variable. These debug messages all go to C<STDOUT>.
+
+=over
+
+=item
+
+If you set it to C<modules>, Kelp will print a message on every module load and every
+middleware load.
+
+=item
+
+If you set it to C<config>, Kelp will print its full configuration.
+
+=item
+
+If you set it to C<routes>, Kelp router will print every route which is being added to the system.
+
+=item
+
+You can also set it to C<1> or C<all>, which will print all of the above plus some
+messages notifying the current state application building process.
+
+=back
+
 =head2 Testing
 
 Kelp provides a test class called C<Kelp::Test>. It is object oriented, and all

lib/Kelp/Routes.pm

@@ -34,6 +34,9 @@ sub add
     $parent = {} if !$parent || ref $parent ne 'HASH';
 
     my $route = $self->_parse_route($parent, $pattern, $descr);
+
+    Kelp::Base::_DEBUG(routes => 'Added route: ', $route);
+
     return $self->_build_location($route);
 }