CatalystX::Starter - bootstrap a CPAN-able Catalyst component

CatalystX-Starter documentation Contained in the CatalystX-Starter distribution.

Index

Code Index:

NAME

Top

CatalystX::Starter - bootstrap a CPAN-able Catalyst component

SYNOPSIS

Top

Like module-starter, but sane:

  $ catalystx-starter 'Module::Name'
  $ cd Module-Name
  $ git init
  $ mv gitignore .gitignore
  $ git add .gitignore *
  $ git ci -m 'Start my component'

Then edit Changes and README to taste

  $ mg README
  $ mg Changes
  $ git ci -a -m 'update Changes and README'

Then you're ready to work:

  $ make test
  00load.............ok
  live...............ok
  All tests successful.

  $ prove --lib t/author # don't want users running these
  pod................ok
  pod-coverage.......ok
  All tests successful.

DESCRIPTION

Top

Recently, I've stopped using Module::Starter, because it generates way too much boilerplate and not enough of stuff I actually need. I find it easier to just start with nothing and manually write what I need.

CatalystX::Starter automates this minimalism for me. It will create everything you need to start developing a Catalyst component or plugin, but won't create useless crap that you just have to delete.

Here's what you get:

t/lib/TestApp

A live app that can be run from tests (including t/live-test.t). It also comes with the testapp_server.pl and testapp_test.pl, so you can try our your TestApp from the command line. Yay for never having to write this again.

So far, I've wasted more than an hour of my life typing this exact TestApp code in again and again. Now it's automatic. FINALLY.

Makefile.PL

Module::Install-based Makefile.PL with build_requires set up to run the default tests.

gitignore

Save yourself the effort of setting up a .gitignore. You can of course import this as svn:ignore or .cvsignore. I use git, so that's what you get by default.

Note that you have to rename this yourself, because I want git to track it, not treat it as an ignore file.

MANIFEST.SKIP

A useful MANIFEST.SKIP that ignores stuff that make leaves lying around, and my .git directory.

Changes / README

No text in here. Change it to what you want it to look like.

lib/Your/Module.pm

Almost nothing:

   package Your::Module;
   use strict;
   use warnings;

   1;

Write the POD yourself. You're smart enough to remember that the sequence is NAME, SYNOPSIS, DESCRIPTION, METHODS, BUGS, AUTHOR, COPYRIGHT. If not... now you are :)

That's about it. Enjoy.

SEE ALSO

Top

catalyst.pl, for creating Catalyst applications.

Module::Starter, if you like deleting code more than writing it.

AUTHOR

Top

Jonathan Rockway <jrockway@cpan.org>.

COPYRIGHT

Top

I don't assert any copyright over the generated files. This module itself is copyright (c) 2007 Jonathan Rockway and is licensed under the same terms as Perl itself.

CatalystX-Starter documentation Contained in the CatalystX-Starter distribution. 
# Copyright (c) 2007 Jonathan Rockway <jrockway@cpan.org>

package CatalystX::Starter;
use strict;
use warnings;

our $VERSION = '0.07';

use File::ShareDir qw/module_dir/;
use File::Copy::Recursive qw/dircopy/;
use File::Slurp qw/read_file write_file/;
use File::pushd;

# don't use any of these subroutines.

sub _boilerplate {
    return module_dir('CatalystX::Starter');
}

sub _module2dist {
    my $module = shift;
    die("You seem to have passed a dist name, not a module name: $module\n")
        unless $module =~ /::/;
    $module =~ s/::/-/g;
    return $module;
}

sub _copy_files {
    my $dest = shift;
    my $src  = _boilerplate();
    dircopy($src, $dest) or die "Failed to install boilerplate: $!";
}

sub _fix_files {
    my ($module, $dir) = @_;
    
    opendir my $dh, $dir or die "Failed to opendir $dir: $!";
    my @paths = grep {!/^[.][.]?$/} readdir $dh 
      or die "Failed to read $dir: $!";

    my $p = pushd $dir;
    my @dirs  = grep { -d  } @paths;
    my @files = grep { !-d } @paths;

    # fix files
    {
        my $dist_name = $module;
        my $main_module_path = "lib/$module.pm";
        $dist_name =~ s/::/-/g;
        $main_module_path =~ s|::|/|g;

        foreach my $file (@files) {
            my $data = read_file($file);
            chmod 0644, $file;
            $data =~ s/\[% DIST_NAME %\]/$dist_name/g;
            $data =~ s/\[% MODULE %\]/$module/g;
            $data =~ s/\[% MAIN_MODULE_PATH %\]/$main_module_path/g;
            write_file($file, $data);
        }
    }
    # fix subdirs
    _fix_files($module, $_) for @dirs;
    closedir $dh;
    
    return;
}

sub _split_module {
    my $module = shift;
    return split /::/, $module;
}

sub _mk_module {
    my $module = shift;
    my $dist   = shift;
    
    my $d = pushd $dist;
    mkdir 'lib';
    die "Failed to create lib in $dist: $!" unless -d 'lib';

    chdir 'lib';
    my @path = _split_module($module);
    my $file = pop @path;
    foreach my $part (@path) {
        mkdir $part;
        die "Failed to mkdir $part: $!" if !-d $part;
        chdir $part;
    }
    
    my $data = <<"MOD"; # indented to prevent pod parser from parsing it
 package $module;
 use Moose;
 use namespace::autoclean;
 
 1;
 
 =head1 NAME
 
 $module - 
 
 =head1 DESCRIPTION
 
 =head1 METHODS
 
 =head1 BUGS
 
 =head1 AUTHOR
 
 =head1 COPYRIGHT & LICENSE

 Copyright 2009 the above author(s).
 
 This sofware is free software, and is licensed under the same terms as perl itself.
 
 =cut
 
MOD
    
    $data =~ s/^ //mg; # cleanup the leading space
    write_file("$file.pm",$data);
    return;
}

sub _go {
    my $module = shift;
    my $dist   = _module2dist($module);
    _copy_files($dist);
    _fix_files($module, $dist);
    _mk_module($module, $dist);
    return $dist;
}

1;

__END__