command_line Module Reference

Data Types
type	cmd_arg
	type containing a key-value pair More...
interface	get_arg
	read arguments by name or number More...
type	str_wrapper
	wrapper to allow array of allocatable strings More...

Functions/Subroutines
subroutine	parse_args ()
	Parse out command line args.
subroutine	initial_parse
	helper function - do a parse if it hasn't been done yet
integer function, public	arg_count ()
	get the number of arguments note: total count may not match command_argument_count due to parsing key=value syntax!
logical function	get_arg_num_logical (num, val, exists)
	read by number for logical values
logical function	get_arg_name_logical (name, val, exists)
	Read by name for logical values.
logical function	get_arg_num_dbl (num, val, exists)
	read by number for double precision values
logical function	get_arg_name_dbl (name, val, exists)
	read by name for double precision values
logical function	get_arg_num_float (num, val, exists)
	Read by number for single precision (float) values.
logical function	get_arg_name_float (name, val, exists)
	read by name for single precision (float) values
logical function	get_arg_num_int (num, val, exists)
	read by number for integer values
logical function	get_arg_name_int (name, val, exists)
	read by name for integer values
logical function	get_arg_num_long (num, val, exists)
	read by number for long integer values
logical function	get_arg_name_long (name, val, exists)
	read by name for long integer values
logical function	get_arg_num_str (num, val, exists)
	read by number for string/character values
logical function	get_arg_name_str (name, val, exists)
	read by name for string values
logical function, public	arg_present (name, has_value)
	check presence of an argument by name
type(str_wrapper) function, dimension(:), allocatable, public	dump_names ()
	get all the argument names (by copy) order will probably match input order, but this is not guaranteed
character(len=:) function, allocatable, public	get_arg_value (name, exists)
	lookup an argument by name and return the value as an (allocatable) string if the name is not present, an empty string is returned

Variables
logical	initial_parse_done = .false.
type(cmd_arg), dimension(:), allocatable, private	all_args
	the argument list
integer, private	num_args = 0
	the number of arguments
integer, parameter	max_string_len = 200

Function/Subroutine Documentation

arg_count()

integer function, public command_line::arg_count

get the number of arguments note: total count may not match command_argument_count due to parsing key=value syntax!

Definition at line 229 of file command_line.f90.

    integer :: arg_count
 
    call initial_parse
    arg_count = num_args

Here is the call graph for this function:

Here is the caller graph for this function:

arg_present()

logical function, public command_line::arg_present	(	character(len=*), intent(in)	name,
		logical, intent(out), optional	has_value )

check presence of an argument by name

Author

H. Ratcliffe

Date

2024

Parameters

name	argument name to look up
has_value	whether this argument has a defined value (also .false. if not present)

Returns

true if present, false if not

Definition at line 727 of file command_line.f90.

 
   logical :: found
   character(len=*), intent(in) :: name
   logical, intent(out), optional :: has_value
   integer :: i
 
    call initial_parse
 
    found = .false.
    if(present(has_value)) has_value = .false.
    do i = 1, num_args
      if(all_args(i)%name == trim(adjustl(name))) then
        found = .true.
        if(present(has_value)) has_value = all_args(i)%has_value
        exit
      endif
    end do
 

Here is the call graph for this function:

dump_names()

type(str_wrapper) function, dimension(:), allocatable, public command_line::dump_names

get all the argument names (by copy) order will probably match input order, but this is not guaranteed

Author

H. Ratcliffe

Date

2024

Returns

array of str_wrapper types containing all argument names

Definition at line 756 of file command_line.f90.

    type(str_wrapper), dimension(:), allocatable :: dump_names
    integer :: i
 
    ! do this the long way again to support non implicit allocations
    allocate(dump_names(num_args))
    do i = 1, num_args
      allocate(dump_names(i)%str, source =all_args(i)%name)
    end do
 

Here is the call graph for this function:

Here is the caller graph for this function:

get_arg_name_dbl()

