search

urbanjost / M_CLI2

Fortran commandline-interface using a simple prototype command
The Unlicense
20 stars 4 forks source link
argument command-line fortran fortran-package-manager parsing

readme

M_CLI2.f90 and associated files

M_CLI2

Name

M_CLI2 - parse Unix-like command line arguments from Fortran

Description

M_CLI2(3f) is a Fortran module that will crack the command line when given a prototype string that looks very much like an invocation of the program. Calls are then made for each parameter name to set the variables appropriately in the program. One approach is isolate all the parsing to the beginning of the program, which is generally just a few lines:

   program compartmentalized
   use M_CLI2, only : set_args, get_args, s=>sget, r=>rget, i=>iget, l=>lget 
   implicit none
   !
   ! define command options and default values and parse command line
     call set_args('-x 1 -y 2.0 -i 11 --title:T "my title" -l F -L F')
   ! just like calling the command accept --title:T means to give it the long
   ! name "title" and the short name "T" and that to define a boolean you give
   ! it the unquoted value of F.
   !
   ! convert arguments to the desired types and call main program
     call main( x=r('x'), y=r('y'), title=s('title'), i=i('i'), l=l('l'), lbig=l('L'))
   contains 
   subroutine main(x,y,title,i,l,lbig)
   ! do something with the values, all the parsing is done
   real                          :: x,y     ;namelist /args/x,y
   logical                       :: l,lbig  ;namelist /args/l,lbig
   integer                       :: i       ;namelist /args/i
   character(len=:),allocatable  :: title   ;namelist /args/title
   write(*,nml=args)
   end subroutine main
   end program compartmentalized

Example Program

This short program defines a command that can be called using conventional Unix-style syntax for short and long parameters:

   # arrays can be allowed like for "-p":
   ./show -x 10 -y -20 -p 10,20,30 --title "plot of stuff" -L
   ./show -lL # in strict mode booleans may be concatenated
   ./show  --title="my new title" # --name=value or --name value is OK
   ./show  -T "my new title" # a short name for "title"
   program show
   use M_CLI2, only : set_args, get_args, set_mode
   use M_CLI2, only : sget, rget, iget, lget 
   use M_CLI2, only : sgets, rgets, igets, lgets 
   implicit none
   real                          :: x,y,z
   logical                       :: l, lbig
   integer,allocatable           :: p(:)
   character(len=:),allocatable  :: title
   namelist /args/x,y,z,l,lbig,p,title ! just for printing
      call set_mode('strict')
      !
      ! Define command and default values and parse supplied command line options
      call set_args('-x 1 -y 2.0 -z 3.5e0 -p 11,-22,33 --title:T "my title" -l F -L F')
      ! use convenience functions for scalar values or allocatable arrays. 
      ! The functions are particularly useful in expressions and as arguments on
      ! procedure calls:
      x=rget('x')         ! float 
      y=rget('y') 
      z=rget('z') 
      title=sget('title') ! string 
      p=igets('p')        ! integer array
      l=lget('l')         ! logical
      lbig=lget('L')
      ! All ready to go, print it as a namelist so everything is labeled
      write(*,args)
      !
      ! Alternatively: use get_args directly instead of via the convenience routines:
      !
      ! multiple scalar non-allocatable values can be done in one call if desired
      call get_args('x',x,'y',y,'z',z,'l',l,'L',lbig)
      !
      ! allocatable arrays and allocatable string lengths need called by themselves
      call get_args('title',title)
      call get_args('p',p)
      !
      ! All ready to go, print it as a namelist so everything is labeled
      write(*,args)
   end program show

running with no options shows the defaults

&ARGS
 X=  1.00000000    ,
 Y=  2.00000000    ,
 Z=  3.50000000    ,
 L=F,
 LBIG=F,
 P=11         ,-22        ,33         ,
 TITLE="my title",
 /

An arbitrary number of strings such as filenames may be passed in on the end of commands; you can query whether an option was supplied; and get_args(3f)-related routines can be used for refining options such as requiring lists of a specified size.

These parameters are defined automatically

    --help
    --usage
    --verbose
    --version

You must supply text for the optional "--help" and "--version" keywords, as described under SET_ARGS(3f).

docs

Documentation

manpages

man-pages

developer documentation

logs

standalone command-line documentation program

