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
- Call draw with the label first and the width second by keyword. Does the output change?
- Write a call that passes a positional argument after a keyword. What does the compiler say?
- Rename the dummy width to columns and leave the calls alone. Which lines stop compiling?
- 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.
-
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.
-
In which order may keyword arguments appear?
Answer
Any order
Names replace positions, so the order is free.
-
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 pAnswer
1 2
The names place the values, so a is 1 and b is 2.
-
Which mixture is legal?
Answer
Positional arguments first, then keywords
A positional argument may not follow a keyword.
-
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.
-
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.
-
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.
-
What does a positional call of six numbers hide?
Answer
Which dummy each number goes to
Position carries the meaning, and nothing names it.
-
Which arguments can a keyword call skip?
Answer
Only optional ones
A required argument must still be passed.
-
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