logical function command_line::get_arg_name_dbl ( character(len=*), intent(in) name, real(kind=real64), intent(inout) val, logical, intent(out), optional exists )

private

read by name for double precision values

Author

H. Ratcliffe

Date

2024

Parameters

name	argument name to look up
val	value to read into
exists	whether the name was found

Returns

true if the name is found and parsed, false otherwise

Definition at line 379 of file command_line.f90.

 
    logical :: get_arg_name_dbl
    character(len=*), intent(in) :: name
    real(kind=real64), intent(inout) :: val
    integer :: i
    logical, intent(out), optional :: exists
    logical :: found
    integer :: ierr
 
    call initial_parse
 
    found = .false.
    ! our cmd_arg type is already initialised to the sentinel
    do i = 1, num_args
      if(all_args(i)%name == trim(adjustl(name))) then
        found = .true.
        read(all_args(i)%value, *, iostat=ierr) val
        exit
      end if
    end do
 
    if(present(exists)) then
      exists = found
    end if
 
    ! return value is whether value is found and correctly parsed
    get_arg_name_dbl = (found .and. (ierr == 0))
 

Here is the caller graph for this function:

get_arg_name_float()

logical function command_line::get_arg_name_float ( character(len=*), intent(in) name, real(kind=real32), intent(inout) val, logical, intent(out), optional exists )

private

read by name for single precision (float) values

Author

H. Ratcliffe

Date

2024

Parameters

name	argument name to look up
val	value to read into
exists	whether the name was found

Returns

true if the name is found and parsed, false otherwise

Definition at line 453 of file command_line.f90.

    logical :: get_arg_name_float
    character(len=*), intent(in) :: name
    real(kind=real32), intent(inout) :: val
    real(kind=real64) :: tmp
    logical, intent(out), optional :: exists
 
    get_arg_name_float = get_arg_name_dbl(name, tmp, exists)
    if( abs(tmp) < huge(val)) then
      !value in range. convert. note: there may be precision loss
      val = real(tmp, kind=real32)
    else
      !value out of range, can't be parsed
      get_arg_name_float  = .false.
    end if
 

Here is the caller graph for this function:

get_arg_name_int()

logical function command_line::get_arg_name_int ( character(len=*), intent(in) name, integer(kind=int32), intent(inout) val, logical, intent(out), optional exists )

private

read by name for integer values

Author

H. Ratcliffe

Date

2024

Parameters

name	argument name to look up
val	value to read into
exists	whether the name was found

Returns

true if the name is found and parsed, false otherwise

Definition at line 521 of file command_line.f90.

 
    logical :: get_arg_name_int
    character(len=*), intent(in) :: name
    integer(kind=int32), intent(inout) :: val
    integer :: i
    logical, intent(out), optional :: exists
    logical :: found
    integer :: ierr
 
    call initial_parse
 
    found = .false.
    ! our cmd_arg type is already initialised to the sentinel
    do i = 1, num_args
      if(all_args(i)%name == trim(adjustl(name))) then
        found = .true.
        read(all_args(i)%value, *, iostat=ierr) val
        exit
      end if
    end do
 
    if(present(exists)) then
      exists = found
    end if
 
    ! return value is whether value is found and correctly parsed
    get_arg_name_int = (found .and. (ierr == 0))
 

Here is the caller graph for this function:

get_arg_name_logical()

logical function command_line::get_arg_name_logical ( character(len=*), intent(in) name, logical, intent(inout) val, logical, intent(out), optional exists )

private

Read by name for logical values.

Note : a flag (name with no '=value' part) will parse as .true. if present, and .false. if not

Author

H. Ratcliffe

Date

2024

Parameters

name	Argument name to look up
val	Value to read into
exists	Whether the name was found

Returns

true if the name is found and parsed, false otherwise

