🔮 Summoner

So many of our dreams at first seem impossible, then they seem improbable, and
then, when we summon the will, they soon become inevitable.

Christopher Reeve

Summoner is a tool for scaffolding fully configured batteries-included production Haskell projects.

Do you want to create a library that is to be uploaded to Hackage/Stackage, that builds with both Cabal and Stack and supports the latest three major GHC versions?
Or you are building a production application which uses a custom prelude and has CI with Travis Linux and AppVeyors Windows checks?
Summoner can help you do all that with minimal effort from you - it can even upload the project to GitHub if you wish!

By the way, Summoner operates as either CLI or TUI application, so you can choose what you’re more comfortable with and install only the required one.

To start summoning projects nothing additional is required. However, to tweak your settings further, you can use additional configuration settings.
There are several options you can use to set particular configurations for new projects (in increasing order of priority):

Default configuration file (~/.summoner.toml).

Explicitly specified configuration file by --file FILENAME option (used instead of the default one if specified).

Options that are stated by CLI arguments.

User input. It could be

TUI – User data specified in the window of summon-tui.

CLI – Interactively inputted answers during execution of the summon command (for the options that were not specified on previous steps).

Usage:
summon COMMAND
Set up your own Haskell project
Available commands:
new Create a new Haskell project
show Show available licenses or ghc versions
Available global options:
-h, --help Show this help text
-v, --version Show summoner's version

Usage:
summon new PROJECT_NAME [--ignore-config] [--no-upload] [--offline]
[-f|--file FILENAME]
[--cabal]
[--stack]
[--prelude-package PACKAGE_NAME]
[--prelude-module MODULE_NAME]
[with [OPTIONS]]
[without [OPTIONS]]
Available options:
-h, --help Show this help text
--ignore-config Ignore configuration file
--no-upload Do not upload to GitHub. Special case of the '--offline' flag.
--offline Offline mode: create project with 'All Rights Reserved' license
and without uploading to GitHub.
--cabal Cabal support for the project
--stack Stack support for the project
-f, --file FILENAME Path to the toml file with configurations. If not
specified '~/.summoner.toml' will be used if present
--prelude-package PACKAGE_NAME
Name for the package of the custom prelude to use in
the project
--prelude-module MODULE_NAME
Name for the module of the custom prelude to use in
the project
Available commands:
with Specify options to enable
without Specify options to disable
Available command options:
-h, --help Show this help text
-g, --github Github integration
-p, --private Create private GitHub repository
-c, --travis Travis CI integration
-w, --app-veyor AppVeyor CI integration
-l, --library Library target
-e, --exec Executable target
-t, --test Tests
-b, --benchmark Benchmarks

Usage:
summon show COMMAND
Show supported licenses or ghc versions
Available commands:
ghc Show available ghc versions
license Show available licenses
license [LICENSE_NAME] Show specific license text
Available options:
-h, --help Show this help text

For example, the following command preconfigures the project settings with the custom prelude relude, included library, executable, test stanzas (but without benchmarks), creates a private repository on GitHub with the Travis CI and AppVeyor CI integrated.

Section 1 – The main section where user inputs data or changes the configurations.

Section 2 – The structure of the project that is going to be created with the current configurations. This tree changes on-the-fly.

Section 3 – Hints, project status, or current errors in the configurations.

Section 4 – Useful hotkeys.

The TUI window opens with the pre-filled information received from a config file and command-line arguments. However, it’s possible to change any field as per your needs.

In the screenshot you can see that you’ll be given a few text fields to fill in or some checkboxes that represent boolean values of the configurations. To help you fill in the correct input, there are some ⓘ info messages in the Status section, which give additional details about the current field.

To help you navigate between the form fields here are the available hotkeys:

Key

Action

Esc

Abort summoner

Enter

If input is valid go to the Confirm window

Tab

Change the focus to the next active field

Shift + Tab

Change the focus to the previous active field

Space

Enable/disable current checkbox or radio button

Ctrl + d

Delete the input of the current text field

Ctrl + u

Delete the input of the current text field from the cursor position to the beginning

Ctrl + k

Delete the input of the current text field from the cursor position to the end

Ctrl + a

Move the cursor to the beginning of the current input field

Ctrl + e

Move the cursor to the end of the current input field

Up/Down

Scroll license list when focused

Note that the form should be valid in order to be able to go to the Confirm window. If there are some errors in the input, you could see details about these errors in the Status section of the form.

In CLI mode of operation Summoner asks about every project setting. Most of the questions contain a default value, so you can press Enter to choose the default value.
If some option is specified via a configuration file or CLI arguments, then the question is skipped and the predefined value is used.

If you’d like to take part in the development processes, here are a few things to keep in mind:

Summoner is a multi-package project which has two packages inside: summoner-cli and summoner-tui. We are supporting the same functionality in both of them, so, if it’s possible, you should add/change the code in both of the packages.

Changes

Changelog

1.2.0 — Nov 30, 2018

#199:
Add None license with no LICENSE file generation.
Add licenses short descriptions text during the interactive mode.
Patch summon show license command to show short description about
each license.

#197
Build with stack lts-12.20, and support GHC 8.4.4 in
project generation. Make GHC-8.4.4 the default one for generated project.