M_CLI2(3) 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 variables appropriately in the program.

One common style of use is to 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, sget, rget, dget, iget, lget
   implicit none
     ! define command 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', &

     ! optional block of text to display when the --help option appears
     help_text=[character(len=80):: &
     'NAME', &
     '  compartmentalized - example program for parsing command line', &
     'DESCRIPTION', &
     '   A program to illustrate using M_CLI2 to parse the command line', &
     '   including creating help text using a block of text.', &
     'OPTIONS', &
     ' -x,-y:      some real values', &
     ' -i:         a whole number', &
     ' --title,T:  title line', &
     ' -l,-L       some Boolean options', &
     ''], &

     ! optional block of text to display when the --version option appears
     version_text=[character(len=80):: &
     'PROGRAM:     compartmentalized               ', &
     'DESCRIPTION: Illustrate command line parsing ', &
     'VERSION:     1.0, 2026-01-26                 ', &
     'AUTHOR:      Leonardo DaVinci                ', &
     'LICENSE:     Public Domain', &
     ''])

     ! get all the argument values and assign them to variables of various
     ! types 
     call main(&
     & x=rget('x'), y=rget('y'), & ! get some float values
     & title=sget('title'),      & ! get a string
     & i=iget('i'),              & ! get a whole number
     l=lget('l'), lbig=lget('L'))  ! get some boolean options
   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

The SET_ARGS(3) call defines the command options and default values and parses the command line. The common Unix command line style is supported where "--keyword=value" or "--keyword value" for long names (multiple character) and "-L" for short names (where L is a single letter).

The "*GET" routines are all that is required to assign scalar values from the command line values by keyword to Fortran variables.

Additionally, the matching "*GETS" functions return arrays of values.

You can query whether a keyword has been specified or not using SPECIFIED(3).

M_CLI2(3) intentionally does not include validating values beyond type because Fortran is already very good at that. The example program in the document for SPECIFIED(3) shows how to determine if required parameters are present, to ensure only one of a number of mutually exclusive options has been chosen, that a value matches a specified range or is a member of a given set, ...

As illustrated, text blocks to display when --help or --version is supplied on the command line can optionally be added to the SET_ARGS(3) call.

A few additional modes are also available. For example, by default Boolean short names may not be concatenated, but in "strict" mode they can be (but in "strict" mode then long keywords must always start with two dashes instead of one or two being allowed).

There are also advanced features such as support for "response files" which let you create platform-independent aliases for long commands, support for subcommands, and a few other less-used capabilities.

All the features are demonstrated via example programs and man-page format descriptions of each procedure.

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

Note that these parameters are defined automatically

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

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

The syntax used in SET_ARGS(3) is similar to invoking the command from the command using just a few simple rules:

• Each keyword must have a default value specified separated from the keyword by a space.
• double-quote string values
• use a value of F unquoted to designate a keyword as Boolean
• to have both a long and short keyword name designate the long name followed immediately by ":LETTER" where LETTER is the short keyword name.
• separate lists of values with commas
• if the value can start with a dash and you want to allow the syntax "--keyword value" add a : to the end of the keyword, which means "next argument is a value even if it starts with " -".

    call set_args('-a -10 -b 1,2,3 --title:T "my title" -t F')

That single line defines all the command keywords and their default values and parses the command line.

All that remains is to get argument values. To get the values

• you add calls to the get_args(3) subroutine or one of its shortcut function names.

  These alternative shortcut names are convenience procedures (rget(3),sget(3),iget(3) ...) that allow you to use a simple function-based interface.

  Less frequently used are special routines for when you want to use fixed length CHARACTER variables or fixed-size arrays instead of the allocatable variables. These require routines that start with "GET_ARGS".

Now when you call the program all the values in the program should be updated using values from the prototype and command line and be ready to use in your program.

These demo programs provide templates for the most common usage:

• demo3 Example of basic use
• demo1 Using the convenience functions
• demo9 Long and short names using --LONGNAME:SHORTNAME.
• demo2 Putting everything including help and version information into a contained procedure.
• demo17 Using unnamed options as filenames or strings
• demo16 Using unnamed values as numbers

• demo15 Allowing bundling short Boolean keys using "strict" mode
• demo14 Optional mode for case-insensitive long keys
• demo12 Enabling response files
• demo13 Mode for equivalencing dash to underscore in keynames

• demo8 Parsing multiple keywords in a single call to get_args(3)
• demo4 COMPLEX-type values
• demo7 Controlling delimiter characters for values that are arrays
• demo6 How to create a command with subcommands
• demo5 extended description of using CHARACTER type values

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.

• HTML man-pages index of individual procedures
• HTML book-form of pages consolidated using JavaScript

• manpages.zip for installing wherever the man(1) command is available
• manpages.tgz is an alternative tar(1) format archive

• doxygen(1) output.
• ford(1) output.

• CHANGELOG
• STATUS of most recent CI/CD runs

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/

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/.

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/.

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.

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" }

To download the github repository and build and install with cmake (you may wish to change the install path in src/CMakeLists.txt first) :

      git clone https://github.com/urbanjost/M_CLI2.git
      cd M_CLI2

      # Create a Build Directory:
      mkdir -p build

      cd build
      cmake -S ../src -B .

      # Configure the Build, specifying your preferred compiler (ifort, flang, etc.):
      cmake . -DCMAKE_Fortran_COMPILER=gfortran

      # Build the Project:
      cmake --build .

      #This creates:
      #
      #    build/lib/libM_CLI2.a (the static library).
      #    build/include/*.mod (module files).
      #    build/test/* (test executables).
      #    build/example/* (example executables).

      # OPTIONAL SECTION:

      # Verify build
      ls build/lib/libM_CLI2.a
      ls build/include/*.mod
      ls build/test/*
      ls build/example/*

      #Optionally Run Tests and Examples:
      for name in ./test/* ./example/*
      do
         $name
      done

      #Install (Optional):
      # This installs the library and module files to the system
      # (e.g., /usr/local/lib/ and /usr/local/include/).
      cmake --install .

      # if you have insufficient permissions sudo(1) may be required
      # to perform the install
      #sudo cmake --install .

      # Verify installation
      ls /usr/local/lib/libM_CLI2.a
      ls /usr/local/include/*.mod

      # Cleaning Up: To clean artifacts, remove the build/ directory:
      rm -rf build

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')

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

• GNU Fortran (GCC) 8.3.1 20191121 (Red Hat 8.3.1-5)
• ifort (IFORT) 19.1.3.304 20200925
• nvfortran 20.7-0 LLVM 64-bit target on x86-64 Linux

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

• GNU Fortran (Ubuntu 10.3.0-1ubuntu1~20.04) 10.3.0
• ifort (IFORT) 2021.3.0 20210609
• nvfortran 21.5-0 LLVM 64-bit target on x86-64 Linux -tp nehalem

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

• ifort (IFORT) 2021.8.0 20221119
• GNU Fortran (Ubuntu 11.1.0-1ubuntu1~20.04) 11.1.0

Last update: Saturday, February 4th, 2023 1:12:54 AM UTC-05:00