Definition at line 291 of file command_line.f90.

 
    logical :: get_arg_name_logical
    character(len=*), intent(in) :: name
    logical, intent(inout) :: val
    integer :: i
    logical, intent(out), optional :: exists
    logical :: found
    integer :: ierr
 
    call initial_parse
 
    found = .false.
    val = .false.
    ierr = 0
    ! our cmd_arg type is already initialised to the sentinel
    do i = 1, num_args
      if(all_args(i)%name == trim(adjustl(name))) then
        found = .true.
        if(all_args(i)%has_value) then
          read(all_args(i)%value, *, iostat=ierr) val
        else
          val = .true.
        end if
        exit
      end if
    end do
 
    if(present(exists)) then
      exists = found
    end if
 
    ! return value is whether value is found and correctly parsed
    get_arg_name_logical = (found .and. (ierr == 0))
 

Here is the caller graph for this function:

get_arg_name_long()

logical function command_line::get_arg_name_long ( character(len=*), intent(in) name, integer(kind=int64), intent(inout) val, logical, intent(out), optional exists )

private

read by name for long integer values

Author

H. Ratcliffe

Date

2024

Parameters

name	argument name to look up
val	value to read into
exists	whether the name was found

Returns

true if the name is found and parsed, false otherwise

Definition at line 601 of file command_line.f90.

 
    logical :: get_arg_name_long
    character(len=*), intent(in) :: name
    integer(kind=int64), intent(inout) :: val
    integer :: i
    logical, intent(out), optional :: exists
    logical :: found
    integer :: ierr
 
   call initial_parse
 
    found = .false.
    ! our cmd_arg type is already initialised to the sentinel
    do i = 1, num_args
      if(all_args(i)%name == trim(adjustl(name))) then
        found = .true.
        read(all_args(i)%value, *, iostat=ierr) val
        exit
      end if
    end do
 
    if(present(exists)) then
      exists = found
    end if
 
    ! return value is whether value is found and correctly parsed
    get_arg_name_long = (found .and. (ierr == 0))
 

Here is the caller graph for this function:

get_arg_name_str()

logical function command_line::get_arg_name_str ( character(len=*), intent(in) name, character(len=*), intent(inout) val, logical, intent(out), optional exists )

private

read by name for string values

Note: if the string passed is shorter than the value, it will be truncated if the length is not known use get_arg_value to get an allocatable string

Author

H. Ratcliffe

Date

2024

Parameters

name	argument name to look up
val	value to read into
exists	whether the name was found - this is already contained in the return value, but is given for consistency with the other members

Returns

true if the name is found and parsed, false otherwise

Definition at line 686 of file command_line.f90.

 
    logical :: get_arg_name_str
    character(len=*), intent(in) :: name
    character(len=*), intent(inout) :: val
    integer :: i
    logical, intent(out), optional :: exists
    logical :: found
 
    call initial_parse
 
    found = .false.
    do i = 1, num_args
      if(all_args(i)%name == trim(adjustl(name))) then
        found = .true.
        val = all_args(i)%value
        exit
      end if
    end do
 
    if(present(exists)) then
      exists = found
    end if
 
    ! return value is whether value is found and correctly parsed
    get_arg_name_str = found
 

Here is the caller graph for this function:

get_arg_num_dbl()

logical function command_line::get_arg_num_dbl ( integer, intent(in) num, real(kind=real64), intent(inout) val, logical, intent(out), optional exists )

private

read by number for double precision values

Author

H. Ratcliffe

Date

2024

Parameters

num	argument number to read
val	value to read into
exists	whether the name was found

Returns

true if the name is found and parsed, false otherwise

Definition at line 340 of file command_line.f90.

 
    logical :: get_arg_num_dbl
    integer, intent(in) :: num
    real(kind=real64), intent(inout) :: val
    logical, intent(out), optional :: exists
    logical :: found
    integer :: ierr
 
    call initial_parse
 
    found = .false.
    ! check requested number is in range
    if(num <= num_args .and. num > 0) then
      ! read it from string into value
      read(all_args(num)%value, *, iostat=ierr) val
      found = .true.
    end if
 
    if(present(exists)) then
      exists = found
    end if
 
    ! return value is whether value is found and correctly parsed
    get_arg_num_dbl = (found .and. (ierr == 0))
 

