# NAME

App::Skeletor - Bootstrap a new project from a shared template

# SYNOPSIS

    skeletor --template Skeltor::Template::Example \
      --as Local::MyApp \
      --directory ~/new_projects \
      --author 'John Napiorkowski <jjnapiork@cpan.org>' \
      --year 2015

# DESCRIPTION

When initially setting up a project (like a website build using [Catalyst](https://metacpan.org/pod/Catalyst) or
an application that uses [DBIx::Class](https://metacpan.org/pod/DBIx::Class)) there is often a number of boilerplate
files and directories you need to create before beginning the true work of
application building.  Additionally, during general development certain types
of repeated tasks may occur which would benefit from automation, such as adding
new controllers to [Catalyst](https://metacpan.org/pod/Catalyst) or new tables in [DBIx::Class](https://metacpan.org/pod/DBIx::Class).  For these types
of activities you may find having a code generator speeds up some of the grunt
work and promotes uniformity of design.  [App::Skeltor](https://metacpan.org/pod/App::Skeltor) is such a code generator.

The core design is simple.  You install [App::Skeltor](https://metacpan.org/pod/App::Skeltor) and any of the code
patterns on CPAN that you wish to derive projects from (typically using the
[Skeltor::Template::\*](https://metacpan.org/pod/Skeltor::Template::*) namespace, but you can use any namespace, and project
patterns can be attached to any arbitirary CPAN module).  You then can use the
'skeletor' commandline application to generate code into a target directory,
using expansion variables to customize how the directories and files are created.

For example if you wish to build a new project called `Local::MyApp` which is
based off the [Skeletor::Template::Example](https://metacpan.org/pod/Skeletor::Template::Example) project, you'd install that distribution
(via [cpanminus](https://metacpan.org/pod/cpanminus) or whichever tool you prefer) and then type something like the
following:

    skeletor --template Skeltor::Template::Example \
      --as Local::MyApp \
      --directory ~/new_projects \
      --author 'John Napiorkowski <jjnapiork@cpan.org>' \
      --year 2015

This would create a new project which consists of directories and files that have been
generated and customized based on the commandline options given.

**NOTE** `directory` and `year` are optional, and default to the current working directory
and current year respectively.  Some project templates may define additional configuration
options, you should review the documentation.

Other similar boilerplate code generators exist on CPAN.  For example [Catalyst::Devel](https://metacpan.org/pod/Catalyst::Devel) has a
commandline tool for creating a simple [Catalyst](https://metacpan.org/pod/Catalyst) project.  [Dancer2](https://metacpan.org/pod/Dancer2), [Mojolicious](https://metacpan.org/pod/Mojolicious)
also have dedicated project builders.  [App::Skeletor](https://metacpan.org/pod/App::Skeletor) differs from those
approaches in that it is detached from a particular project domain and thus can
be more generically useful.  This should give the community the chance for people
to suggest their favorite approach to bootstrapping a project without forcing people
to accept default options they don't like (current approach tends to be one size fits
no one).

When comparing [App::Skeletor](https://metacpan.org/pod/App::Skeletor) to similar generic code builders like [Dist::Zilla](https://metacpan.org/pod/Dist::Zilla)
minting profiles, the main different is that [App::Skeletor](https://metacpan.org/pod/App::Skeletor) is dependency manager
agnostic (doesn't require [Dist::Zilla](https://metacpan.org/pod/Dist::Zilla)).  I think its also a lot more simple than
a minting profile.

[App::Skeletor](https://metacpan.org/pod/App::Skeletor) is probably more comparable with tools like [Module::Starter](https://metacpan.org/pod/Module::Starter) which
at this time are more mature tools.  If [App::Skeltor](https://metacpan.org/pod/App::Skeltor) has tool many rough edges you
may wish to take a look.  At this point the main comparison is that I think the way
a project skelton is created and organized is significantly easier to understand (famous
last words I know :) ).  The a later section covers this topic, and you may wish to review
[Module::Starter](https://metacpan.org/pod/Module::Starter), [Module::Setup](https://metacpan.org/pod/Module::Setup) and [App::Starter](https://metacpan.org/pod/App::Starter) for points of comparison.
([App::Skeletor](https://metacpan.org/pod/App::Skeletor) is probably most like [App::Starter](https://metacpan.org/pod/App::Starter) although I think [App::Skeletor](https://metacpan.org/pod/App::Skeletor)
is more simple / less features).

# ARGUMENTS

The following configuration options are available, which are used as template
variables and directory/file path expansions.

## namespace

## as

The new project Perl namespace, as you might use it in a 'package' declaration.
For example "Local::MyApp".  Use this to declare the base package for your new
project.

## name

Derived from ["as"](#as).  We substitute '::' for '-' to create a project
'name' that is normalized to the CPAN specification.  For example 'Local-MyApp'

## name\_lowercase

## name\_lc

Same as ["name"](#name) but using lowercased characters via 'lc'.  For example 'local-myapp'.

## name\_lowercase\_underscore

## name\_lc\_underscore

Same as [name](https://metacpan.org/pod/name) but using lowercase characters via 'lc' and substituting all
'-' characters with '\_'.  For example 'local\_myapp'.

## project\_fullpath

Given a ["as"](#as) like "Local::My::App":

When used as an expansion for a directory expands to a nest of
directories such as "Local/My/App".  Directories will be created as needed.

When used as an expansion for a filename, expands directories as needed and
creates a terminal file as needed such as "Local/My/App". Extensions are
preserved, for example "${namespace\_fullpath}.pm" becomes "Local/My/App.pm".

When used as a variable in a template, resolves to a [Path::Tiny](https://metacpan.org/pod/Path::Tiny) object that
points to the directory+filename as already described.

## author

Used in templates, set to the project author.

## year

Year information for setting project copyright, etc.  Default is current year.

# BUILDING A TEMPLATE

An [App::Skeletor](https://metacpan.org/pod/App::Skeletor) template is just a CPAN module under any namespace you like
(athough Skeletor::Template:: is not a terrible place to put one to make it
easier for people to find) with a share/skel directory which should contain
asset files (files copied to a new project without alteration), project templates
(files that are copied to a new project but are first processed thru [Template::Tiny](https://metacpan.org/pod/Template::Tiny)
to customize them) and directories.  Directory names may also contain expansion
variables in order to customize directory layout.

There is a reasonable complex example on CPAN under the namespace
[Skeletor::Template::Example](https://metacpan.org/pod/Skeletor::Template::Example) which you may refer to as a somewhat complexe
template that includes all the mentioned types of data.  You may find reviewing
the example to be a faster way to understand how to make your own project templates.

Here is a very simple template with explanation to get you started.  The example
namespace given is mythical and does not exist on CPAN.  In this example a path
ending in '/' indicates a directory.

    Local-Skeltor-Template-MyTemplate/
      Makefile.PL
      lib/
        Local/
          Skeletor/
            Template/
              MyTemplate.pm
      share/
        skel/
          $name/
            dist.ini.ttt
            lib/
              ${project_fullpath}.pm.ttt
              $project_fullpath/
                Web.pm.ttt
            t/
              basic.t.ttt
            share/
              image.jpg
              docs.txt

So first of all you should note that the template is just a normal CPAN module that
declares its installation process and has a file (in this case under
'lib/Local/Skeletor/Template/MyTemplate.pm') that should be used to describe what
the skeleton does.  Also note that you may include skeleton template files under
any CPAN module you wish, it doesn't need to be stand alone.

The main work happens under 'share/skel/' which is the root directory that
[App::Skeletor](https://metacpan.org/pod/App::Skeletor) uses when finding a template pattern.  The way it works is
that we traverse the filesystem recursively and copy directories and files from
the project template share/skel/ to the target directory, performing any
template expansions as needed.  Template variable are defined above.  We
expand directories and files by matching a template variable in the path
using a similar approach as we do variable interpolation in a string.  for
example a directory called "$name" would expand to the project name variable
(which is derived from the ["as"](#as) commandline option.

In the case where you need to combine a template variable with other characters
you may enclose it with parenthesis, as in the example "${project\_fullpath}.pm.ttt".

Any file ending in '.ttt' is considered a template and is processed via [Template::Tiny](https://metacpan.org/pod/Template::Tiny)
expanding variables as described in the previous section.

# AUTHOR

John Napiorkowski [email:jjnapiork@cpan.org](email:jjnapiork@cpan.org)

# COPYRIGHT & LICENSE

Copyright 2015, John Napiorkowski [email:jjnapiork@cpan.org](email:jjnapiork@cpan.org)

This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
