4. Commands

heat grows three jobs: run a simulation, post-process its results, print info. Each becomes a command, with its own options and its own help, as in git commit or docker run.

! the top level: options before any command
call cli%add(switch='--threads', help='OpenMP threads', required=.false., act='store', def='1')
! the commands
call cli%add_group(group='run', aliases='r', description='Run a simulation')
call cli%add_group(group='post', aliases='p', description='Post-process the results')
call cli%add_group(group='info', description='Print the build information')
! the options of each command
call cli%add(group='run', switch='--nx', help='Cells along each direction', required=.false., act='store', def='64')
call cli%add(group='run', switch='--cfl', help='CFL number', required=.false., act='store', def='0.25')
call cli%add(group='post', switch='--format', help='Output format', required=.false., act='store', def='vtk', &
             choices='vtk,csv')
! one definition, copied into two commands: each copy has its own value
call cli%add(switch='--verbose', switch_ab='-v', help='Verbosity (repeatable)', required=.false., act='count')
call cli%copy_options(to_group='run', switches='--verbose')
call cli%copy_options(to_group='post', switches='--verbose')

• add_group defines a command; aliases gives it shorter names (heat r is heat run).
• add(group=...) gives a command its options; an option without group belongs to the top level and goes before any command name.
• copy_options copies a definition into a command: run and post both get a --verbose, each with its own value.

The arguments after a command name belong to that command, up to the next command name, so one command line can call several commands. The program asks which ones were called:

! several commands can be called on one command line: one block each
if (cli%run_command('run')) call run
if (cli%run_command('post')) call post
if (cli%run_command('info')) print '(A)', 'heat v0.4, built with FLAP'

subroutine run
!< The run command.
integer :: nx, verbose, e
real(8) :: cfl

call cli%get(group='run', switch='--nx', val=nx, error=e)
call cli%get(group='run', switch='--cfl', val=cfl, error=e)
call cli%get(group='run', switch='--verbose', val=verbose, error=e)
print '(A,I0,A,F4.2,A,I0)', 'run: nx ', nx, ', cfl ', cfl, ', verbosity ', verbose
endsubroutine run

$ heat --threads 4 run --nx 128 -v post --format csv
heat on 4 thread(s)
run: nx 128, cfl 0.25, verbosity 1
post: format csv, verbosity 0

$ heat r
heat on 1 thread(s)
run: nx 64, cfl 0.25, verbosity 0

$ heat info
heat on 1 thread(s)
heat v0.4, built with FLAP

The top-level help lists the commands; each command has its own help:

$ heat --help
usage: heat [--threads value] [--verbose]... [--help] [--markdown] [--version] {run,post,info} ...

Solve the 2D heat equation on a square plate

Optional switches:
  --threads value
      default value 1
      OpenMP threads
  --verbose, -v
      default value 0
      Verbosity (repeatable)
  --help, -h
      Print this help message
  --markdown, -md
      Save this help message in a Markdown file
  --version
      Print version

Commands:
  run, r
      Run a simulation
  post, p
      Post-process the results
  info
      Print the build information

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

$ heat run --help
usage: heat run [--nx value] [--cfl value] [--verbose]... [--help] [--markdown] [--version]

Run a simulation

Optional switches:
  --nx value
      default value 64
      Cells along each direction
  --cfl value
      default value 0.25
      CFL number
  --verbose, -v
      default value 0
      Verbosity (repeatable)
  --help, -h
      Print this help message
  --markdown, -md
      Save this help message in a Markdown file
  --version
      Print version

What you learned

Commands, aliases, options shared between commands, dispatch with run_command, several commands on one line. Reference: Subcommands.

Next: 5. Values from everywhere.