• Stars
    star
    141
  • Rank 253,840 (Top 6 %)
  • Language
    Fortran
  • Created about 10 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Fortran command Line Arguments Parser for poor people

FLAP GitHub tag Join the chat at https://gitter.im/szaghi/FLAP

License License License License

Status CI Status Coverage Status

FLAP, Fortran command Line Arguments Parser for poor people

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.

Issues

GitHub issues

Compiler Support

Compiler Compiler Compiler Compiler Compiler Compiler


| What is FLAP? | Main features | Copyrights | Documentation | Install |


What is FLAP?

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

Main features

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, aka list-valued) CLA:
      • compiletime sized list, e.g. nargs='3';
      • runtime sized list with at least 1 value, e.g. nargs='+';
      • runtime sized list with any size, even empty, e.g. nargs='*';
    • 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

Copyrights

FLAP is an open source project, it is distributed under a multi-licensing system:

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

Documentation

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.

A Taste of FLAP

A minimal plate:

program minimal
type(command_line_interface) :: cli    ! Command Line Interface (CLI).
character(99)                :: string ! String value.
integer                      :: error  ! Error trapping flag.

call cli%init(description = 'minimal FLAP example')
call cli%add(switch='--string', &
             switch_ab='-s',    &
             help='a string',   &
             required=.true.,   &
             act='store',       &
             error=error)
if (error/=0) stop
call cli%get(switch='-s', val=string, error=error)
if (error/=0) stop
print '(A)', cli%progname//' has been called with the following argument:'
print '(A)', 'String = '//trim(adjustl(string))
endprogram minimal

That built and run provides:

→ ./minimal
./minimal: error: named option "--string" is required!

usage:  ./exe/test_minimal --string value [--help] [--version]

minimal FLAP example

Required switches:
   --string value, -s value
    a string

Optional switches:
   --help, -h
    Print this help message
   --version, -v
    Print version

A nice automatic help-message, right? Executed correctly gives.

→ ./minimal --string 'hello world'
./exe/minimal has been called with the following argument:
String = hello world

For more details, see the provided tests.

