(r14) TopLCS2016_006g < P1076

P1076 Web>VHDL2017>LCS2016_006e>TopLCS2016_006g (revision 14) (raw view)~~EditAttach~~
---+ Language Change Specification for Environment API

---++ 

| <sticky><b>LCS Number:</b></sticky> | LCS-2016-006g |
| <sticky><b>Version:</b>   </sticky> | 3 |
| <sticky><b>Date:</b>      </sticky> | 07-Mar-2017  |
| <sticky><b>Status:</b>    </sticky> | Voting |
| <sticky><b>Author:</b>    </sticky> | Thomas Preusser |
| <sticky><b>Email:</b>     </sticky> | [[Main.ThomasPreusser]] |
| <sticky><b>Source Doc:</b></sticky> | |
| <sticky><b>Summary:</b>   </sticky> | Allow access to system environment variables (explorable). |

---+++ Voting Results: Cast your votes here

Yes:
   1 %USERSIG{ThomasPreusser - 2017-03-06}% - ver 3
   1 %USERSIG{JimLewis- 2017-03-06}% - ver 2
   1 %USERSIG{PatrickLehmann - 2017-03-14}% - ver 3 see my comment

No:

Abstain:
   1 %USERSIG{MartinZabel - 2017-03-07}% - ver 3 - I prefer separate functions for environment variables and conditional analysis identifiers.
   1 %USERSIG{RobGaddi - 2017-03-21}% - ver 3 - I think it's technically correct, but can't see a use case in VHDL for querying the entire environment blindly.

---++ Style Notes

Changes are shown in %RED%red font%ENDCOLOR%.%BR%
Deletions are %RED%<del>crossed out</del>%ENDCOLOR%.%BR%
Editing or inline reviewing notes are shown in %GREEN%green font%ENDCOLOR%.%BR%
%BLUE%Blue text%ENDCOLOR% will only be introduced if [[LCS2016_061][LCS061]], i.e. conditional analysis, is approved.

---++ Reviewing Notes

This is a proposal extending [[LCS2016_006e][LCS006e]]. It provides access to the complete sets of environment variables and conditional analysis identifiers through arrays of variable definition vectors.

---++ Details of Language Change
---+++ 16.5 Standard environment package
---+++ 16.5.1 General %GREEN%[NEW headline level]%ENDCOLOR%

Package ENV contains declarations that provide a VHDL interface to the host environment.
<pre>package ENV is
  procedure STOP (STATUS: INTEGER);
  procedure STOP;
  procedure FINISH (STATUS: INTEGER);
  procedure FINISH;
 
  function RESOLUTION_LIMIT return DELAY_LENGTH;

  %GREEN%[... LCS-2016-011 ...]%ENDCOLOR%
  %GREEN%[... LCS-2016-006c ...]%ENDCOLOR%
  %GREEN%[... LCS-2016-006e ...]%ENDCOLOR%

  %RED%type VARIABLE_DEFINITION is record
    name  : LINE;
    value : LINE;
  end record;
  -- The predefined operations for this type are as follows:
  -- function "=" (anonymous, anonymous: VARIABLE_DEFINITION) return BOOLEAN;
  -- function "/=" (anonymous, anonymous: VARIABLE_DEFINITION) return BOOLEAN;%ENDCOLOR%

  %RED%type VARIABLE_DEFINITION_VECTOR is array(NATURAL range&lt;&gt;) of VARIABLE_DEFINITION;
  -- The predefined operations for this type are as follows:
  -- function "="(anonymous, anonymous: VARIABLE_DEFINITION_VECTOR) return BOOLEAN;
  -- function "/="(anonymous, anonymous: VARIABLE_DEFINITION_VECTOR) return BOOLEAN;
  -- function "&"(anonymous, anonymous: VARIABLE_DEFINITION_VECTOR) return VARIABLE_DEFINITION_VECTOR;
  -- function "&"(anonymous: VARIABLE_DEFINITION_VECTOR; anonymous: VARIABLE_DEFINITION) return VARIABLE_DEFINITION_VECTOR;
  -- function "&"(anonymous: VARIABLE_DEFINITION; anonymous: VARIABLE_DEFINITION_VECTOR) return VARIABLE_DEFINITION_VECTOR;
  -- function "&"(anonymous, anonymous: VARIABLE_DEFINITION) return VARIABLE_DEFINITION_VECTOR;%ENDCOLOR%

  %RED%type VARIABLE_DEFINITIONS is access VARIABLE_DEFINITION_VECTOR;
  -- The predefined operations for this type are as follows:
  -- function "=" (anonymous, anonymous: VARIABLE_DEFINITIONS) return BOOLEAN;
  -- function "/=" (anonymous, anonymous: VARIABLE_DEFINITIONS) return BOOLEAN;
  -- procedure DEALLOCATE (P: inout VARIABLE_DEFINITIONS);%ENDCOLOR%

  %RED%function GETALLENV return VARIABLE_DEFINITIONS;%ENDCOLOR%

  %GREEN%[... LCS-2016-006f ...]%ENDCOLOR%