Here is the caller graph for this function:

get_arg_num_float()

logical function command_line::get_arg_num_float ( integer, intent(in) num, real(kind=real32), intent(inout) val, logical, intent(out), optional exists )

private

Read by number for single precision (float) values.

Author

H. Ratcliffe

Date

2024

Parameters

num	argument number to read
val	value to read into
exists	whether the name was found

Returns

true if the name is found and parsed, false otherwise

Definition at line 424 of file command_line.f90.

    logical :: get_arg_num_float
    integer, intent(in) :: num
    real(kind=real32), intent(inout) :: val
    real(kind=real64) :: tmp
    logical, intent(out), optional :: exists
 
    get_arg_num_float = get_arg_num_dbl(num, tmp, exists)
    if( abs(tmp) < huge(val)) then
      !value in range. convert. note: there may be precision loss
      val = real(tmp, kind=real32)
    else
      !value out of range, can't be parsed
      get_arg_num_float  = .false.
    end if
 

Here is the caller graph for this function:

get_arg_num_int()

logical function command_line::get_arg_num_int ( integer, intent(in) num, integer(kind=int32), intent(inout) val, logical, intent(out), optional exists )

private

read by number for integer values

Author

H. Ratcliffe

Date

2024

Parameters

num	argument number to read
val	value to read into
exists	whether the name was found

Returns

true if the name is found and parsed, false otherwise

Definition at line 482 of file command_line.f90.

 
    logical :: get_arg_num_int
    integer, intent(in) :: num
    integer(kind=int32), intent(inout) :: val
    logical, intent(out), optional :: exists
    logical :: found
    integer :: ierr
 
    call initial_parse
 
    found = .false.
    ! check requested number is in range
    if(num <= num_args .and. num > 0) then
      ! read it from string into value
      ! we don't need to specify the format in general
      read(all_args(num)%value, *, iostat=ierr) val
      found = .true.
    end if
 
    if(present(exists)) then
      exists = found
    end if
 
    ! return value is whether value is found and correctly parsed
    get_arg_num_int = (found .and. (ierr == 0))
 

Here is the caller graph for this function:

get_arg_num_logical()

logical function command_line::get_arg_num_logical ( integer, intent(in) num, logical, intent(inout) val, logical, intent(out), optional exists )

private

read by number for logical values

Author

H. Ratcliffe

Date

2024

Parameters

num	argument number to read
val	value to read into
exists	whether the name was found

Returns

true if the name is found and parsed, false otherwise

Definition at line 249 of file command_line.f90.

 
    logical :: get_arg_num_logical
    integer, intent(in) :: num
    logical, intent(inout) :: val
    logical, intent(out), optional :: exists
    logical :: found
    integer :: ierr
 
    call initial_parse
 
    found = .false.
    ! check requested number is in range
    if(num <= num_args .and. num > 0) then
      ! read it from string into value
      read(all_args(num)%value, *, iostat=ierr) val
      found = .true.
    end if
 
    if(present(exists)) then
      exists = found
    end if
 
    ! return value is whether value is found and correctly parsed
    get_arg_num_logical = (found .and. (ierr == 0))
 

Here is the caller graph for this function:

get_arg_num_long()

logical function command_line::get_arg_num_long ( integer, intent(in) num, integer(kind=int64), intent(inout) val, logical, intent(out), optional exists )

private

read by number for long integer values

Author

H. Ratcliffe

Date

2024

Parameters

num	argument number to read
val	value to read into
exists	whether the name was found

Returns

true if the name is found and parsed, false otherwise

Definition at line 562 of file command_line.f90.

 
    logical :: get_arg_num_long
    integer, intent(in) :: num
    integer(kind=int64), intent(inout) :: val
    logical, intent(out), optional :: exists
    logical :: found
    integer :: ierr
 
    call initial_parse
 
    found = .false.
    ! check requested number is in range
    if(num <= num_args .and. num > 0) then
      ! read it from string into value
      ! we don't need to specify the format in general
      read(all_args(num)%value, *, iostat=ierr) val
      found = .true.
    end if
 
    if(present(exists)) then
      exists = found
    end if
 
    ! return value is whether value is found and correctly parsed
    get_arg_num_long = (found .and. (ierr == 0))
 

