KRACKEN(3F): The Ultimate Fortran Command Line Argument Cracker

John S. Urban (last change: Dec. 2008)

Abstract
Example of typical use
Routine Descriptions
Extended Example
Download

ABSTRACT

In Fortran 2003, GET_COMMAND(3f) provides a standard method to read command-line arguments. But this little library goes much further and lets you use Unix-like syntax very easily. You can call your command like this:

 krackenbasic -r 333.333 -f /home/urbanjs/testin -l -i 300

with very little code:

Example Usage

program krackenbasic
   use M_kracken
   character(255) filename
   logical lval

!  define command arguments, default values
!  and crack command line
   call kracken('cmd','-i 10 -r 10e3 -l .false. -f input')

!  get values
   call retrev('cmd_f',filename,iflen,ier) ! get -f FILENAME
   lval = lget('cmd_l')                    ! get -l present?
   rval = rget('cmd_r')                    ! get -r RVAL
   ival = iget('cmd_i')                    ! get -i IVAL

!  all done parsing; do something with the values
   print *, "filename=",filename(:iflen)
   print *, " i=",ival, " r=",rval, " l=",lval

end program krackenbasic

While the new (Fortran 2008) GET_COMMAND(3f) routine is very welcome, and is used in the f90+ version of kracken(3f), it does not provide what kracken(3F) does:

a standard style for parsing arguments and keywords. Admittedly, deciding on which keyword/argument syntax invokes holy wars (VERB,KEY1=VALUE,KEY2=VALUE,... vs verb -key1 value -key2 value ... , for example) but the Unix model seems to be popular lately.
a clear way to specify allowable keywords and default values
simple access to the parsed data from procedures
easy conversion from strings to numbers
easy conversion from strings to arrays

The Routines

KRACKEN(VERB,PROTOTYPE) to define your command, set defaults, and then apply the user-supplied options

 SUBROUTINE kracken(verb, string)

    ! arbitrary command name, usually 'cmd'
    CHARACTER(len=*), intent(in) ::  verb

    ! prototype command to define keywords and defaults
    ! this string is simply a list of all keywords and their
    ! default values exactly as you would type them on the
    ! command line
    CHARACTER(len=*), intent(in) :: string

 END SUBROUTINE kracken

 CALL KRACKEN('cmd','-start 1 -end 100')

RETREV(3) to get the value of a command keyword as a string

 SUBROUTINE retrev(name, val, len, ier)

    ! parameter name of form VERB_KEYWORD
    CHARACTER(len=*),intent(in) :: name

    ! returned parameter value
    CHARACTER(len=*),intent(out):: val

    ! length of returned string
    INTEGER,intent(out)  :: len

    ! error flag. Any non-zero value means an error occurred
    INTEGER,intent(out)  :: ier

 END SUBROUTINE retrev

 CALL RETREV('cmd_start',val,len,ier)

STRING_TO_REAL(STRING,VALUE) to convert a string to a number

 SUBROUTINE string_to_real(chars, valu, ierr)

    ! string representing numeric value to convert
    CHARACTER(len=*), intent(in) :: chars

    ! real value returned from reading string CHARS
    REAL, intent(out) :: valu

    ! if non-zero an error occurred
    INTEGER, intent(out) :: ierr
 END SUBROUTINE string_to_real

 val='1'
 call string_to_real(VAL,x,ierr)

DELIM(3) to split a list into single words

 SUBROUTINE delim(INLINE,array,n,icount,ibegin,iterm,ilen,dlim)
    CHARACTER(*) INLINE, dlim *(*)
    ! INLINE is the string to break into tokens

    CHARACTER array(n)*(*)
    ! array is the array to fill with tokens

    INTEGER icount, ibegin(n), iterm(n), ilen
    ! icount is how many tokens are found
    ! ibegin(1:icount) = starting column numbers for the tokens in INLINE
    ! iend(1:icount)=ending column numbers for the tokens in INLINE
    ! ilen is the position of last non-blank character in INLINE
    ! dlim is a string of single characters to use as delimiters

 END SUBROUTINE delim

If ARRAY(N) fills before reaching the end of the line the routine stops. Check "if(iend(icount) .eq. ilen)" to see if you got to the end.

There are also three convenience functions for getting simple values

      lval=lget(VERB_ARGNAME) !gets a "logical" value. 
      rval=rget(VERB_ARGNAME) !gets a "real" value.
      ival=iget(VERB_ARGNAME) !gets a "integer" value

Extended Example

The following example is a bit long compared to typical use; but exercises all the options. The command generated will have parameters -i, -r, -l, -par1, -par2, -par3, and -- . And here is a main program that does just that ...

      program krackentest
      use M_kracken

! call with an arbitrary verb name and a prototype string that defines
! allowable switch names and default values

      call kracken('mycommand',
     &' -i 10 -r 200.3 -l -par1 "#N#" -par2 -par3 10 20 30 -- ')

