Keyword arguments

A call can name the arguments it passes: call draw(width=5, label="box") says which dummy gets which value, and from then on the order in the call is free. The form costs one word per argument and pays it back in a call a reader can check without opening the procedure. This lesson writes the three shapes: all keywords, keywords in another order, and the mixture of both.

A call by name

The name before the equals sign is the dummy argument of the procedure, not a variable of the caller. The compiler matches it, so a call with keywords can only be compiled where the interface is known, which is the usual case for a module procedure or a contained one.

The file keyword.f90:

program keyword_demo implicit none call draw(width=5, label="box") call draw(label="line", width=3) call draw(4, "dot") contains subroutine draw(width, label) integer, intent(in) :: width character(len=*), intent(in) :: label print '(a,a,i0)', trim(label), " width = ", width end subroutine draw end program keyword_demo

gfortran -Wall -Wextra -std=f2018 keyword.f90 -o keyword
./keyword

box width = 5
line width = 3
dot width = 4

The first two calls pass the same two values in different orders and produce the output their names promise; the third passes them by position, which is the form every earlier lesson used. All three are the same subroutine call.

Order does not matter

With keywords the order of the arguments in the call is the order the reader chose. A call that passes an optional argument and skips an earlier one has to use a keyword, and a call that names every argument can put the important one first, which is the one habit worth taking from this lesson.

The rule that does not bend is the mixing rule: once a call starts with keywords, every later argument must be a keyword too, and a positional argument may not follow a keyword. A call written entirely by position stays valid forever, which is why a library that many programs call keeps the positional form for its first arguments.

Positional then keyword

The two forms mix in one direction: positional arguments first, keywords after. The program below calls one subroutine three ways, once with every argument by position and once with the last one by name.

program mixed_demo implicit none call area(3.0, 4.0, "rect") call area(3.0, 4.0, shape="tri") call area(b=6.0, a=2.0, shape="rect") contains subroutine area(a, b, shape) real, intent(in) :: a, b character(len=*), intent(in) :: shape real :: s if (shape == "tri") then s = 0.5 * a * b else s = a * b end if print '(a,a,f6.2)', trim(shape), " area : ", s end subroutine area end program mixed_demo

gfortran -Wall -Wextra -std=f2018 mixed.f90 -o mixed
./mixed

rect area : 12.00
tri area : 6.00
rect area : 12.00

The third call passes the two numbers in the order b, a and the subroutine receives them in the right places because the names say so. A right triangle of 2 by 6 and a rectangle of 2 by 6 would differ, and this call is the one where a reader would otherwise have to check the argument list to know which is which.

A keyword that is not there

A misspelt keyword is a compile error, and gfortran names the nearest real argument:

program badkw implicit none call draw(widthh=5, label="box") contains subroutine draw(width, label) integer, intent(in) :: width character(len=*), intent(in) :: label print *, trim(label), width end subroutine draw end program badkw

gfortran -Wall -Wextra -std=f2018 badkw.f90 -o badkw

badkw.f90:4:19:

4 | call draw(widthh=5, label="box")
| 1
Error: Keyword argument 'widthh' at (1) is not in the procedure; did you mean 'width'?

The message is the reason to prefer keywords in a long argument list: a typo in a positional call is a value in the wrong place, which compiles whenever the types agree, and the same typo in a keyword call is a line with the fix in it.

Why keyword calls are worth it

A call of six positional arguments is unreadable without the procedure open beside it: call solve(n, 1.0e-8, 100, .true., 0, out) says nothing. The same call with names says what the numbers are, and the compiler checks that each name exists and each type matches, so the documentation cannot go stale.

The habit that follows: write the small, frequently called procedures positionally, because a call such as sqrt(x) is clearer short; write a call with more than three arguments, or with any argument whose meaning is a number, with keywords. The two forms cost the same at run time.

Exercises

  1. Call draw with the label first and the width second by keyword. Does the output change?
  2. Write a call that passes a positional argument after a keyword. What does the compiler say?
  3. Rename the dummy width to columns and leave the calls alone. Which lines stop compiling?
  4. Add a fourth argument to area with a default and call the subroutine with only the three old arguments. Does the keyword form still build?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does call draw(width=5) mean?

    Answer

    The value 5 goes to the dummy argument named width

    The name before the equals sign is the dummy argument.

  2. In which order may keyword arguments appear?

    Answer

    Any order

    Names replace positions, so the order is free.

  3. What does this program print? program p implicit none call show(b=2, a=1) contains subroutine show(a, b) integer, intent(in) :: a, b print *, a, b end subroutine show end program p

    Answer

    1 2

    The names place the values, so a is 1 and b is 2.

  4. Which mixture is legal?

    Answer

    Positional arguments first, then keywords

    A positional argument may not follow a keyword.

  5. What does gfortran report for a misspelt keyword?

    Answer

    Error: Keyword argument ... is not in the procedure, with a suggestion

    The name must be a dummy argument of the procedure.

  6. What is needed before a call with keywords can be compiled?

    Answer

    An explicit interface, as a module or a contained procedure gives

    The compiler must know the dummy names and types.

  7. Why does a keyword call document itself?

    Answer

    The name of each argument says what the value means

    A reader checks the call without the procedure.

  8. What does a positional call of six numbers hide?

    Answer

    Which dummy each number goes to

    Position carries the meaning, and nothing names it.

  9. Which arguments can a keyword call skip?

    Answer

    Only optional ones

    A required argument must still be passed.

  10. What is the cost of the keyword form at run time?

    Answer

    None: the compiler matches the names

    The names exist only in the source.

The programs on this page were built with GNU Fortran (Alpine 15.2.0) 15.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev