7. Shipping it

Before heat reaches its users: a complete help, colours, a man page, and completion for their shell.

call cli%init(progname    = 'heat',                                                        &
              version     = 'v1.0',                                                        &
              description = 'Solve the 2D heat equation on a square plate',               &
              authors     = 'The heat team',                                               &
              license     = 'MIT',                                                         &
              examples    = ['heat --nx 128 run         ',                                 &
                             'heat run --cfl 0.4        ',                                 &
                             'heat --install-completion '],                                &
              epilog      = 'Report bugs at https://example.org/heat/issues',              &
              error_color = 'red', error_style='bold_on',                                  &
              man_option  = .true.,                                                        & ! --man
              completion_options = .true.)                                                   ! --show/--install-completion

call cli%add(switch='--nx', help='Cells along each direction', required=.false., act='store', def='64', metavar='N', &
             help_color='cyan', help_style='bold_on')
call cli%add(switch='--scheme', help='Time scheme', required=.false., act='store', def='fe', choices='fe,cn', &
             help_color='cyan', help_style='bold_on')
call cli%add_group(group='run', description='Run a simulation')
call cli%add(group='run', switch='--cfl', help='CFL number', required=.false., act='store', def='0.25')

$ heat --help
usage: heat [--nx N] [--scheme value] [--help] [--markdown] [--version] [--man] [--show-completion [SHELL]] [--install-completion [SHELL]] {run} ...

Solve the 2D heat equation on a square plate

Optional switches:
  --nx N
      default value 64
      Cells along each direction
  --scheme value
      choices: fe, cn
      default value fe
      Time scheme
  --help, -h
      Print this help message
  --markdown, -md
      Save this help message in a Markdown file
  --version, -v
      Print version
  --man
      Save this help message as a man page
  --show-completion [SHELL]
      choices: bash, zsh, fish, powershell
      Print the completion script of SHELL (default: $SHELL)
  --install-completion [SHELL]
      choices: bash, zsh, fish, powershell
      Install the completion script of SHELL (default: $SHELL) in $HOME

Commands:
  run
      Run a simulation

For more detailed commands help try:
  heat run -h,--help

Examples:
  heat --nx 128 run
  heat run --cfl 0.4
  heat --install-completion

Report bugs at https://example.org/heat/issues

Errors and warnings get the colour of error_color/error_style:

$ heat --nxx 10
heat: error: switch "--nxx" is unknown! Did you mean "--nx"?

Try 'heat --help' for help.
[exit status 1]

Man page and Markdown

man_option=.true. adds --man, which writes heat.1; the builtin --markdown writes heat.md:

$ heat --man && head -n 8 heat.1
.TH heat "1" "<month> <year>" "version v1.0" "heat Manual"
.SH NAME
heat - manual page for heat version v1.0
.SH SYNOPSIS
.B heat
[--nx N] [--scheme value] [--help] [--markdown] [--version] [--man] [--show-completion [SHELL]] [--install-completion [SHELL]] {run} ...
.SH DESCRIPTION
Solve the 2D heat equation on a square plate

$ heat --markdown && head -n 20 heat.md
# heat

Manual page for `heat` version v1.0

`heat [--nx N] [--scheme value] [--help] [--markdown] [--version] [--man] [--show-completion [SHELL]] [--install-completion [SHELL]] {run} ...`

<month> <year>

### Short description

Solve the 2D heat equation on a square plate

### Command line options:

Optional switches:  

* `--nx N`    
    default value 64  
    Cells along each direction

Shell completion

completion_options=.true. adds --show-completion and --install-completion. The program prints its own completion script for bash, zsh, fish or PowerShell, or installs it for the user's shell:

$ heat --show-completion bash | head -n 12
#!/usr/bin/env bash
_heat_completion()
{
  local cur prev group w i start skip used words
  cur=${COMP_WORDS[COMP_CWORD]}
  prev=${COMP_WORDS[COMP_CWORD - 1]}
  start=1
  group=""
  skip=0
  for ((i=1; i<COMP_CWORD; i++)); do
    w=${COMP_WORDS[i]}
    if [ $skip -gt 0 ] ; then

$ heat --install-completion bash
completion script installed in "/home/user/.heat-completion.bash", loaded by "/home/user/.bashrc"

After a new shell, heat --sch<TAB> completes --scheme, and heat --scheme <TAB> offers fe cn. The same scripts can be written by the program itself (save_bash_completion, ...: see Output Formats), for a package.

What you learned

Examples, epilog, colours, --man, --markdown, --show-completion, --install-completion. Reference: Output Formats.

Next: 8. Testing the command line.