Here is the caller graph for this function:

get_arg_num_str()

logical function command_line::get_arg_num_str ( integer, intent(in) num, character(len=*), intent(inout) val, logical, intent(out), optional exists )

private

read by number for string/character values

Author

H. Ratcliffe

Date

2024

Parameters

num	argument number to read
val	value to read into
exists	whether the name was found - this is already contained in the return value, but is given for consistency with the other members

Returns

true if the name is found and parsed, false otherwise

Definition at line 643 of file command_line.f90.

 
    logical :: get_arg_num_str
    integer, intent(in) :: num
    character(len=*), intent(inout) :: val
    logical, intent(out), optional :: exists
    logical :: found
 
    call initial_parse
 
    found = .false.
    ! check requested number is in range
    if(num <= num_args .and. num > 0) then
      ! read it from string into value
      ! we don't need to specify the format in general
      val = all_args(num)%value
      found = .true.
    end if
 
    if(present(exists)) then
      exists = found
    end if
 
    ! return value is whether value is found and correctly parsed
    get_arg_num_str = found
 

Here is the caller graph for this function:

get_arg_value()

character(len=:) function, allocatable, public command_line::get_arg_value	(	character(len=*), intent(in)	name,
		logical, intent(out), optional	exists )

lookup an argument by name and return the value as an (allocatable) string if the name is not present, an empty string is returned

Author

H. Ratcliffe

Date

2024

Parameters

name	argument name to look up
exists	whether the name was found

Returns

the string value associated with the given name

Definition at line 779 of file command_line.f90.

 
    character(len=:), allocatable :: get_arg_value
    character(len=*), intent(in) :: name
    logical, intent(out), optional :: exists
    integer :: i
    logical :: found
 
    call initial_parse
 
    found = .false.
 
    do i = 1, num_args
      if(all_args(i)%name .eq. trim(adjustl(name))) then
        allocate(get_arg_value, source=all_args(i)%value)
        found = .true.
        exit
      end if
    end do
 
    ! return empty string, not unallocated one.
    if(.not. allocated(get_arg_value)) allocate(character(len=0) :: get_arg_value)
    if(present(exists)) then
      exists = found
    end if
 

Here is the call graph for this function:

Here is the caller graph for this function:

initial_parse()

subroutine command_line::initial_parse

private

helper function - do a parse if it hasn't been done yet

Definition at line 217 of file command_line.f90.

 
    if(.not. initial_parse_done) then
      call parse_args
      initial_parse_done = .true.
    end if
 

Here is the call graph for this function:

Here is the caller graph for this function:

parse_args()

subroutine command_line::parse_args

private

Parse out command line args.

This function can be called multiple times and will freshly parse all arguments each time we assume these are entered as 'name=value'. If there is no '=' sign, we set an empty value

Author

H. Ratcliffe

Date

2024

