A KISS pure Fortran Library for building powerful, easy-to-use, elegant command line interfaces
- FLAP is a pure Fortran (KISS) library for building easily nice Command Line Interfaces (CLI) for modern Fortran projects;
- FLAP is Fortran 2003+ standard compliant;
- FLAP is OOP designed;
- FLAP is a Free, Open Source Project.
-brightgreen.svg){kind=icon}
-brightgreen.svg){kind=icon}
Modern Fortran standards (2003+) have introduced support for Command Line Arguments (CLA), thus it is possible to construct nice and effective Command Line Interfaces (CLI). FLAP is a small library designed to simplify the (repetitive) construction of complicated CLI in pure Fortran (standard 2003+). FLAP has been inspired by the python module argparse trying to mimic it. Once you have defined the arguments that are required by means of a user-friendly method of the CLI, FLAP will parse the CLAs for you. It is worthy of note that FLAP, as argparse, also automatically generates help and usage messages and issues errors when users give the program invalid arguments.
Go to Top
FLAP is inspired by the python great module argparse, thus many features are taken from it. Here the main features are listed.
- User-friendly methods for building flexible and effective Command Line Interfaces (CLI);
- comprehensive Command Line Arguments (CLA) support:
- support optional and non optional CLA;
- support boolean CLA;
- support positional CLA;
- support list of allowable values for defined CLA with automatic consistency check;
- support multiple valued (list of values) CLA;
- support mutually exclusive CLAs;
- self-consistency-check of CLA definition;
- support fake CLAs input from a string;
- support fake CLAs input from environment variables;
- comprehensive command (group of CLAs) support:
- support nested subcommands;
- support mutually exclusive commands;
- self-consistency-check of command definition;
- automatic generation of help and usage messages;
- consistency-check of whole CLI definition;
- errors trapping for invalid CLI usage;
- POSIX style compliant;
- automatic generation of MAN PAGE using your CLI definition!;
- replicate all the useful features of argparse;
- implement docopt features.
- implement click features.
Any feature request is welcome.
Go to Top
FLAP is an open source project, it is distributed under a multi-licensing system:
- for FOSS projects:
- for closed source/commercial projects:
Anyone is interest to use, to develop or to contribute to FLAP is welcome, feel free to select the license that best matches your soul!
More details can be found on wiki.
Go to Top
Besides this README file the FLAP documentation is contained into its own wiki. Detailed documentation of the API is contained into the GitHub Pages that can also be created locally by means of ford tool.
Running the provided test program, Test_Driver -h, a taste of FLAP is served:
usage: Test_Driver [value] --string value [--integer value] [--real value] [--boolean] [--boolean_val value] [--integer_list value#1 value#2 value#3] [--help] [--version]
Toy program for testing FLAP
Required switches:
--string value, -s value
String input
Optional switches:
value
1-th argument
default value 1.0
Positional real input
--integer value, -i value, value in: (1,3,5)
default value 1
Integer input with fixed range
--real value, -r value
default value 1.0
Real input
--boolean, -b
default value .false.
Boolean input
--boolean_val value, -bv value
default value .true.
Valued boolean input
--integer_list value#1 value#2 value#3, -il value#1 value#2 value#3
default value 1 8 32
Integer list input
--help, -h
Print this help message
--version, -v
Print version
Examples:
Test_Driver -s 'Hello FLAP'
Test_Driver -s 'Hello FLAP' -i -2 # printing error...
Test_Driver -s 'Hello FLAP' -i 3 -r 33.d0
Test_Driver -s 'Hello FLAP' --integer_list 10 -3 87
Test_Driver 33.0 -s 'Hello FLAP' -i 5
Test_Driver --string 'Hello FLAP' --booleanNot so bad for just a very few statements as the following:
! initializing Command Line Interface
call cli%init(progname = 'Test_Driver', &
version = 'v2.1.5', &
authors = 'Stefano Zaghi', &
license = 'MIT', &
description = 'Toy program for testing FLAP', &
examples = ["Test_Driver -s 'Hello FLAP' ",&
"Test_Driver -s 'Hello FLAP' -i -2 # printing error...",&
"Test_Driver -s 'Hello FLAP' -i 3 -r 33.d0 ",&
"Test_Driver -s 'Hello FLAP' --integer_list 10 -3 87 ",&
"Test_Driver 33.0 -s 'Hello FLAP' -i 5 ",&
"Test_Driver --string 'Hello FLAP' --boolean "])
! setting Command Line Argumenst
call cli%add(switch='--string',switch_ab='-s',help='String input',required=.true.,act='store',error=error)
call cli%add(switch='--integer',switch_ab='-i',help='Integer input with fixed range',required=.false.,act='store',&
def='1',choices='1,3,5',error=error)
call cli%add(switch='--real',switch_ab='-r',help='Real input',required=.false.,act='store',def='1.0',error=error)
call cli%add(switch='--boolean',switch_ab='-b',help='Boolean input',required=.false.,act='store_true',def='.false.',&
error=error)
call cli%add(switch='--boolean_val',switch_ab='-bv',help='Valued boolean input',required=.false., act='store',&
def='.true.',error=error)
call cli%add(switch='--integer_list',switch_ab='-il',help='Integer list input',required=.false.,act='store',&
nargs='3',def='1 8 32',error=error)
call cli%add(positional=.true.,position=1,help='Positional real input',required=.false.,def='1.0',error=error)
! parsing Command Line Interface
call cli%parse(error=error)For more details, see the provided example.
For a practical example of FLAP usage see POG source file at line 85.
FLAP fully supports nested (sub)commands or groups of command line arguments. For example a fake git toy remake can be coded as
! initializing Command Line Interface
call cli%init(progname = 'Test_Driver_Nested', &
version = 'v2.1.5', &
authors = 'Stefano Zaghi', &
license = 'MIT', &
description = 'Toy program for testing FLAP with nested commands', &
examples = ['Test_Driver_Nested ',&
'Test_Driver_Nested -h ',&
'Test_Driver_Nested init ',&
'Test_Driver_Nested commit -m "fix bug-1"',&
'Test_Driver_Nested tag -a "v2.1.5" '])
! set a Command Line Argument without a group to trigger authors names printing
call cli%add(switch='--authors',switch_ab='-a',help='Print authors names',required=.false.,act='store_true',def='.false.')
! set Command Line Arguments Groups, i.e. commands
call cli%add_group(group='init',description='fake init versioning')
call cli%add_group(group='commit',description='fake commit changes to current branch')
call cli%add_group(group='tag',description='fake tag current commit')
! set Command Line Arguments of commit command
call cli%add(group='commit',switch='--message',switch_ab='-m',help='Commit message',required=.false.,act='store',def='')
! set Command Line Arguments of commit command
call cli%add(group='tag',switch='--annotate',switch_ab='-a',help='Tag annotation',required=.false.,act='store',def='')
! parsing Command Line Interface
call cli%parse(error=error)
if (error/=0) then
print '(A)', 'Error code: '//trim(str(n=error))
stop
endif
! using Command Line Interface data to trigger program behaviour
call cli%get(switch='-a',val=authors_print,error=error) ; if (error/=0) stop
if (authors_print) then
print '(A)','Authors: '//cli%authors
elseif (cli%run_command('init')) then
print '(A)','init (fake) versioning'
elseif (cli%run_command('commit')) then
call cli%get(group='commit',switch='-m',val=message,error=error) ; if (error/=0) stop
print '(A)','commit changes to current branch with message "'//trim(message)//'"'
elseif (cli%run_command('tag')) then
call cli%get(group='tag',switch='-a',val=message,error=error) ; if (error/=0) stop
print '(A)','tag current branch with message "'//trim(message)//'"'
else
print '(A)','cowardly you are doing nothing... try at least "-h" option!'
endifthat when invoked without arguments prompts:
cowardly you are doing nothing... try at least "-h" option!and invoked with -h option gives:
usage: Test_Driver_Nested [--authors] [--help] [--version] {init,commit,tag} ...
Toy program for testing FLAP with nested commands
Optional switches:
--authors, -a
default value .false.
Print authors names
--help, -h
Print this help message
--version, -v
Print version
Commands:
init
fake init versioning
commit
fake commit changes to current branch
tag
fake tag current commit
For more detailed commands help try:
Test_Driver_Nested init -h,--help
Test_Driver_Nested commit -h,--help
Test_Driver_Nested tag -h,--help
Examples:
Test_Driver_Nested
Test_Driver_Nested -h
Test_Driver_Nested init
Test_Driver_Nested commit -m "fix bug-1"
Test_Driver_Nested tag -a "v2.1.5"For more details, see the provided example.
Go to Top