= App::Cpan6
:toc: preamble

`App::Cpan6` is a tool to assist in creating and sharing
https://www.cpan.org/[CPAN] modules.

== Commands
To do it's job, `cpan6` has a couple of tools ready for you. Use any of the
following subcommands to use them.

=== depend
Indicate your module depends on another module. Unless disabled with
`--skip-install`, `cpan6` will try to install the module as well through `zef`.
Regardless of the `--skip-install` value, `cpan6` will update your `META6.json`
with the new dependency as well.

=== dist
`dist` creates a `.tar.gz` file you can upload to
https://pause.perl.org/[PAUSE].

=== new
Create a new module in the current directory. Cpan6 will ask you some questions,
and continue to perform the following steps:

- Create module directory skeleton
- Write `META6.json`
- Write `.editorconfig`
- If the `git` flag is enabled (which it is by default):
  - Initialize a git repository
  - Make an initial commit

=== pkg
The `pkg` command allows you to easily create packages for distributions. For
each type of package, there's a different subcommand.

==== ebuild
To create `ebuild` files, used by Gentoo and derivatives, you can make use of
the `ebuild` subcommand to `package`.

==== push
`push` is a short-hand to running `release`, `dist` and `upload`.

=== release
Create a new release for a module. This will bump the version number in
`META6.json`, commit it into git and create a tag with the version number.

=== touch
Using `touch` requires a subcommand. It will create a template file for your
module in the correct location, and update the `provides` key of your
`META6.json` as well.

==== bin
Create a new perl 6 script in the `bin` directory. The template will include a
shebang, version indicator and a `sub MAIN` to get you started.

==== lib
Create a new perl 6 module file in the `lib` directory. If subdirectories need
to be made, `cpan6` will take care of it. The template by default contains a
shebang and a version indicator. You can get an extended template by supplying
a `--type` argument to `cpan6`. Valid types are

- `class`, which will add an empty class with the correct name
- `unit`, which will add a unit module name

=== upload
Upload module tarballs to PAUSE. This will ask you to enter your PAUSE ID and
password. It will ask to save your PAUSE ID, so you wont have to enter it next
time.

== Configuration
To avoid having to repeat yourself too often, a number of configuration options
can be set in the configuration file. The format of the configuration file is
https://github.com/toml-lang/toml[TOML]. `cpan6` assumes some defaults, defined
in `App::Cpan6::Config`, which can all be overwritten in the configuration
file.

Currently, the configuration file is only searched in
`${HOME}/.config/cpan6.toml`. Additional search locations may be added later.

=== Example
This example configuration block describes a configuration file's contents with
all options defined, and set to their defaults.

[source,toml]
----
[cpan6]
# The directory to store newly created dists in. Set to "." to put them into
# the current working directory. If unset, "/home/user" will be substituted
# with the path to your $HOME.
distdir = "/home/user/.local/var/cpan6/dists"

[pause]
# Set this id to your own PAUSE ID. If it's unset, it will be asked when
# needed.
id = ""

# The new module options are always asked for, but the values set in the
# configuration file here will be used as defaults. This enables you to just
# hit enter a couple times.
[new-module]
# The real name of the author of the module.
author = ""

# The email address of the author of the module.
email = ""

# Which version of Perl 6 the module is going to be written against.
perl = "c"

# The license under which this module will be made available.
license = "GPL-3.0"

# The prefix given to the directory containing the module.
dir-prefix = "perl6-"
----

== Roadmap
- Make `new` also write a `.travis.yml`
- Add tests
- Clean up the codebase
- Release v1.0.0

== License
`App::Cpan6` is released under the GNU GPL, version 3 or later.