=pod

=head1 NAME

Dist::Starter - A command-line utility for rendering Perl project templates

=head1 DESCRIPTION

This is an B<alpha> release. It is yet another starter kit implementation for
a Perl project (distribution). It provides the C<diststarter> script as a CLI.
The script has a single mandatory argument that is the C<distname>. If you
provide a module name, this will be normalized to the corresponding C<distname>
too. The following table lists the options/flags of the script:

  Option | Placeholder          | Default                       | Example
  -------+----------------------+-------------------------------+--------------------
  T:     | n/a                  | 'templates/perl-dist-eummcpf' |
  V      | n/a                  | not set (version info)        |
  h      | n/a                  | not set (usage info)          |
  n      | n/a                  | not set                       |
  o:     | n/a                  | current directory             |
  A:     | abstract             | 'The great new Foo::Bar::Baz' |
  G:     | git_base_url         |                               |
  I:     | initial_version      | 'v0.1.0'                      |
  L:     | license              | 'perl_5'                      |
  M:     | min_perl_version     | '5.010000'                    |
  S=     | share.type           |                               |
         | share.dir            |                               |
         | share.MY             |                               |
         | share.Makefile       |                               |
         | share.deps.configure |                               |
         | share.deps.runtime   |                               |
  a:     | author.from          | FROM_GECOS                    |
         | author.full_name     | FROM_GECOS                    |
         | author.email         | FROM_GECOS, fallback EMAIL    |
  n/a    | distname             |                               | Foo-Bar-Baz
  n/a    | main_module          |                               | Foo::Bar::Baz
  n/a    | main_module_file     |                               | lib/Foo/Bar/Baz.pm
  n/a    | main_module_podfile  |                               | lib/Foo/Bar/Baz.pod

The options that have a "Placeholder" value control the scaffolding. It is
recommended to overwrite the "Default" of some of them in your run-control
file. Example:

  cat ${XDG_CONFIG_HOME}/diststarterrc
  G https://github.com/sitcom
  M 5.042003
  a FROM_GIT

The C<-a> option allows the special values FROM_GECOS (the default), FROM_GIT,
and FROM_ENV. If you use FROM_GIT, the author information is taken from the
C<user.name> and C<user.email> git configuration attributes. If you use
FROM_ENV, the author information is taken from the environment variables
FULL_NAME and EMAIL. The default is to take the author information (at
least its full name) from the GECOS string and if the email extraction
isn't possible to fall back to the EMAIL environment variable. The author
information has the format

  Fred Flintstone <fred.flintstone@example.com> # with email
  Fred Flintstone                               # without email

The value of the C<-T> option specifies a directory that includes the template
definition. The default refers to a directory shared by this distribution.

The value of the C<-o> option specifies a directory where the generated project
should be created. The default refers to the current directory. The special
value TEMP_DIR can be used to create the project in a temporary directory.

If you set the C<-n> (dry-run) flag, the project will not be created but
the so-called C<context> will be printed to standard output. The context is
a YAML document that contains the placeholder names and their values.

=head1 TODO

=over 2

=item *

Explain how to create a new template definition

=item *

Reorganize documentation

=item *

Add script (C<-s>) option

=item *

Provide option to customize the initial version

=item *

Validate license string allowing only values contained in the
L<CPAN::Meta::Spec/license> list

=back

=head1 SEE ALSO

=over 2

=item *

L<Cookiecutter|https://cookiecutter.readthedocs.io/en/stable/README.html>

=item *

L<Copier|https://copier.readthedocs.io/en/stable/>

=item *

L<App::Starter>

=item *

L<CPAN::Maker>

=item *

L<Distribution::Cooker>

=item *

L<Module::New>

=item *

L<Module::Starter>

=back

=head1 AUTHOR

Sven Willenbuecher <sven.willenbuecher@gmx.de>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Sven Willenbuecher.

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

=cut
