Appearance
The tutorial
The tutorial teaches FLAP by building one program, step by step. The cookbook then collects short recipes for everyday tasks, and the reference has every keyword, every rule, every error code.
The chapters
The tutorial builds the command line of heat, a (pretend) solver of the 2D heat equation, from three options to a polished, tested program with commands, configuration files and shell completion. Each chapter is a complete program that you can compile and run; every output shown is the real output of that program.
| Chapter | You learn |
|---|---|
| 1. A first command line | init, add, parse, get; the free --help and --version; errors and exit statuses |
| 2. Options of every kind | types, choices, ranges, counters, flags, optional values, placeholders |
| 3. Lists and parameters | fixed and variable lists, KEY=VALUE maps |
| 4. Commands | run, post, info: commands with their own options, aliases, shared options |
| 5. Values from everywhere | environment variables, a configuration file, the provenance of every value |
| 6. Validation | exclusive options, file checks, deprecations, auxiliary actions, the program's own checks |
| 7. Shipping it | a polished help, colours, man page, Markdown, shell completion |
| 8. Testing the command line | parsing strings, statuses instead of stops, capturing the messages |
| 9. Asking the user | an interactive menu, only when a value is missing |
The cookbook
The cookbook answers "how do I ...?" in a few lines each: a verbose flag, a list of files, an option that reads an environment variable, a subcommand, a test of the command line, ...
Building the examples
Every program of the tutorial and of the cookbook is in docs/examples/src. With FLAP built by FoBiS (fobis build --mode static-gnu, see Installation):
bash
gfortran -I static/mod docs/examples/src/heat_1.f90 static/libflap.a -o heat
./heat --helpbash scripts/docs_examples.sh builds and runs all of them, regenerating the outputs shown in these pages.
The examples end on an error with stop 1, quiet=.true.: FLAP has already printed the message, the program only sets the exit status (Fortran 2018; with nvfortran 26.5, which rejects quiet=, use call exit(1)).