M_CLI2 – M_CLI2
Author: John S. Urban
Description: command line parsing

# M_CLI2 Module

- 2637 statements
- Source File

## NAME

    M_CLI2(3fm) - [ARGUMENTS::M_CLI2::INTRO] command line argument
    parsing using a prototype command
    (LICENSE:PD)

## SYNOPSIS

Available procedures and variables:

      ! basic procedures
      use M_CLI2, only : set_args, get_args, specified, set_mode
      ! convenience functions
      use M_CLI2, only : dget, iget, lget, rget, sget, cget
      use M_CLI2, only : dgets, igets, lgets, rgets, sgets, cgets
      ! variables
      use M_CLI2, only : unnamed, remaining, args
      ! working with non-allocatable strings and arrays
      use M_CLI2, only : get_args_fixed_length, get_args_fixed_size
      ! special function for creating subcommands
      use M_CLI2, only : get_subcommand(3f)

## DESCRIPTION

    The M_CLI2 module cracks a Unix-style command line.

    Typically one call to SET_ARGS(3f) is made to define the command
    arguments, set default values and parse the command line. Then a call
    is made to the convenience procedures or GET_ARGS(3f) proper for each
    command keyword to obtain the argument values.

    Detailed descriptions of each procedure and example programs are
    included.

## EXAMPLE

Sample minimal program which may be called in various ways:

     mimimal -x 100.3 -y 3.0e4
     mimimal --xvalue=300 --debug
     mimimal --yvalue 400
     mimimal -x 10 file1 file2 file3

Program example:

     program minimal
     use M_CLI2,  only : set_args, lget, rget, sgets
     implicit none
     real    :: x, y
     integer :: i
     character(len=:),allocatable :: filenames(:)
        ! define and crack command line
        call set_args(' --yvalue:y 0.0 --xvalue:x 0.0 --debug F')
        ! get values
        x=rget('xvalue')
        y=rget('yvalue')
        if(lget('debug'))then
           write(*,*)'X=',x
           write(*,*)'Y=',y
           write(*,*)'ATAN2(Y,X)=',atan2(x=x,y=y)
        else
           write(*,*)atan2(x=x,y=y)
        endif
        filenames=sgets() ! sget with no name gets "unnamed" values
        if(size(filenames) > 0)then
           write(*,'(g0)')'filenames:'
           write(*,'(i6.6,3a)')(i,'[',filenames(i),']',i=1,size(filenames))
        endif
     end program minimal