! that's it. You defined your command arguments and their default
! values and parsed the user-supplied command line arguments.
!
! Now you can just retrieve the values as strings using
! names of the form VERB_SWITCHNAME anywhere in your program.
! Note that the special name "VERB_oo"  is for the string
! before any switch. to see how look at the SAMPLES() procedure

      call samples()
      end

When the user types

 mycommand  one two -l -i 10 -three four -- file1 file2 file3

the program should complain about -three not being a valid option and will create names that can be used with RETREV(3f).

CALL RETREV('mycommand_oo',val,ier) ! -> sets VAL='one two'
This is thrown in on the user's command intentionally to demonstrate the existence of the -oo parameter. Often, you can ignore it exists, but the -oo option is always there, cannot have a default if any other parameter is specified, and represents anything before the first keyword (unless explicitly declared). There's one in every crowd. This behavior is actually quite useful, but unique. The rest act in an intuitive fashion for anyone familiar with AEGIS/UNIX/Linux:
CALL RETREV('mycommand_i',val,ier) ! ->sets VAL=' 10'
CALL RETREV('mycommand_r',val,ier) ! ->sets VAL=' 200.3'
CALL RETREV('mycommand_l',val,ier) ! ->sets VAL=''
CALL RETREV('mycommand_par1',val,ier) ! ->sets VAL=' #N#'
CALL RETREV('mycommand_par2',val,ier) ! ->sets VAL=''
CALL RETREV('mycommand_par3',val,ier) ! ->sets VAL='10 20 30'
CALL RETREV('mycommand_-',val,ier) ! ->sets VAL='file1 file2 file3'

So lets take a look at something that calls RETREV(3F) and the convenience functions (LGET(),IGET(),RGET)). For completeness, I show the use of string_to_real(3F) to convert the string returned by RETREV(3F) to a number; and the use of DELIM(3F) to break down a returned list into words. Note that as long as the routines are not called many times (because they are slower than common alternatives), you can just put the calls to RETREV() where you need the information instead of passing the values around or putting them into a COMMON or MODULE.

C=======================================================================--------
      SUBROUTINE samples
      USE M_kracken

      CHARACTER*255 value
      LOGICAL lget,lval

C everything before any switch is always VERB_oo
      call RETREV('mycommand_oo',value,len,ier)
      write(*,*)'before any switch=',value(:len)

C Getting an integer from -i value
      inumber=IGET('mycommand_i')
      write(*,*)'value for -i =',inumber,' divided by 2 is ',inumber/2

C Getting a real number from -r value 
      anumber=RGET('mycommand_r')
      write(*,*)'value for -r =',anumber,'divided by 2 is ',anumber/2

C Getting a logical value from -l value 
      lval=LGET('mycommand_l')
      write(*,*)'value for -l =',lval

C Getting a string (with a default) from -par1
      call RETREV('mycommand_par1',value,len,ier)
      write(*,*)'value for -par1 =',value(:len)

C Getting a string (with no default) from -par2
      call RETREV('mycommand_par2',value,len,ier)
      write(*,*)'value for -par2 =',value(:len)

C Getting a string with a multi-word default and splitting it from -par3
      call listem('mycommand_par3','-par3',.true.)

C Convention for last parameter because multi-word unquoted values are allowed
      call listem('mycommand_-','--'.false.)

      end
C=======================================================================--------
      SUBROUTINE listem(keyword,label,toreal)
      USE M_kracken
C     Just getting fancy and showing the use of DELIM(3F)
C     SAMPLE that decomposes list of strings and optionally, numbers
C     and prints it.
C     Delimit with space, comma, or colon
      LOGICAL toreal
      CHARACTER*(*) keyword
      CHARACTER*(*) label
      CHARACTER*255 value

C     for DELIM call if you want to break down a list
      CHARACTER*255 array(132)
      INTEGER ibegin(132)
      INTEGER iterm(132)

C     get the value of the keyword and the length
      CALL RETREV(keyword,value,len,ier)
      WRITE(*,*)'value for ',label,'=',value(:len)
C     split the list into one word per array
      call DELIM(value,array,132,igot,ibegin,iterm,ilen,' ,:')
C     print and optionally convert each word into a numeric value
      DO i10=1,igot
         WRITE(*,*)i10,') ',array(i10)(:julen(array(i10)))
         IF(toreal)THEN
            CALL string_to_real(array(i10),anumber,ier)
            IF(ier.eq.0)THEN
               WRITE(*,*)' which is a number'
            ELSE
               WRITE(*,*) ' which is not a number'
            ENDIF
         ENDIF
      ENDDO
      RETURN
      END
C=======================================================================--------

This shows the expected output of the execution:

 # Remember the command was defined by
 # call kracken('mycommand',&
 # &' -i 10 -r 200.3 -l -par1 "#N#" -par2 -par3 10 20 30 -- ')
 #
 # user types
 mycommand  one two -l -i 10 -three four -- file1 file2 file3
 # response should be
 >:E-R-R-O-R: UNKNOWN OPTION mycommand_three
 before any switch=one two
 value for -i =10
 divided by 2 is  5
 value for -r =200.3
 divided by 2 is  100.15
 value for -par1 =#N#
 value for -par2 =
 value for -par3=10 20 30
 1) 10
  which is a number
 2) 20
  which is a number
 3) 30
  which is a number
 value for --=file1 file2 file3
 1) file1
 2) file2
 3) file3

