Version 1.3 of ai05s/ai05-0285-1.txt

Unformatted version of ai05s/ai05-0285-1.txt version 1.3
Other versions for file ai05s/ai05-0285-1.txt

!standard A.17(4/2) 12-02-24 AI05-0285-1/02
!standard A.17(11/2)
!class Amendment 12-01-27
!status Amendment 2012 12-01-27
!status work item 12-01-27
!status received 11-10-01
!priority Low
!difficulty Easy
!subject Defaulted environment variable queries

!summary

An additional form of the Value routine is added to Ada.Environment_Variables.

!proposal

A common usage is that one wants to determine the value of an environment variable, if the variable exists, but then assume a default value if the variable does not exist.

The current package Environment_Variables requires two steps for this functionality (test whether the variable exists, then get the value if it does not).

!wording

Add after A.17(4/2):

function Value (Name : in String; Default : in String) return String;

Add after A.17(11/2):

function Value (Name : in String; Default : in String) return String;

If an environment variable with the given name exists, returns its value. Otherwise, returns Default.

AARM Note: On an implementation that does not support environment variables, the "Otherwise" above will apply. Duh.

!discussion

Not only is the two-step process inconvenient, it could cause a race condition if another process could modify the variable.

!corrigendum A.17(4/2)

Insert after the paragraph:

function Value (Name : in String) return String;

the new paragraph:

function Value (Name : in String; Default : in String) return String;

!corrigendum A.17(11/2)

Insert after the paragraph:

If the external execution environment supports environment variables, then Value returns the value of the environment variable with the given name. If no environment variable with the given name exists, then Constraint_Error is propagated. If the execution environment does not support environment variables, then Program_Error is propagated.

the new paragraphs:

function Value (Name : in String; Default : in String) return String;

If an environment variable with the given name exists, returns its value. Otherwise, returns Default.

!ACATS Test

Create an ACATS C-Test to test this subprogram.

!ASIS

No change needed.

!appendix


!topic Defaulted Environment Variable Lookups
!reference Ada 2005 A.17 (4/2)
!from /Brad Moore 11-10-01/
!keywords Environment Variable Lookup Default
!discussion
Ada.Environment_Variables provides the call;

function Value (Name : in String) return String;

To retrieve the value of an environment variable. A common usage however 
is that one wants to
determine the value of an environment variable, if the variable exists, 
but then assume a default
if the variable does not exist.

It would be useful to have the subprogram;

function Value (Name : in String; Default : in String) return String;

If the Name exists, then that value is returned, otherwise the Default 
is returned.

It is annoying to have to either make extra calls to test for the 
existence of the variable before calling Value,
or wrapping this call in another user defined call that provides the 
desired behavior.

****************************************************************

From: Jeff Cousins
Sent: Tuesday, October 4, 2011  6:07 AM

We would strongly agree with this one.
In most if not all cases our default would simply be a null string, but
it seems a good idea to generalise it.

****************************************************************

Questions? Ask the ACAA Technical Agent