Write engine specific vars with defaults as comments.

This is in `git init`. Added the `add_comment()` method to Config to make this possible (see also bestpractical/config-gitlike#4).

Changes

@@ -3,6 +3,9 @@ Revision history for Perl extension App::Sqitch
 0.12
      - Added `--local` option to `sqitch config`.
      - Renamed `project_file()` to `--local_file()` in App::Sqitch::Config.
+     - `sqitch init` now writes engine config settings with default values to
+       the configuration file. This makes it easier for folks to get started
+       editing it.
 
 0.11  2012-04-27T06:44:54Z
      - Implemented `init` command.

lib/App/Sqitch/Command/init.pm

@@ -79,6 +79,9 @@ sub write_config {
         # Write out the core.$engine section.
         my $ekey = 'core.' . $engine->name;
         my %config_vars = $engine->config_vars;
+        my $emeta       = $engine->meta;
+        my @comments;
+
         while (my ($key, $type) = each %config_vars) {
             # Was it passed as an option?
             if (my $attr = $meta->find_attribute_by_name($key)) {
@@ -93,9 +96,29 @@ sub write_config {
                         filename => $file,
                         multiple => $multiple,
                     );
+                    # We're good on this one.
+                    next;
                 }
             }
+
+            # No value, but add it as a comment.
+            if (my $attr = $emeta->find_attribute_by_name($key)) {
+                # Add it as a comment, possibly with a default.
+                my $def = $attr->default($engine);
+                $def = '' unless defined $def;
+                push @comments => "\t$key = $def";
+            } else {
+                # Add it as a comment, but we don't know of a default.
+                push @comments => "\t$key = ";
+            }
         }
+
+        # Emit the comments.
+        $config->add_comment(
+            filename => $file,
+            indented => 1,
+            comment  => join "\n" => @comments,
+        ) if @comments;
     }
 
     $self->info("Created $file");

lib/App/Sqitch/Config.pm

@@ -53,6 +53,33 @@ sub get_section {
     };
 }
 
+# Remove once https://github.com/bestpractical/config-gitlike/pull/4 is merged
+# and released.
+sub add_comment {
+    my $self = shift;
+    my (%args) = (
+        comment     => undef,
+        filename    => undef,
+        indented    => undef,
+        semicolon   => undef,
+        @_
+    );
+
+    my $filename = $args{filename} or die "No filename passed to add_comment()";
+    die "No comment to add\n" unless defined $args{comment};
+
+    # Comment, preserving leading whitespace.
+    my $chars = $args{indented} ? '[[:blank:]]*' : '';
+    my $char  = $args{semicolon} ? ';' : '#';
+    (my $comment = $args{comment}) =~ s/^($chars)/$1$char /mg;
+    $comment .= "\n" if $comment !~ /\n\z/;
+
+    my $c = $self->_read_config($filename);
+    $c = '' unless defined $c;
+
+    return $self->_write_config( $filename, $c . $comment );
+}
+
 __PACKAGE__->meta->make_immutable;
 no Moose;
 
@@ -113,6 +140,10 @@ An alias for C<local_file()> for use by the parent class.
 Returns a hash reference containing only the keys within the specified
 section or subsection.
 
+=head3 C<add_comment>
+
+Adds a comment to the configuration file.
+
 =head1 See Also
 
 =over

t/init.t

@@ -4,13 +4,14 @@ use strict;
 use warnings;
 use v5.10.1;
 use utf8;
-use Test::More tests => 52;
+use Test::More tests => 55;
 #use Test::More 'no_plan';
 use App::Sqitch;
 use Path::Class;
 use Test::Dir;
 use Test::File qw(file_not_exists_ok file_exists_ok);
 use Test::Exception;
+use Test::File::Contents;
 use File::Path qw(remove_tree make_path);
 use lib 't/lib';
 use MockCommand;
@@ -189,6 +190,9 @@ is_deeply read_config $conf_file, {
     'core.sqlite.db_name' => 'my.db',
 }, 'The configuration should have been written with sqlite values';
 
+file_contents_like $conf_file, qr/^\t# sqitch_prefix = sqitch\n/m,
+    'sqitch_prefix should be included in a comment';
+
 ##############################################################################
 # Now get it to write core.pg stuff.
 unlink $conf_file;
@@ -216,3 +220,8 @@ is_deeply read_config $conf_file, {
     'core.pg.host'     => 'banana',
     'core.pg.port'     => 93453,
 }, 'The configuration should have been written with pg values';
+
+file_contents_like $conf_file, qr/^\t# sqitch_schema = sqitch\n/m,
+    'sqitch_schema should be included in a comment';
+file_contents_like $conf_file, qr/^\t# password = \n/m,
+    'password should be included in a comment';