end package ENV;
</pre>
---+++ 16.5.5 System Environment API %GREEN%[NEW]%ENDCOLOR%

%GREEN%(This paragraph is to go between the paragraphs possibly added by [[LCS2016_006e][LCS006e]] and [[LCS2016_006f][LCS006f]] as part of this same new section.)%ENDCOLOR%

%RED%The function GETALLENV%ENDCOLOR% %RED%returns an access value to an array of variable definition records. Each of these records contains the name and the value of a defined environment variable%ENDCOLOR%. %BLUE%The conditional analysis identifiers (24.2) are part of this environment and hide possibly inherited environment variables of identical names.%ENDCOLOR%%RED%The returned array is a complete list of all defined environment variables%ENDCOLOR% %BLUE%completed and possibly shadowed by all conditional analysis identifiers including standard, tool-defined and user-specified identifiers.%ENDCOLOR%

---+++ Comments

For the sentence before the package declaration:
   * This sentence already exists and can't be added by either of the proposed LCS 006e..g.
   * If this sentence is going to be changed, then indicate this by using red cross out text.
   * The proposed sentence breaks the meaning of the existing sentence.
     Sub programs like =STOP= or =RESOLUTION_LIMIT= are not related to environment variables.
   * The LRM contains doesn't reference the operating system as "OS". The correct term is "host environment".
   * Reference to other sections are placed in parenthesis instead of square brackets. Square brackets are used for references to
     bibliographical items in annex J.

The all three new types miss the list of implicitly pre-defined operators for any type, record types, array types and access types.

The syntax of the function definition is no valid VHDL code.

Why is this obscure solution less hacky then my proposed simple solution in LCS 006d?

-- %BUBBLESIG{PatrickLehmann - 2017-03-06}%

@Patrick: Thanks for your hints. I adopted all your proposed edits.

*PL*: Why is this obscure solution less hacky then my proposed simple solution in LCS 006d?

Maybe, you can elaborate on the "obscure". Anyhow, if you just compare the number of functions, procedures and types as well as the descriptive text between LCS 006d and LCS 006(e,f,g) combined, you should be puzzled already. Some of this is due to a great deal of alternatives for the same things. For instance: Why does LCS 006d have a procedure ENV_GETVARIABLE if the function ENV_GETVARIABLE directly below does the same with the additional benefit of being usable within expressions? This is the opposite of orthogonality and creates confusion and maintenance hastles.

This concrete LCS 006g addresses a request by Jim to have the environment explorable without a secondary value lookup. LCS 006d does not achieve this.

-- %BUBBLESIG{ThomasPreusser - 2017-03-07}%

I suggest to rename the environment related functions to =ENV_*=, this aligns with the =FILE_*= and =DIR_*= subprograms.

-- %BUBBLESIG{PatrickLehmann - 2017-03-14}%

Please, just bring this up in the next meeting to pick up the general feeling about it. There are good reasons to establish a naming scheme as you suggest. There are also good reasons to stick with traditional names such as =GETENV=. Both choices are absolutely valid, and I am ready to follow a broadly and clearly expressed group decision on this matter. I would hope though that every other voter would see it similarly so that we can avoid losing votes again on such a side issue.

-- %BUBBLESIG{ThomasPreusser - 2017-03-16}%
%COMMENT%
Topic revision: r1 - 2017-04-02 - 15:46:39 - TWikiGuest
P1076