1. A first command line

heat starts with three numbers: the cells along each direction, the time steps and the CFL number. Every FLAP program follows the same four steps: initialise the command line interface, define the arguments, parse the command line, get the values.

program heat
!< Tutorial, chapter 1: a first command line.
use flap
implicit none
type(command_line_interface) :: cli   ! the command line interface
integer                      :: nx    ! cells along each direction
integer                      :: steps ! time steps
real(8)                      :: cfl   ! CFL number
integer                      :: error ! error code

! 1. initialise
call cli%init(progname='heat', version='v0.1', description='Solve the 2D heat equation on a square plate')
! 2. define
call cli%add(switch='--nx', help='Cells along each direction', required=.false., act='store', def='64')
call cli%add(switch='--steps', help='Time steps', required=.false., act='store', def='100')
call cli%add(switch='--cfl', help='CFL number', required=.false., act='store', def='0.25')
! 3. parse
call cli%parse(error=error)
if (error /= 0) stop 1, quiet=.true.
! 4. get
call cli%get(switch='--nx', val=nx, error=error)       ; if (error /= 0) stop 1, quiet=.true.
call cli%get(switch='--steps', val=steps, error=error) ; if (error /= 0) stop 1, quiet=.true.
call cli%get(switch='--cfl', val=cfl, error=error)     ; if (error /= 0) stop 1, quiet=.true.

print '(A,I0,A,I0,A,I0,A,F4.2)', 'heat: ', nx, 'x', nx, ' cells, ', steps, ' steps, cfl ', cfl
endprogram heat

• init names the program and describes it; version is what --version prints.
• add defines an option: its switch, a help line, whether it is required, the action (act='store': it stores the value that follows) and its default def, always a string.
• parse reads the command line and checks it. It returns an error code: 0 means success.
• get converts each value to the type of the variable you pass: an integer, a real(8), ... There is one get for every type and kind.

Running it

$ heat
heat: 64x64 cells, 100 steps, cfl 0.25

$ heat --nx 128 --steps=10
heat: 128x128 cells, 10 steps, cfl 0.25

A value follows its switch, or is attached to it with = (--steps=10).

Help and version for free

Every FLAP program has --help (-h), --version (-v) and --markdown (-md, the help as a Markdown file):

$ heat --help
usage: heat [--nx value] [--steps value] [--cfl value] [--help] [--markdown] [--version]

Solve the 2D heat equation on a square plate

Optional switches:
  --nx value
      default value 64
      Cells along each direction
  --steps value
      default value 100
      Time steps
  --cfl value
      default value 0.25
      CFL number
  --help, -h
      Print this help message
  --markdown, -md
      Save this help message in a Markdown file
  --version, -v
      Print version

$ heat --version
heat version v0.1

--help and --version end the program inside parse, with exit status 0: the code after parse never runs.

Errors

A mistake on the command line is reported by parse, with suggestions for a misspelled switch and a hint pointing to the help; a value that cannot be converted is reported by get:

$ heat --stesp 10
heat: error: switch "--stesp" is unknown! Did you mean "--steps"?

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

$ heat --nx many
heat: error: cannot convert "many" of option "--nx" to an integer!

[exit status 1]

FLAP prints the message and returns the error code; it never stops the program on an error. heat stops with exit status 1, so that a shell script or a batch system sees the failure.

What you learned

The four steps init, add, parse, get; the free builtins; error codes instead of crashes. Reference: Defining Arguments, Parsing & Getting Values.

Next: 2. Options of every kind.