If you read this far, you probably want the source. You'll be happy to know it's annotated more thoroughly than this example is.

To get a demonstration program and the source for the kracken library download the following source files:

  # compile a demo program and the source for kracken(3F) and
  # associated routines
  g95 M_kracken.f90 krackentest.f90
  # or if you prefer ANSI-77 syntax an alternate (static) version is available
  g77   krackentest.f   kracken.f

Download files

f90+ files(preferred)

EXE/krackentest.f90 -- f90+ test of all routines
EXE/krackentest2.f90 -- f90+ test of common basic usage
src/M_kracken.f90 -- f90+ library source

f77+ files (considered frozen)

src/kracken.f -- f77 library source
EXE/krackentest.f -- f77+ test of all routines
EXE/krackentest2.f -- f77+ test of common basic usage

The f77 version found here will not be changing

My purpose here is to make something very simple and portable that others can use reliably. I have made and used variants of kracken for years; for me it was just calls to mostly-f77 libraries used for a variety of other purposes. While extracting parts of the library to make a simple stand-alone version I realized anyone using this would be better served by using clean f90+ syntax. Lately being "clean" means I can compile it with an "F" compiler (if it doesn't use stuff "past" F). So I won't be maintaining the public f77 version, as I have a bigger better one I will be maintaining. And the whole idea of libraries is to not have to maintain duplicate code.

If you are having problems

The routine GET_COMMAND_ARGUMENTS() is the only one that actually reads from the command line. The f90+ version assumes your compiler has GET_COMMAND_ARGUMENTS(). The f77+ version assumes your compiler has GETARGS() and IARGC(). If neither is the case and you don't know how to make your own GET_COMMAND_ARGUMENTS() look-alike, It is VERY likely you can get a GET_COMMAND_ARGUMENT() from the F2KCLI package from WINTERACTER.

You may note that the parsing rules are not identical to Unix, although very similar. There is no way to terminate a keyword except by starting a new keyword; and the keyword -oo is implied after the verb; and you cannot combine keywords (-ir is not equivalent to -i -r, which is sometimes allowed on Unix commands). You may find the way to include a literal double-quote character (") is the most unlike Unix (see code comments for details).

This is a simplified version of command parsing routines modeled on libJSU.a; which has been everywhere (NOS, SCOPE, VMS, UNICOS, NextStep, HP-UX, SunOS, Solaris, AIX, ULTRIX, Tru64, CygWin, OpenBSD, Linux...). Note that the routines work on any string, not just one obtained from the command line. When used to parse "commands" from a file, they can be used to provide self-describing input which can best be described as a portable Unix-style NAMELIST replacement (developed long before NAMELIST was standardized).

Things not dealt with in this version that have been in others

If on a 64-bit machine might want to make string_to_real real*8
easily display allowed parameters and default values
FORTRAN math expressions are not allowed as numeric values. Easily added with JUCALC().
a standard way to request parameter prompting with help text, allowing both a command-line and screen-panel interface (like CDC's CCL and TDU interfaces on NOS, for those who remember -- not matched to this day for simple use from Fortran or for providing self-documenting shell scripts).
For why I didn't use GET_COMMAND(1) it's because it is not clear in the standard if the command name is included; what happens if the command name has spaces or other characters in it, how long the string has to be to allow the command name, ... (as of Dec 20, 2008 see my diatribe on GET_COMMAND()).
A clean "F" version is overdue in that I don't think there is a FORTRAN77-only platform left I need to worry about; but I have a bad case of IINBDFI ("If It's Not Broke, Don't Fix It", of course).

Updates and Footnotes (See Also's, Thoughts about Next Time, ...)

Alternatives:

Almost every Fortran supports some form of GETENV(). You can create a script to parse the command options and then set corresponding environmental variables before executing the Fortran program. Then the program just calls GETENV() to get string values. If there is no GETENV() available, the script can write information to a file that the program reads to get the same result.

Some Fortran programming environments now support a look-alike for the getopts(1) Unix command or something like it.

A package called SNG does something like this, but more like getopt_long(3); according to the documentation.

Fortran 2003 now supplies a standard way for Fortran to call C routines; but what ever happened to the excellent idea proposed in The POSIX FORTRAN 77 Language Interfaces Standard IEEE Std 1003.9-1992 (POSIX.a) ; which " defines a standardized interface for accessing the system services of IEEE Std 1003.1-1990 (POSIX.1), and supports routines to access constructs not directly accessible with FORTRAN 77."? I made look-alikes of these routines for years, optimistically awaiting them on all FORTRAN compilers; but Cray was the only one that came through that I know of.

The F2KCLI package from WINTERACTER provides GET_COMMAND for all publicly known Fortran compilers

GNU now supplies a standard parsing routine called "getopt_long", that I should probably emulate the rules of; as it makes a valiant attempt at creating a standard command syntax for Unix and Unix-like platforms.