Manual Reference Pages - M_CLI2 (3m_cli2)

NAME

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

Synopsis
Description
Example
Author
License
See Also

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:

    program minimal
    use M_CLI2,  only : set_args, lget, rget, sgets
    implicit none
    real    :: x, y
    integer :: i
    character(len=:),allocatable :: version_text(:), help_text(:)
    character(len=:),allocatable :: filenames(:)
       ! define and crack command line.
       ! creates argument --yvalue with short name y with default value 0
       ! creates argument --xvalue with short name x with default value 0
       ! creates boolean argument
       call setup() ! define help text and version text
       call set_args(’ --yvalue:y 0.0 --xvalue:x 0.0 --debug F’,&
            & help_text=help_text,&
            & version_text=version_text)
       ! 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() ! sgets(3f) 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
    contains
    subroutine setup()

    help_text=[character(len=80) :: &
                & "wish I put instructions", &
                & "here I suppose.        ", &
                & " "]

    version_text=[character(len=80) :: "version 1.0","author: me"]

    end subroutine setup
    end program minimal

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

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,parameter            :: dp=kind(0.0d0)
    integer                      :: i
     !
     ! 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

Results:

 >  x=1.00000000     y=2.00000000     z=3.00000000       6.00000000
 >  p=  -1.00000000      -2.00000000      -3.00000000
 >  point=   11.109999999999999 22.219999999999999 33.329999999999998
 >  title=my title
 >  label=
 >  l= F
 >  L= F
 >  logicals= F F F F F
 >  logi= F T F

AUTHOR

John S. Urban, 2019

LICENSE

Public Domain

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