Sample program using get_args() and variants

     program demo_M_CLI2
     use M_CLI2,  only : set_args, get_args
     use M_CLI2,  only : filenames=>unnamed
     use M_CLI2,  only : get_args_fixed_length, get_args_fixed_size
     implicit none
     integer                      :: i
     integer,parameter            :: dp=kind(0.0d0)
      !
      ! Define ARGS
     real                         :: x, y, z
     logical                      :: l, lbig
     character(len=40)            :: label    ! FIXED LENGTH
     real(kind=dp),allocatable    :: point(:)
     logical,allocatable          :: logicals(:)
     character(len=:),allocatable :: title    ! VARIABLE LENGTH
     real                         :: p(3)     ! FIXED SIZE
     logical                      :: logi(3)  ! FIXED SIZE
      !
      ! DEFINE AND PARSE (TO SET INITIAL VALUES) COMMAND LINE
      !   o set a value for all keywords.
      !   o double-quote strings, strings must be at least one space
      !     because adjacent double-quotes designate a double-quote
      !     in the value.
      !   o set all logical values to F
      !   o numeric values support an "e" or "E" exponent
      !   o for lists delimit with a comma, colon, or space
     call set_args('                         &
             & -x 1 -y 2 -z 3                &
             & -p -1 -2 -3                   &
             & --point 11.11, 22.22, 33.33e0 &
             & --title "my title" -l F -L F  &
             & --logicals  F F F F F         &
             & --logi F T F                  &
             & --label " " &
             ! note space between quotes is required
             & ')
      ! Assign values to elements using G_ARGS(3f).
      ! non-allocatable scalars can be done up to twenty per call
     call get_args('x',x, 'y',y, 'z',z, 'l',l, 'L',lbig)
      ! As a convenience multiple pairs of keywords and variables may be
      ! specified if and only if all the values are scalars and the CHARACTER
      ! variables are fixed-length or pre-allocated.
      !
      ! After SET_ARGS(3f) has parsed the command line
      ! GET_ARGS(3f) retrieves the value of keywords accept for
      ! two special cases. For fixed-length CHARACTER variables
      ! see GET_ARGS_FIXED_LENGTH(3f). For fixed-size arrays see
      ! GET_ARGS_FIXED_SIZE(3f).
      !
      ! allocatables should be done one at a time
     call get_args('title',title) ! allocatable string
     call get_args('point',point) ! allocatable arrays
     call get_args('logicals',logicals)
      !
      ! less commonly ...

      ! for fixed-length strings
     call get_args_fixed_length('label',label)

      ! for non-allocatable arrays
     call get_args_fixed_size('p',p)
     call get_args_fixed_size('logi',logi)
      !
      ! all done parsing, use values
     write(*,*)'x=',x, 'y=',y, 'z=',z, x+y+z
     write(*,*)'p=',p
     write(*,*)'point=',point
     write(*,*)'title=',title
     write(*,*)'label=',label
     write(*,*)'l=',l
     write(*,*)'L=',lbig
     write(*,*)'logicals=',logicals
     write(*,*)'logi=',logi
      !
      ! unnamed strings
      !
     if(size(filenames) > 0)then
        write(*,'(i6.6,3a)')(i,'[',filenames(i),']',i=1,size(filenames))
     endif
      !
     end program demo_M_CLI2

## AUTHOR

     John S. Urban, 2019

## LICENSE

     Public Domain

## SEE ALSO

     + get_args(3f)
     + get_args_fixed_size(3f)
     + get_args_fixed_length(3f)
     + get_subcommand(3f)
     + set_mode(3f)
     + specified(3f)

Note that the convenience routines are described under get_args(3f): dget(3f), iget(3f), lget(3f), rget(3f), sget(3f), cget(3f) dgets(3f), igets(3f), lgets(3f), rgets(3f), sgets(3f), cgets(3f)

### Uses

- - iso_fortran_env

### Contents

### Variables

CLI_RESPONSE_FILE args remaining unnamed

### Interfaces

cgets dgets get_args get_args_fixed_length get_args_fixed_size igets lgets rgets sgets

### Functions

cget dget get_subcommand iget lget rget sget specified

### Subroutines

print_dictionary set_args set_mode

## Variables

Type | Visibility | Attributes |  | Name |  | Initial |
--- | --- | --- | --- | --- | --- | --- | ---
logical, | public, | save | :: | CLI_RESPONSE_FILE | = | .false. |
character(len=:), | public, | allocatable | :: | args(:) |  |  |
character(len=:), | public, | allocatable | :: | remaining |  |  |
character(len=:), | public, | allocatable | :: | unnamed(:) |  |  |

## Interfaces

### public interface cgets

- ### private function cgs(n)

  #### Arguments

  Type | Intent | Optional | Attributes |  | Name |
  --- | --- | --- | --- | --- | --- | ---
  character(len=*), | intent(in) |  |  | :: | n |

  #### Return Value complex, allocatable, (:)

- ### private function cg()

  #### Arguments

  None

  #### Return Value complex, allocatable, (:)

### public interface dgets

- ### private function dgs(n)

  #### Arguments

  Type | Intent | Optional | Attributes |  | Name |
  --- | --- | --- | --- | --- | --- | ---
  character(len=*), | intent(in) |  |  | :: | n |

  #### Return Value real(kind=dp), allocatable, (:)

- ### private function dg()

  #### Arguments

  None

  #### Return Value real(kind=dp), allocatable, (:)

### public interface get_args

- ### private subroutine get_anyarray_d(keyword, darray, delimiters)

  #### Arguments

  Type | Intent | Optional | Attributes |  | Name |
  --- | --- | --- | --- | --- | --- | ---
  character(len=*), | intent(in) |  |  | :: | keyword |
  real(kind=dp), | intent(out), |  | allocatable | :: | darray(:) |
  character(len=*), | intent(in), | optional |  | :: | delimiters |

### public interface get_args_fixed_length

- ### private subroutine get_args_fixed_length_a_array(keyword, strings, delimiters)

  #### Arguments

  Type | Intent | Optional | Attributes |  | Name |
  --- | --- | --- | --- | --- | --- | ---
  character(len=*), | intent(in) |  |  | :: | keyword |
  character(len=*), |  |  | allocatable | :: | strings(:) |
  character(len=*), | intent(in), | optional |  | :: | delimiters |

### public interface get_args_fixed_size

- ### private subroutine get_fixedarray_class(keyword, generic, delimiters)

  ## NAME

      get_args(3f) - [ARGUMENTS:M_CLI2] return keyword values when parsing
      command line arguments
      (LICENSE:PD)

  ## SYNOPSIS

  get_args(3f) and its convenience functions:

       use M_CLI2, only : get_args
       ! convenience functions
       use M_CLI2, only : dget, iget, lget, rget, sget, cget
       use M_CLI2, only : dgets, igets, lgets, rgets, sgets, cgets

       subroutine get_args(name,value,delimiters)

        character(len=*),intent(in) :: name

        type(${TYPE}),allocatable,intent(out) :: value(:)
        ! or
        type(${TYPE}),allocatable,intent(out) :: value

        character(len=*),intent(in),optional :: delimiters

        where ${TYPE} may be from the set
                {real,doubleprecision,integer,logical,complex,character(len=:)}

  ## DESCRIPTION

      GET_ARGS(3f) returns the value of keywords after SET_ARGS(3f) has
      been called to parse the command line. For fixed-length CHARACTER
      variables see GET_ARGS_FIXED_LENGTH(3f). For fixed-size arrays see
      GET_ARGS_FIXED_SIZE(3f).

      As a convenience multiple pairs of keywords and variables may be
      specified if and only if all the values are scalars and the CHARACTER
      variables are fixed-length or pre-allocated.

  ## OPTIONS

       NAME        name of commandline argument to obtain the value of
       VALUE       variable to hold returned value. The kind of the value
                   is used to determine the type of returned value. May
                   be a scalar or allocatable array. If type is CHARACTER
                   the scalar must have an allocatable length.
       DELIMITERS  By default the delimiter for array values are comma,
                   colon, and whitespace. A string containing an alternate
                   list of delimiter characters may be supplied.

  ## CONVENIENCE FUNCTIONS

      There are convenience functions that are replacements for calls to
      get_args(3f) for each supported default intrinsic type

        o scalars -- dget(3f), iget(3f), lget(3f), rget(3f), sget(3f),
                     cget(3f)
        o vectors -- dgets(3f), igets(3f), lgets(3f), rgets(3f),
                     sgets(3f), cgets(3f)

      D is for DOUBLEPRECISION, I for INTEGER, L for LOGICAL, R for REAL,
      S for string (CHARACTER), and C for COMPLEX.

      If the functions are called with no argument they will return the
      UNNAMED array converted to the specified type.

  ## EXAMPLE

  Sample program:

       program demo_get_args
       use M_CLI2,  only : filenames=>unnamed, set_args, get_args
       implicit none
       integer                      :: i
        ! Define ARGS
       real                         :: x, y, z
       real,allocatable             :: p(:)
       character(len=:),allocatable :: title
       logical                      :: l, lbig
        ! Define and parse (to set initial values) command line
        !   o only quote strings and use double-quotes
        !   o set all logical values to F or T.
       call set_args('         &
          & -x 1 -y 2 -z 3     &
          & -p -1,-2,-3        &
          & --title "my title" &
          & -l F -L F          &
          & --label " "        &
          & ')
        ! Assign values to elements
        ! Scalars
       call get_args('x',x,'y',y,'z',z,'l',l,'L',lbig)
        ! Allocatable string
       call get_args('title',title)
        ! Allocatable arrays
       call get_args('p',p)
        ! Use values
       write(*,'(1x,g0,"=",g0)')'x',x, 'y',y, 'z',z
       write(*,*)'p=',p
       write(*,*)'title=',title
       write(*,*)'l=',l
       write(*,*)'L=',lbig
       if(size(filenames) > 0)then
          write(*,'(i6.6,3a)')(i,'[',filenames(i),']',i=1,size(filenames))
       endif
       end program demo_get_args

  ## AUTHOR

        John S. Urban, 2019

  ## LICENSE

        Public Domain

  ## NAME

      get_args_fixed_length(3f) - [ARGUMENTS:M_CLI2] return keyword values
      for fixed-length string when parsing command line
      (LICENSE:PD)

  ## SYNOPSIS

      subroutine get_args_fixed_length(name,value)

       character(len=*),intent(in)  :: name
       character(len=:),allocatable :: value
       character(len=*),intent(in),optional :: delimiters

  ## DESCRIPTION

      get_args_fixed_length(3f) returns the value of a string
      keyword when the string value is a fixed-length CHARACTER
      variable.

  ## OPTIONS

      NAME   name of commandline argument to obtain the value of

      VALUE  variable to hold returned value.
             Must be a fixed-length CHARACTER variable.

      DELIMITERS  By default the delimiter for array values are comma,
                  colon, and whitespace. A string containing an alternate
                  list of delimiter characters may be supplied.

  ## EXAMPLE

  Sample program:

       program demo_get_args_fixed_length
       use M_CLI2,  only : set_args, get_args_fixed_length
       implicit none

        ! Define args
       character(len=80)   :: title
        ! Parse command line
       call set_args(' --title "my title" ')
        ! Assign values to variables
       call get_args_fixed_length('title',title)
        ! Use values
       write(*,*)'title=',title

       end program demo_get_args_fixed_length

  ## AUTHOR

        John S. Urban, 2019

  ## LICENSE

        Public Domain

  ## NAME

      get_args_fixed_size(3f) - [ARGUMENTS:M_CLI2] return keyword values
      for fixed-size array when parsing command line arguments
      (LICENSE:PD)

  ## SYNOPSIS

      subroutine get_args_fixed_size(name,value)

       character(len=*),intent(in) :: name
       [real|doubleprecision|integer|logical|complex] :: value(NNN)
          or
       character(len=MMM) :: value(NNN)

       character(len=*),intent(in),optional :: delimiters

  ## DESCRIPTION

      get_args_fixed_size(3f) returns the value of keywords for fixed-size
      arrays after set_args(3f) has been called.  On input on the command
      line all values of the array must be specified.

  ## OPTIONS

      NAME        name of commandline argument to obtain the value of

      VALUE       variable to hold returned values. The kind of the value
                  is used to determine the type of returned value. Must be
                  a fixed-size array. If type is CHARACTER the length must
                  also be fixed.

      DELIMITERS  By default the delimiter for array values are comma,
                  colon, and whitespace. A string containing an alternate
                  list of delimiter characters may be supplied.

  ## EXAMPLE

  Sample program:

       program demo_get_args_fixed_size
       use M_CLI2,  only : set_args, get_args_fixed_size
       implicit none
       integer,parameter   :: dp=kind(0.0d0)
       ! DEFINE ARGS
       real                :: x(2)
       real(kind=dp)       :: y(2)
       integer             :: p(3)
       character(len=80)   :: title(1)
       logical             :: l(4), lbig(4)
       complex             :: cmp(2)
       ! DEFINE AND PARSE (TO SET INITIAL VALUES) COMMAND LINE
       !   o only quote strings
       !   o set all logical values to F or T.
       call set_args(' &
          & -x 10.0,20.0 &
          & -y 11.0,22.0 &
          & -p -1,-2,-3 &
          & --title "my title" &
          & -l F,T,F,T -L T,F,T,F  &
          & --cmp 111,222.0,333.0e0,4444 &
          & ')
       ! ASSIGN VALUES TO ELEMENTS
          call get_args_fixed_size('x',x)
          call get_args_fixed_size('y',y)
          call get_args_fixed_size('p',p)
          call get_args_fixed_size('title',title)
          call get_args_fixed_size('l',l)
          call get_args_fixed_size('L',lbig)
          call get_args_fixed_size('cmp',cmp)
       ! USE VALUES
          write(*,*)'x=',x
          write(*,*)'p=',p
          write(*,*)'title=',title
          write(*,*)'l=',l
          write(*,*)'L=',lbig
          write(*,*)'cmp=',cmp
       end program demo_get_args_fixed_size

  Results:

  ## AUTHOR

        John S. Urban, 2019

  ## LICENSE

        Public Domain

  #### Arguments

  Type | Intent | Optional | Attributes |  | Name |
  --- | --- | --- | --- | --- | --- | ---
  character(len=*), | intent(in) |  |  | :: | keyword |
  class(*) |  |  |  | :: | generic(:) |
  character(len=*), | intent(in), | optional |  | :: | delimiters |

### public interface igets

- ### private function igs(n)

  #### Arguments

  Type | Intent | Optional | Attributes |  | Name |
  --- | --- | --- | --- | --- | --- | ---
  character(len=*), | intent(in) |  |  | :: | n |

  #### Return Value integer, allocatable, (:)

- ### private function ig()

  #### Arguments

  None

  #### Return Value integer, allocatable, (:)

### public interface lgets

- ### private function lgs(n)

  #### Arguments

  Type | Intent | Optional | Attributes |  | Name |
  --- | --- | --- | --- | --- | --- | ---
  character(len=*), | intent(in) |  |  | :: | n |

  #### Return Value logical, allocatable, (:)

- ### private function lg()

  #### Arguments

  None

  #### Return Value logical, allocatable, (:)

### public interface rgets

- ### private function rgs(n)

  #### Arguments

  Type | Intent | Optional | Attributes |  | Name |
  --- | --- | --- | --- | --- | --- | ---
  character(len=*), | intent(in) |  |  | :: | n |

  #### Return Value real, allocatable, (:)

- ### private function rg()

  #### Arguments

  None

  #### Return Value real, allocatable, (:)

### public interface sgets

- ### private function sgs(n, delims)

  #### Arguments

  Type | Intent | Optional | Attributes |  | Name |
  --- | --- | --- | --- | --- | --- | ---
  character(len=*), | intent(in) |  |  | :: | n |
  character(len=*), | intent(in), | optional |  | :: | delims |

  #### Return Value character(len=:), allocatable, (:)

- ### private function sg()

  #### Arguments

  None

  #### Return Value character(len=:), allocatable, (:)

## Functions

### public function cget(n)

#### Arguments

Type | Intent | Optional | Attributes |  | Name |
--- | --- | --- | --- | --- | --- | ---
character(len=*), | intent(in) |  |  | :: | n |

#### Return Value complex

### public function dget(n)

#### Arguments

Type | Intent | Optional | Attributes |  | Name |
--- | --- | --- | --- | --- | --- | ---
character(len=*), | intent(in) |  |  | :: | n |

#### Return Value real(kind=dp)

### public function get_subcommand() result(sub)

Sample program:

Read more…

#### Arguments

None

#### Return Value character(len=:), allocatable

### public function iget(n)

#### Arguments

Type | Intent | Optional | Attributes |  | Name |
--- | --- | --- | --- | --- | --- | ---
character(len=*), | intent(in) |  |  | :: | n |

#### Return Value integer

### public function lget(n)

#### Arguments

Type | Intent | Optional | Attributes |  | Name |
--- | --- | --- | --- | --- | --- | ---
character(len=*), | intent(in) |  |  | :: | n |

#### Return Value logical

### public function rget(n)

#### Arguments

Type | Intent | Optional | Attributes |  | Name |
--- | --- | --- | --- | --- | --- | ---
character(len=*), | intent(in) |  |  | :: | n |

#### Return Value real

### public function sget(n)

#### Arguments

Type | Intent | Optional | Attributes |  | Name |
--- | --- | --- | --- | --- | --- | ---
character(len=*), | intent(in) |  |  | :: | n |

#### Return Value character(len=:), allocatable

### public impure elemental function specified(key)

Sample program:

Read more…

#### Arguments

Type | Intent | Optional | Attributes |  | Name |
--- | --- | --- | --- | --- | --- | ---
character(len=*), | intent(in) |  |  | :: | key |

#### Return Value logical

## Subroutines

### public subroutine print_dictionary(header, stop)

Typical usage:

Read more…

#### Arguments

Type | Intent | Optional | Attributes |  | Name |
--- | --- | --- | --- | --- | --- | ---
character(len=*), | intent(in), | optional |  | :: | header |
logical, | intent(in), | optional |  | :: | stop |

### public subroutine set_args(prototype, help_text, version_text, string, prefix, ierr, errmsg)

Sample program:

Read more…

#### Arguments

Type | Intent | Optional | Attributes |  | Name |
--- | --- | --- | --- | --- | --- | ---
character(len=*), | intent(in) |  |  | :: | prototype |
character(len=*), | intent(in), | optional |  | :: | help_text(:) |
character(len=*), | intent(in), | optional |  | :: | version_text(:) |
character(len=*), | intent(in), | optional |  | :: | string |
character(len=*), | intent(in), | optional |  | :: | prefix |
integer, | intent(out), | optional |  | :: | ierr |
character(len=:), | intent(out), | optional, | allocatable | :: | errmsg |

### public impure elemental subroutine set_mode(key, mode)

Sample program:

Read more…

#### Arguments

Type | Intent | Optional | Attributes |  | Name |
--- | --- | --- | --- | --- | --- | ---
character(len=*), | intent(in) |  |  | :: | key |
logical, | intent(in), | optional |  | :: | mode |