The 3.2.0 release of the command-line parser module M_CLI2 has a standalone program available that will display the help text for the procedures as a substitute for the man(1) pages.

If the program is placed in your search path you can enter

fpm-m_cli2 --help
# if an fpm user
fpm m_cli2 --help

for a description of usage. An example to build it on a typical Linux platform would be

# create a scratch directory for the build
mkdir temp
cd temp
# get the documentation program
curl https://raw.githubusercontent.com/urbanjost/index/main/bootstrap/fpm-m_cli2.f90
# compile the program
gfortran fpm-m_cli2.f90 -o fpm-m_cli2
# copy it to somewhere in your path
mv fpm-m_cli2 $HOME/.local/bin/

gmake

Download and Build with Make(1)

Compile the M_CLI2 module and build all the example programs.

   git clone https://github.com/urbanjost/M_CLI2.git
   cd M_CLI2/src
   # change Makefile if not using one of the listed compilers

   # for gfortran
   make clean
   make gfortran

   # for ifort
   make clean
   make ifort

   # for nvfortran
   make clean
   make nvfortran

   # display other options (test, run, doxygen, ford, ...)
   make help

To install you then generally copy the .mod file and .a file to an appropriate directory. Unfortunately, the specifics vary but in general if you have a directory $HOME/.local/lib and copy those files there then you can generally enter something like

     gfortran -L$HOME/.local/lib -lM_CLI2  myprogram.f90 -o myprogram

There are different methods for adding the directory to your default load path, but frequently you can append the directory you have placed the files in into the colon-separated list of directories in the $LD_LIBRARY_PATH or $LIBRARY_PATH environment variable, and then the -L option will not be required (or it's equivalent in your programming environment).

       export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH

NOTE: If you use multiple Fortran compilers you may need to create a different directory for each compiler. I would recommend it, such as $HOME/.local/lib/gfortran/.

Creating a shared library

If you desire a shared library as well, for gfortran you may enter

     make clean gfortran gfortran_install

and everything needed by gfortran will be placed in libgfortran/ that you may add to an appropriate area, such as $HOME/.local/lib/gfortran/.

     make clean ifort ifort_install # same for ifort

does the same for the ifort compiler and places the output in libifort/.

Specifics may vary

NOTE: The build instructions above are specific to a ULS (Unix-Like System) and may differ, especially for those wishing to generate shared libraries (which varies significantly depending on the programming environment). For some builds it is simpler to make a Makefile for each compiler, which might be required for a more comprehensive build unless you are very familiar with gmake(1).

If you always use one compiler it is relatively simple, otherwise make sure you know what your system requires and change the Makefile as appropriate.

parse

Build with FPM

Alternatively, fpm(1) users may download the github repository and build it with fpm ( as described at Fortran Package Manager )

        git clone https://github.com/urbanjost/M_CLI2.git
        cd M_CLI2
        fpm test   # build and test the module
        fpm install # install the module (in the default location)

or just list it as a dependency in your fpm.toml project file.

        [dependencies]
        M_CLI2        = { git = "https://github.com/urbanjost/M_CLI2.git" }

Supports Meson

Alternatively, meson(1) users may download the github repository and build it with meson ( as described at Meson Build System )

        git clone https://github.com/urbanjost/M_CLI2.git
        cd M_CLI2
        meson setup _build
        meson test -C _build  # build and test the module

        # install the module (in the <DIR> location)
        # --destdir is only on newer versions of meson
        meson install -C _build --destdir <DIR>
        # older method if --destdir is not available
        env DESTDIR=<DIR> meson install -C _build

or just list it as a subproject dependency in your meson.build project file.

        M_CLI2_dep = subproject('M_CLI2').get_variable('M_CLI2_dep')

Functional Specification

This is how the interface works --

demos

Demo Programs

These demo programs provide templates for the most common usage:

Optional Modes

Niche examples

Response files

Response files are supported as described in the documentation for set_args. They are a system-independent way to create short abbreviations for long complex commands. This option is generally not needed by programs with just a few options, but can be particularly useful for programs with dozens of options where various values are frequently reused.

Commit Tests

commit 598e44164eee383b8a0775aa75b7d1bb100481c3 was tested on 2020-11-22 with

commit 8fe841d8c0c1867f88847e24009a76a98484b31a was tested on 2021-09-29 with

commit 732bcadf95e753ccdf025cec2c08d776ea2534c2 was tested on 2023-02-10 with