FLAP Documentation

Appearance

FLAPFortran command Line Arguments Parser

Describe your command line once, in pure Fortran 2018: FLAP parses it, reads the environment and the configuration files, checks every value, and writes the help, the errors, the man page and the shell completions.

Tutorial
Cookbook
Reference
API
View on GitHub
🧩

Every kind of argument

Options with abbreviations, positionals, flags and --x/--no-x pairs, counters (-vvv), repeatable options, optional values, inline --opt=value, value placeholders.

Defining arguments

🔢

Typed values, lists and maps

One get for every integer and real kind, logicals and strings; fixed-size lists, runtime-sized ones into allocatable arrays, KEY=VALUE maps.

Parsing & getting values

✅

Validation built in

Required options, choices, numeric ranges with open bounds or clamping, path checks, mutually exclusive sets, deprecation warnings: declared in the definition, checked for you.

Advanced features

💬

Errors that help

"Did you mean" suggestions, a hint line, the usage after an error, a named constant for every code, and your own errors printed in the same style.

Errors

🔀

Commands

git-style commands, each with its options and its help; aliases, option sets shared between commands, mutually exclusive commands, several commands on one command line.

Subcommands

🌱

Values from everywhere

Command line, environment variables (named or generated from a prefix), INI configuration files and defaults, in a fixed precedence; the source of every value reported, for reproducible runs.

Value sources

📄

Help, man page, Markdown

The help and the usage are generated from the definitions, with colours, examples and an epilog; --man and --markdown save the same content as files.

Output formats

⌨️

Shell completion

Completion scripts for bash, zsh, fish and PowerShell, which the program prints or installs by itself: --show-completion, --install-completion.

Shell completion

🧪

Testable command lines

Parse a string instead of the real command line, parse again, get statuses back instead of stops, send the messages to the units you choose.

Testing

🙋

Interactive menus

An opt-in module asks for what is missing: single or multiple choice, defaults, yes/no questions, retries; it never blocks a batch job.

Interactive menus

🛠️

Standard Fortran, any build

Fortran 2018, tested with gfortran 13 to 16, nvfortran and Intel ifx; built with FoBiS, fpm, CMake or Make. Two small dependencies, fetched for you.

Installation

🔓

Multi-licensed

GPL v3 for FOSS projects; BSD 2-Clause, BSD 3-Clause or MIT for closed source and commercial ones: pick the license that fits.

Copyrights

Quick start ​

A real session with a FLAP program: the help, the values and the errors all come from FLAP.

a terminal session of a FLAP program: its help, some runs, a typo and an out-of-range value

This is the whole program, in four steps: initialise, define, parse, get.

f90
program greet
!< Quick start: a positional, a ranged integer, a choice read from the environment too, a flag.
use flap
implicit none
type(command_line_interface) :: cli
character(32)                :: name, lang, hello
integer                      :: times, i, error
logical                      :: shout

call cli%init(progname='greet', version='v1.0', description='Greet someone, in a few languages', &
              error_color='red', error_style='bold_on')
call cli%add(positional=.true., position=1, help='Who to greet', required=.true., metavar='NAME')
call cli%add(switch='--times', switch_ab='-t', help='How many times', def='1', min='1', max='5', metavar='N', &
             help_color='cyan', help_style='bold_on')
call cli%add(switch='--lang', help='Language', def='en', choices='en,it,fr', envvar='GREET_LANG', metavar='LANG', &
             help_color='cyan', help_style='bold_on')
call cli%add(switch='--shout', help='Say it louder', act='store_true', def='.false.', &
             help_color='cyan', help_style='bold_on')
call cli%parse(error=error)                 ! prints the help, the version or the error by itself
if (error /= 0) stop 1, quiet=.true.
call cli%get(position=1, val=name, error=error)       ; if (error /= 0) stop 1, quiet=.true.
call cli%get(switch='--times', val=times, error=error) ; if (error /= 0) stop 1, quiet=.true.
call cli%get(switch='--lang', val=lang, error=error)   ; if (error /= 0) stop 1, quiet=.true.
call cli%get(switch='--shout', val=shout, error=error) ; if (error /= 0) stop 1, quiet=.true.

select case(trim(lang))
case('it') ; hello = 'Ciao'
case('fr') ; hello = 'Salut'
case default ; hello = 'Hello'
endselect
do i = 1, times
  print '(A)', trim(hello)//' '//trim(name)//merge('!', '.', shout)
enddo
endprogram greet

Grows with your program ​

The same calls scale to commands, configuration files, a man page and shell completion. This help is generated from the definitions of the heat solver that the tutorial builds step by step; the colours are two keywords.

the help of a FLAP program

an error of a FLAP program

Learn FLAP step by step in the tutorial, find quick answers in the cookbook, look up every detail in the reference. Upgrading from v1.x? Read Upgrading.

Authors ​

Contributions are welcome — see the Contributing page.

Copyrights ​

This project is distributed under a multi-licensing system:

Anyone interested in using, developing, or contributing to this project is welcome — pick the license that best fits your needs.