11.7.6 External Values

An external value is an expression whose value is obtained from the command that invoked the processing of the current project file (typically a gnatmake or gprbuild command).

There are two kinds of external values, one that returns a single string, and one that returns a string list.

The syntax of a single string external value is:

     external_value ::= external ( string_literal [, string_literal] )

The first string_literal is the string to be used on the command line or in the environment to specify the external value. The second string_literal, if present, is the default to use if there is no specification for this external value either on the command line or in the environment.

Typically, the external value will either exist in the ^environment variables^logical name^ or be specified on the command line through the ^-X^/EXTERNAL_REFERENCE=^vbl=value switch. If both are specified, then the command line value is used, so that a user can more easily override the value.

The function external always returns a string. It is an error if the value was not found in the environment and no default was specified in the call to external.

An external reference may be part of a string expression or of a string list expression, and can therefore appear in a variable declaration or an attribute declaration.

Most of the time, this construct is used to initialize typed variables, which are then used in case statements to control the value assigned to attributes in various scenarios. Thus such variables are often called scenario variables.

The syntax for a string list external value is:

     external_value ::= external_as_list ( string_literal , string_literal )

The first string_literal is the string to be used on the command line or in the environment to specify the external value. The second string_literal is the separator between each component of the string list.

If the external value does not exist in the environment or on the command line, the result is an empty list. This is also the case, if the separator is an empty string or if the external value is only one separator.

Any separator at the beginning or at the end of the external value is discarded. Then, if there is no separator in the external value, the result is a string list with only one string. Otherwise, any string between the beginning and the first separator, between two consecutive separators and between the last separator and the end are components of the string list.

        external_as_list ("SWITCHES", ",")

If the external value is "-O2,-g", the result is ("-O2", "-g").

If the external value is ",-O2,-g,", the result is also ("-O2", "-g").

if the external value is "-gnav", the result is ("-gnatv").

If the external value is ",,", the result is ("").

If the external value is ",", the result is (), the empty string list.