A-Shell Reference

Revised and reviewed April 2020

Named parameters, also called "keyword arguments," may be used in place of, or in conjunction with, the traditional ordered parameters for all function and procedure calls. (For related information as it applies to subroutines, see Named Parameters in Subroutines.) Although this feature is really just a syntactic nicety rather than a fundamental capability, it nevertheless offers a variety of benefits:

The ASB implementation of named parameters is similar to that found in other modern languages such as Python, in which the parameter names are extracted from the existing function and procedure definitions without requiring any syntactic changes to existing definitions. In addition, function and procedure definitions may specify default values for one or more parameters. Parameters with specified defaults are considered optional parameters, whereas those without defaults are considered mandatory.

However, there is one important exception to this rule, required for backward compatibility. Since ASB has traditionally treated ALL function, procedure and subroutine parameters as optional, it will continue to do so unless a function/procedure definition is modified to specify at least one default value.

This will become clear with a few examples, but first let's note the following points:

++ifndef ABC_NAMED_PARAMS

   ++error This program requires compiler 653+ (and /P)

++endif

 

Now for the examples. Consider the following function which takes the names of players at the first, second and third base positions and displays them as a sentence, as in the famous Abbott & Costello routine, i.e. "Who's on first, What's on second, and I Don't Know's on third".

function fn'lineup$(first$ as s0, second$ as s0, third$ as s0) as s0

Traditionally, any of the following would be legal invocations of the function, at least from the compiler's perspective:

? fn'lineup$()

? fn'lineup$("Who")

? fn'lineup$("Manny","Moe")

? fn'lineup$(spam$,spam$,spam$,spam$)

 

The first three examples specify fewer than the three expected parameters, but since there is no enforcement of minimum parameter counts, the compiler is happy. The routine itself can test .ARGCNT to see how many were actually passed. The fourth example specifies an extra parameter, which the compiler is happy to pass, and the routine may simply ignore, although it also has the ability to retrieve such additional parameters using explicit XGETARG statements.

Using named parameters, any of the following are also legal:

? fn'lineup$(first$="Who", second$="What", third$="I don't know")

? fn'lineup$(second$="Jack", first$="Manny")

? fn'lineup$("Eenie", "Meenie", third$="Mo")

 

The first simply adds the names of the parameters, making the code a bit more self-documenting. The second illustrates that you can rearrange the parameters since the compiler can match the names up to their proper positions, and you can also omit trailing parameters, in this case third$, provided it doesn't create a gap. The third example illustrates that you can combine ordered and named parameters, as long as the ordered ones ("Eenie" and "Meenie" in this case) come first.

These, however, are illegal:

? fn'lineup$(first$="Who", shortstop$="Curly")

       ! no such parameter: shortstop$

 

? fn'lineup$(first$="Manny", "Mo", "Jack")

       ! ordered parameters cannot follow named parameters

 

? fn'lineup$(first$="Tiny", second$="Fats", first$="Tiny")

       ! parameter first$ specified twice

 

? fn'lineup$(second$="What", third$="Nobody")  

       ! missing mandatory first$ parameter

 

The last example above deserves clarification. Although traditionally all parameters were optional, it was never possible with ordered parameters to omit one, other than at the trailing end of the parameter list. Consequently, to preserve runtime compatibility, we don't want to allow that to happen with named parameters either, at least by default.

However, by adding default values for one or more parameters in the function/procedure definition, we can effectively instruct the compiler regarding which parameters are mandatory and thereby have it do more of the work of error checking and standardizing function and procedure calls. To accommodate default values, a default value may be specified for any parameter in the function declaration, using the following syntax:

<paramname>{=defvalue} as <type>{:modifier}

For example:

function fn'lineup$(first$="Who" as s0, second$ as s0, third$="I don't know" as s0) as s0

Or, if we want to make it clear that these are all inputonly parameters, we can add the :inputonly modifier:

function fn'lineup$(first$="Who" as s0:inputonly, second$ as s0:inputonly, third$="I don't know" as s0:inputonly) as s0

With the updated function definition, we can reevaluate how the compiler would treat the example calls:

? fn'lineup$()              

       ! illegal (missing mandatory second$ parameter)

? fn'lineup$("Who")        

       ! illegal ("    "   ")

? fn'lineup$("Manny","Moe")

       ! ok (missing third$ defaults to "I don't know")

? fn'lineup$(spam$,spam$,spam$,spam$)  

       ! ok

 

? fn'lineup$(first$="Who", second$="What", third$="I don't know")

       ! ok

? fn'lineup$(second$="Jack")

       ! ok (first$ defaults to "Who" and third$ to "I don't know")

? fn'lineup$("Eenie", "Meenie", third$="Mo")

       ! ok

 

Finally, if we want to make our fn'lineup$() function available in a library where it might be compiled with an older version of the compiler, we can use conditional compilation to specify two versions of the function definition—one traditional (ordered parameters only) and one modern (with named parameters and default values):

++ifdef ABC_NAMED_PARAMS                ! if /P (named parameter supported)

    function fn'lineup$(first$="Who" as s0, second$ as s0, third$="I don't know" as s0) as s0

 

++else                                  ! traditional version

 

    function fn'lineup$(first$ as s0, second$ as s0, third$ as s0) as s0

 

++endif

    fn'lineup$ = first$ + "'s on first, " + second$ + ",s on second, and " + third$ + ",s on third."

    endfunction

History

2014 January, A-Shell 6.1.1373:  Named parameters implemented in A-Shell.