# 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 ' \ --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 ' \ --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.