Definition at line 101 of file command_line.f90.

 
    ! strictly we can't be sure any max_string_len is enough
    ! but for command-line args it's enough if we're sensible
    ! we wont overflow, but our strings may get truncated
    ! we'll print an warning, since this is probably unintended input
 
    ! note: some codes have reason to disable implicit re-allocation so we
    ! take the extra effort to allocate all our strings manually
 
    integer :: i_arg, i_tok, indx
    type(cmd_arg), dimension(:), allocatable :: all_args_tmp
    character(len=max_string_len) :: arg, tmp, tmp_name, tmp_val
    integer :: arg_in_length, tmp_len
    logical :: truncated
 
    truncated = .false.
 
    num_args = command_argument_count()
    if(num_args > 0) then
 
      ! if this is not the first call, all_args may be already allocated
      ! deallocate if needed, and allocate to sufficient size
      ! will be trimmed to actual size after parsing
      if(allocated(all_args)) deallocate(all_args)
      allocate(all_args(num_args))
 
      i_arg = 1 !index of current arg
      i_tok = 1 ! index of current input token
      ! loop over all arguments and extract
      do while (i_tok <= num_args)
        ! first extract name and value parts in all cases
        ! this consumes 1, 2 or 3 tokens depending on spaces
 
        call get_command_argument(i_tok, arg, length=arg_in_length)
        i_tok = i_tok + 1
 
        if(arg_in_length > max_string_len) truncated = .true.
 
        ! location of the '=' sign
        ! if not found, return value of this is 0
        indx = index(arg, '=')
 
        !look at next chars - remove all whitespace
        tmp = adjustl(arg(indx+1:))
        tmp_len = len_trim(tmp)
        if(indx > 1 .and. tmp_len > 0) then
          ! all characters after '='
          tmp_val = tmp
          ! all characters up to '=', not including it
          ! but with any leading spaces removed
          tmp_name = adjustl(arg(1:indx-1))
        else if(indx > 1) then
          ! have an '=' but no following value
          ! consume next token
          call get_command_argument(i_tok, tmp, length=arg_in_length)
          i_tok = i_tok + 1
          if(arg_in_length > max_string_len) truncated = .true.
 
          tmp_val = adjustl(tmp)
          tmp_name = adjustl(arg(1:indx-1))
        else   ! have not yet found the equals!
          ! set name, then hunt value...
          tmp_name = adjustl(arg)
 
          !peek next token - will need either 0, 1 or 2 more
          call get_command_argument(i_tok, tmp, length=arg_in_length)
          if(arg_in_length > max_string_len) truncated = .true.
 
          indx = index(adjustl(tmp), '=')
          if(indx /= 1) then
            ! next token does not lead with '=', assume this is a flag and
            ! do not consume next. set value for clarity, and mark
            tmp_val = ""
            all_args(i_arg)%has_value = .false.
          else
            ! consume this one and possibly one more
            i_tok = i_tok + 1
            if(len_trim(adjustl(tmp)) > 1) then
              !this token has content following the '='
              tmp_val = adjustl(tmp(2:))
            else
              ! consume another
              call get_command_argument(i_tok, tmp, length=arg_in_length)
              i_tok = i_tok + 1
              if(arg_in_length > max_string_len) truncated = .true.
 
              tmp_val = adjustl(tmp)
            end if
          end if
        end if
 
        ! explicitly allocate and set the values
        allocate(character(len=len_trim(tmp_name)) :: all_args(i_arg)%name)
        all_args(i_arg)%name = trim(tmp_name)
        allocate(character(len=len_trim(tmp_val)) :: all_args(i_arg)%value)
        all_args(i_arg)%value = trim(tmp_val)
 
        i_arg = i_arg + 1
      end do
      !i_arg is now the actual parsed count
      !shrink array to get rid of excess unfilled space
      num_args = i_arg-1
      call move_alloc(all_args, all_args_tmp)
      allocate(all_args(num_args))
      all_args = all_args_tmp(1:num_args)
      deallocate(all_args_tmp)
    endif
 
    if(truncated) print'(a,i0, a)', "warning: very long argument truncated. to support arguments&
   & longer than ", max_string_len, " increase the max_string_len parameter"
 
 

Here is the caller graph for this function:

Variable Documentation

all_args

type(cmd_arg), dimension(:), allocatable, private command_line::all_args

private

the argument list

Definition at line 83 of file command_line.f90.

  type(cmd_arg), dimension(:), allocatable :: all_args

initial_parse_done

logical command_line::initial_parse_done = .false.

private

Definition at line 41 of file command_line.f90.

  logical :: initial_parse_done = .false.

max_string_len

integer, parameter command_line::max_string_len = 200

private

Definition at line 86 of file command_line.f90.

  integer, parameter :: max_string_len = 200

num_args

integer, private command_line::num_args = 0

private

the number of arguments

Definition at line 85 of file command_line.f90.

  integer :: num_args = 0