Nested (sub)commands

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_nested',                                      &
              version     = 'v2.1.5',                                           &
              authors     = 'Stefano Zaghi',                                    &
              license     = 'MIT',                                              &
              description = 'Toy program for testing FLAP with nested commands',&
              examples    = ['test_nested                      ',&
                             'test_nested -h                   ',&
                             'test_nested init                 ',&
                             'test_nested commit -m "fix bug-1"',&
                             'test_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!'
endif

that when invoked without arguments prompts:

cowardly you are doing nothing... try at least "-h" option!

and invoked with -h option gives:

usage: test_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_nested init -h,--help
  test_nested commit -h,--help
  test_nested tag -h,--help

Examples:
   test_nested
   test_nested -h
   test_nested init
   test_nested commit -m "fix bug-1"
   test_nested tag -a "v2.1.5"

For more details, see the provided example.

Go to Top


Install

FLAP is a Fortran library composed by several modules.

Before download and compile the library you must check the requirements.

To download and build the project two main ways are available:


Go to Top

install script

FLAP ships a bash script (downloadable from here) that is able to automatize the download and build steps. The script install.sh has the following usage:

→ ./install.sh
Install script of FLAP
Usage:

install.sh --help|-?
    Print this usage output and exit

install.sh --download|-d <arg> [--verbose|-v]
    Download the project

    --download|-d [arg]  Download the project, arg=git|wget to download with git or wget respectively
    --verbose|-v         Output verbose mode activation

install.sh --build|-b <arg> [--verbose|-v]
    Build the project

    --build|-b [arg]  Build the project, arg=fobis|make|cmake to build with FoBiS.py, GNU Make or CMake respectively
    --verbose|-v      Output verbose mode activation

Examples:

install.sh --download git
install.sh --build make
install.sh --download wget --build cmake

The script does not cover all possibilities.

The script operation modes are 2 (collapsible into one-single-mode):

you can mix any of the above combinations accordingly to the tools available.

Typical usages are:

# download and prepare the project by means of git and build with GNU Make
install.sh --dowload git --build make
# download and prepare the project by means of wget (curl) and build with CMake
install.sh --dowload wget --build cmake
# download and prepare the project by means of git and build with FoBiS.py
install.sh --dowload git --build fobis

Go to Top

manually download and build

download

To download all the available releases and utilities (fobos, license, readme, etc...), it can be convenient to clone whole the project:

git clone https://github.com/szaghi/FLAP
cd FLAP
git submodule update --init

Alternatively, you can directly download a release from GitHub server, see the ChangeLog.

build

The most easy way to compile FLAP is to use FoBiS.py within the provided fobos file.

Consequently, it is strongly encouraged to install FoBiS.py.

| Build by means of FoBiS | Build by means of GNU Make | Build by means of CMake |


build by means of FoBiS

FoBiS.py is a KISS tool for automatic building of modern Fortran projects. Providing very few options, FoBiS.py is able to build almost automatically complex Fortran projects with cumbersome inter-modules dependency. This removes the necessity to write complex makefile. Moreover, providing a very simple options file (in the FoBiS.py nomenclature indicated as fobos file) FoBiS.py can substitute the (ab)use of makefile for other project stuffs (build documentations, make project archive, etc...). FLAP is shipped with a fobos file that can build the library in both static and shared forms and also build the Test_Driver program. The provided fobos file has several building modes.

listing fobos building modes

Typing:

FoBiS.py build -lmodes

the following message should be printed:

The fobos file defines the following modes:
 - "shared-gnu"
  - "static-gnu"
  - "test-driver-gnu"
  - "shared-gnu-debug"
  - "static-gnu-debug"
  - "test-driver-gnu-debug"
  - "shared-intel"
  - "static-intel"
  - "test-driver-intel"
  - "shared-intel-debug"
  - "static-intel-debug"
  - "test-driver-intel-debug"

The modes should be self-explicative: shared, static and test-driver are the modes for building (in release, optimized form) the shared and static versions of the library and the Test Driver program, respectively. The other 3 modes are the same, but in debug form instead of release one. -gnu use the GNU gfortran compiler while -intel the Intel one.

building the library

The shared or static directories are created accordingly to the form of the library built. The compiled objects and mod files are placed inside this directory, as well as the linked library.

release shared library
FoBiS.py build -mode shared-gnu
release static library
FoBiS.py build -mode static-gnu
debug shared library
FoBiS.py build -mode shared-gnu-debug
debug static library
FoBiS.py build -mode static-gnu-debug
building the Test Driver program

The Test_Driver directory is created. The compiled objects and mod files are placed inside this directory, as well as the linked program.

release test driver program
FoBiS.py build -mode test-driver-gnu
debug test driver program
FoBiS.py build -mode test-driver-gnu-debug
listing fobos rules

Typing:

FoBiS.py rule -ls

the following message should be printed:

The fobos file defines the following rules:
  - "makedoc" Rule for building documentation from source files
       Command => rm -rf doc/html/*
       Command => ford doc/main_page.md
       Command => cp -r doc/html/publish/* doc/html/
  - "deldoc" Rule for deleting documentation
       Command => rm -rf doc/html/*
  - "maketar" Rule for making tar archive of the project
       Command => tar -czf FLAP.tar.gz *
  - "makecoverage" Rule for performing coverage analysis
       Command => FoBiS.py clean -mode test-driver-gnu
       Command => FoBiS.py build -mode test-driver-gnu -coverage
       Command => ./Test_Driver/Test_Driver
       Command => ./Test_Driver/Test_Driver -v
       Command => ./Test_Driver/Test_Driver -s 'Hello FLAP' -i 2
       Command => ./Test_Driver/Test_Driver 33.0 -s 'Hello FLAP' --integer_list 10 -3 87 -i 3 -r 64.123d0  --boolean --boolean_val .false.
  - "coverage-analysis" Rule for performing coverage analysis and saving reports in markdown
       Command => FoBiS.py clean -mode test-driver-gnu
       Command => FoBiS.py build -mode test-driver-gnu -coverage
       Command => ./Test_Driver/Test_Driver
       Command => ./Test_Driver/Test_Driver -v
       Command => ./Test_Driver/Test_Driver -s 'Hello FLAP' -i 2
       Command => ./Test_Driver/Test_Driver 33.0 -s 'Hello FLAP' --integer_list 10 -3 87 -i 3 -r 64.123d0  --boolean --boolean_val .false.
       Command => gcov -o Test_Driver/obj/ src/*
       Command => FoBiS.py rule -gcov_analyzer wiki/ Coverage-Analysis
       Command => rm -f *.gcov

The rules should be self-explicative.


build by means of GNU Make

Bad choice :-)

However, a makefile (generated by FoBiS.py...) to be used with a compatible GNU Make tool is provided.

It is convenient to clone the whole FLAP repository and run a standard make:

git clone https://github.com/szaghi/FLAP
cd FLAP
make -j 1

This commands build all tests (executables are in exe/ directory). To build only the library (statically linked) type:

git clone https://github.com/szaghi/FLAP
cd FLAP
make -j 1 STATIC=yes

Build by means of CMake

Bad choice :-)

However, a CMake setup (kindly developed by victorsndvg) is provided.

It is convenient to clone the whole FLAP repository and run a standard CMake configure/build commands:

git clone https://github.com/szaghi/FLAP $YOUR_FLAP_PATH
mkdir build
cd build
cmake $YOUR_FLAP_PATH
cmake --build .

If you want to run the tests suite type:

git clone https://github.com/szaghi/FLAP $YOUR_FLAP_PATH
mkdir build
cd build
cmake -DFLAP_ENABLE_TESTS=ON $YOUR_FLAP_PATH
cmake --build .
ctest

Build by means of FPM

A Fortran Package Manager manifest file is also included, so that the library and test cases can be compiled with FPM. For example:

fpm build --profile release
fpm test --profile release

To use FLAP within your fpm project, add the following to your fpm.toml file:

[dependencies]
FLAP = { git="https://github.com/szaghi/FLAP.git" }

Or, to use a specific revision:

[dependencies]
FLAP = { git="https://github.com/szaghi/FLAP.git", rev = "11cb276228d678c1d9ce755badf0ce82094b0852" }

Note that, when compiling with FPM, the git submodules in the src/third_party directory are not used, but FPM will download these separately, based on the versions specified in the fpm.toml file.

Go to Top

NVFortran Compiling Issue

Thanks to Carl Ponder (@cponder), we know that Nvidia NVFortran compiler misunderstand a quoted string containing a backslash into source files. To overcome this issue we suggest to use the -Mbackslash switch of NVFortran compiler.

For example, to compile by means of CMake use:

git clone https://github.com/szaghi/FLAP $YOUR_FLAP_PATH
mkdir build
cd build
cmake -D CMAKE_Fortran_FLAGS="-Mbackslash" $YOUR_FLAP_PATH
cmake --build .

Similarly, into the fobos config file there is a specific template for NVFortran where this switch has been used to compile FLAP by means of Nvidia compiler. To test it use:

FoBiS.py build -mode static-nvf

Go to Top

More Repositories

1

VTKFortran

pure Fortran VTK (XML) API
Fortran
137
star
2

FoBiS

FoBiS.py, Fortran projects Building System for poor people
Python
130
star
3

OFF

OFF, Open source Finite volume Fluid dynamics code
Fortran
126
star
4

StringiFor

Strings Fortran Manipulator with steroids
Fortran
83
star
5

MaTiSSe

Markdown To Impressive Scientific Slides
Python
45
star
6

PENF

Portability Environment for Fortran poor people
Fortran
38
star
7

FACE

Fortran Ansi Colors (and Styles) Environment
Fortran
37
star
8

FiNeR

Fortran INI ParseR and generator
Fortran
36
star
9

forbear

Fortran (progress) B(e)ar envinronment
Fortran
36
star
10

zen-of-fortran

an opinionated coding guidelines for Fortran poor people
31
star
11

VecFor

Vector algebra class for Fortran poor people
Fortran
29
star
12

FURY

Fortran Units (environment) for Reliable phYsical math
Fortran
29
star
13

PreForM

PreForM.py, Preprocessor for Fortran poor Men
Python
24
star
14

zen-of-fortran-talk

a path to discover Modern Fortran, a poor, informal talk for newbies Fortraners
Fortran
19
star
15

ZOO

ZOO, Zaghi fOrtran cOllection, where my wild Fortran pets will survive
Fortran
19
star
16

BeFoR64

BeFoR64, Base64 encoding/decoding library for FoRtran poor men
Fortran
18
star
17

FITTER

Fortran tIc Toc Timer
Fortran
14
star
18

FOSSIL

FOSSIL, FOrtran Stereo (si) Litography parser
Fortran
14
star
19

HASTY

HASh Table fortran container exploting coarraY
Fortran
13
star
20

DEFY

DEmystify Fortran mYths
Fortran
12
star
21

fmake

Small script for easy creation of makefile for Fortran (standard 90 or higher) projects
Racket
11
star
22

FLOw

Fortran fLuid Object
Fortran
11
star
23

FORESEER

FOrtran RiEmann SolveErs EnviRonment
Fortran
10
star
24

MORTIF

MORTon Indexer (Z-order) Fortran environment
Fortran
10
star
25

FriVolous

Finite Volume block-structured Fortran abstract class
Fortran
8
star
26

FUNDAL

Fortran UNified Device Acceleration Library
Fortran
8
star
27

leaks_hunter

hunter of Fortran Compilers memory leaks
Fortran
7
star
28

single-linked-list

Fortran
7
star
29

forget

FORtran Git Template
Fortran
6
star
30

dotfiles

my dotfiles...me!
Perl
5
star
31

dmoz-fortran-archive

an unofficial of DMOZ Fortran archive
HTML
5
star
32

Shu-Osher-shock-tube-problem

Regression-test results of Shu-Osher shock tube problem
Fortran
4
star
33

NTNU-BTs-CNR-INSEAN

CNR-INSEAN CFD simulations of NTNU Blind Tests, Horizontal Axis Wind Turbines experiments
Shell
3
star
34

DCS

Driven-Cavity Simulator
Fortran
3
star
35

cfdshipiowa_gridgen_to_xnavis

a Fortran Environment to handle CFDShip-Iowa Gridgen files and optionally emit Xnavis ones
Fortran
3
star
36

LoadBalance

Load balancing for Xnavis code
Fortran
1
star
37

ATENA-talk-2016-03-09

a talk for ATENA workshop
CSS
1
star