(r42) LCS2016_006c < P1076

P1076 Web>VHDL2017>LCS2016_006c (revision 42) (raw view)~~EditAttach~~
---+ Language Change Specification for Directory API
---++ 

| <sticky><b>LCS Number:</b></sticky> | LCS-2016-006c |
| <sticky><b>Version:</b>   </sticky> | 1 {18-Jan-2017} %BR% 2 {11-Feb-2017} %BR% 3 {17-Feb-2017} %BR% 4 {21-Feb-2017} %BR% 5 {22-Feb-2017} %BR% 6 {xx-Feb-2017} %BR% 7 {24-Feb-2017} %BR% 8 {15-Mar-2017} |
| <sticky><b>Date:</b>      </sticky> | 15-Mar-2017  |
| <sticky><b>Status:</b>    </sticky> | Voting |
| <sticky><b>Author:</b>    </sticky> | Patrick Lehmann |
| <sticky><b>Email:</b>     </sticky> | [[Main.PatrickLehmann]] |
| <sticky><b>Source Doc:</b></sticky> | [[FileIo][File IO / TextIO updates]] |
| <sticky><b>Summary:</b>   </sticky> | TextIO additions. %BR% See [[LCS2016_006a][LCS-2016-006a]] for file I/O additions. |

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

Yes:
   1 %USERSIG{YannGuidon - 2017-01-19}% - ver 1
   1 %USERSIG{RobGaddi - 2017-03-16}% - ver 8
   1 <span data-mce-mark="1">%USERSIG{LievenLemiengre - 2017-01-27}%</span> - ver 1
   1 %USERSIG{HendrikEeckhaut - 2017-01-27}% ver 1
   1 %USERSIG{KevinJennings - 2017-2-9}% Ver 2
   1 %USERSIG{SteveGrout - 2017-03-15}% - ver 7
   1 %USERSIG{PatrickLehmann - 2017-03-15}% - ver 8
   1 %USERSIG{JimLewis - 2017-03-15}% ver 8

No:
   1 %USERSIG{ThomasPreusser - 2017-02-06}% - ver 5 - mutable working dir is dangerous, OPEN_DIR joins independent operations needlessly, see comment of 2017-02-22

Abstain:
   1 %USERSIG{BrentHahoe - 2017-02-16}% Version 2 - Abstain due to lack of personal time for review.

---++ Style Notes

<noautolink>

<sticky>
Changes are shown in %RED%red font%ENDCOLOR%.%BR%
Deletions are %RED%<del>crossed out</del>%ENDCOLOR%.%BR%
Editing or reviewing notes in %GREEN%green font%ENDCOLOR%.
 
---++ Reviewing Notes
*Version 1:* %BR%
This LCS adds the ability to read directory contents (list all names), query properties (file vs. directory),
to create directories and to remove files or directories. The directory's content is returned as a record with
an embedded dynamic array of string pointers. Each string contains an item's name. This API does not provide a
high-level API: for example to assemble paths or to extract a parent directory from a path. This can be provided
by an (open source) package or library.

*Version 2:* %BR%
   * Change =DIRECTORY.Childs= to =DIRECTORY.Items=.

*Version 4:* %BR%
   * provide function overloads for the procedure interface to return status values
   * split DIR_DELETE_STATUS into two status enumerations: for directories and files
   * made DIR_SEPARATOR a deferred constant
   * Change wording for recursive deletion of directories
   * specified the Name element in DIRECTORY as a "fully resolved absolute path"

*Version 5:* %BR%
   * reworked STATUS values again
      * In =DIR_CREATE_STATUS=, changed =STATUS_NO_DIRECTORY= to =STATUS_ITEM_EXISTS=.
      * In =DIR_DELETE_STATUS=, added =STATUS_NOT_EMPTY=.
   * Reordered =out= parameter =Dir= to match the LRM style.
   * Improved text for the impure functions offering another but similar interface to there corresponding procedures.
   * Marked =impure function DIR_OPEN= as dependent on LCS 002.
   * Listed predefined implicitly declared operators.

*Version 6:* %BR%
   * Rewrote optional parameters in procedures to overloaded procedures to fulfill the coding guide lines.

*Version 7:* %BR%
   * Specified the returned value if an operation fails.

*Version 8:* %BR%
   * Added new overloads for =FILE_OPEN= as requested.


---++ Details of Language Change
---+++ (006c.1) 5.5.2 File operations
The language implicitly defines the operations for objects of a file type. Given the following file type declaration:

<pre>
type FT is file of TM;
</pre>

where type mark TM denotes a scalar type, a record type, or a fully constrained array subtype, the following operations are %BR%
implicitly declared immediately following the file type declaration:

<pre>
procedure FILE_OPEN (file F: FT; External_Name: in STRING; Open_Kind: in FILE_OPEN_KIND := READ_MODE);
procedure FILE_OPEN (Status: out FILE_OPEN_STATUS; file F: FT; External_Name: in STRING; Open_Kind: in FILE_OPEN_KIND := READ_MODE);
%ORANGE%procedure FILE_OPEN (file F: FT; External_Name: in STRING; Status: out FILE_OPEN_STATUS);
procedure FILE_OPEN (file F: FT; External_Name: in STRING; Open_Kind: in FILE_OPEN_KIND; Status: out FILE_OPEN_STATUS);
impure function  FILE_OPEN (file F: FT; External_Name: in STRING; Open_Kind: in FILE_OPEN_KIND := READ_MODE) return FILE_OPEN_STATUS;%ENDCOLOR%

procedure FILE_CLOSE (file F: FT);
procedure READ (file F: FT; VALUE: out TM);
procedure WRITE (file F: FT; VALUE: in TM);
procedure FLUSH (file F: FT);
function  ENDFILE (file F: FT) return BOOLEAN;
</pre>

%GREEN%[...]%ENDCOLOR%

The first form of FILE_OPEN causes an error to occur if the second form of FILE_OPEN, when called under identical conditions, %BR%
would return a Status value other than OPEN_OK.

A call to FILE_OPEN of the first form is successful if and only if the call does not cause an error to occur. Similarly, a call %BR%
to FILE_OPEN of the second form is successful if and only if it returns a Status value of OPEN_OK.

%ORANGE%The procedure FILE_OPEN, with parameters F, External_Name, and Status, is an overload of the form with parameters Status, F, External_Name, %BR%
and Open_Kind and implements the same behavior. The Open_Kind is always READ_MODE.%ENDCOLOR%

%ORANGE%The procedure FILE_OPEN, with parameters F, External_Name, Open_Kind, and Status, is an overload of the form with parameters Status, F, %BR%
External_Name, and Open_Kind and implements the same behavior.%ENDCOLOR%

%ORANGE%The impure function FILE_OPEN implements the same behavior as the procedure FILE_OPEN, with parameters F, External_Name, Open_Kind, %BR%
and Status. The procedure's output parameter Status of type FILE_OPEN_STATUS in the return value of the function.%ENDCOLOR%

%GREEN%[...]%ENDCOLOR%

---+++ (006c.2) 16.4 Package TEXTIO
<pre>
package TEXTIO is
  -- Type definitions for text I/O:
  type LINE is access STRING; -- A LINE is a pointer to a STRING value.
  -- The predefined operations for this type are as follows:
  -- function"=" (anonymous, anonymous: LINE) return BOOLEAN;
  -- function"/=" (anonymous, anonymous: LINE) return BOOLEAN;
  -- procedure DEALLOCATE (P: inout LINE);
 
  %GREEN%[Editor note: Move LINE_VECTOR to std.STANDARD if LINE moves their.]%ENDCOLOR%
  %RED%type LINE_VECTOR is array(NATURAL range <>) of LINE;
  -- The predefined operations for this type are as follows:
  -- function "="(anonymous, anonymous: LINE_VECTOR) return BOOLEAN;
  -- function "/="(anonymous, anonymous: LINE_VECTOR) return BOOLEAN;
  -- function "&"(anonymous: LINE_VECTOR; anonymous: LINE_VECTOR) return LINE_VECTOR;
  -- function "&"(anonymous: LINE_VECTOR; anonymous: LINE) return LINE_VECTOR;
  -- function "&"(anonymous: LINE; anonymous: LINE_VECTOR) return LINE_VECTOR;
  -- function "&"(anonymous: LINE; anonymous: LINE) return LINE_VECTOR;%ENDCOLOR%
 
  type TEXT is file of STRING; -- A file of variable-length ASCII records.
  -- The predefined operations for this type are as follows:
  -- procedure FILE_OPEN (file F: TEXT; External_Name; in STRING; Open_Kind: in FILE_OPEN_KIND := READ_MODE);
  -- procedure FILE_OPEN (Status: out FILE_OPEN_STATUS; file F: TEXT; External_Name: in STRING; Open_Kind: in FILE_OPEN_KIND := READ_MODE);
  -- procedure FILE_CLOSE (file F: TEXT);
  -- procedure READ (file F: TEXT; VALUE: out STRING);
  -- procedure WRITE (file F: TEXT; VALUE: in STRING);
  -- procedure FLUSH (file F: TEXT);
  -- function ENDFILE (file F: TEXT) return BOOLEAN;
end %RED%package%ENDCOLOR% TEXTIO;
</pre>


---+++ 16.5 Standard environment package
---+++ (006c.3) 16.5.1 General %GREEN%[NEW headline level]%ENDCOLOR%
Package ENV contains declarations that provide a VHDL interface to the host environment.

<pre>
%RED%use work.textio.all;%ENDCOLOR%

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%
 
  %RED%type DIRECTORY_ITEMS is access LINE_VECTOR;
  -- The predefined operations for this type are as follows:
  -- function"=" (anonymous, anonymous: DIRECTORY_ITEMS) return BOOLEAN;
  -- function"/=" (anonymous, anonymous: DIRECTORY_ITEMS) return BOOLEAN;
  -- procedure DEALLOCATE (P: inout DIRECTORY_ITEMS);
 
  type DIRECTORY is record
    Name      : LINE;             -- current directory name; resolved to its canonical form
    Items     : DIRECTORY_ITEMS;  -- list of pointers to directory item names
  end record;
  -- The predefined operations for this type are as follows:
  -- function "="(anonymous, anonymous: DIRECTORY) return BOOLEAN;
  -- function "/="(anonymous, anonymous: DIRECTORY) return BOOLEAN;
  
  type DIR_OPEN_STATUS is (
    STATUS_OK,
    STATUS_NOT_FOUND,
    STATUS_NO_DIRECTORY,
    STATUS_ACCESS_DENIED,
    STATUS_ERROR
  );
  -- The predefined operations for this type are as follows:
  -- function "="(anonymous, anonymous: DIR_OPEN_STATUS) return BOOLEAN;
  -- function "/="(anonymous, anonymous: DIR_OPEN_STATUS) return BOOLEAN;
  -- function "<"(anonymous, anonymous: DIR_OPEN_STATUS) return BOOLEAN;
  -- function "<="(anonymous, anonymous: DIR_OPEN_STATUS) return BOOLEAN;
  -- function ">"(anonymous, anonymous: DIR_OPEN_STATUS) return BOOLEAN;
  -- function ">="(anonymous, anonymous: DIR_OPEN_STATUS) return BOOLEAN;
  -- function MINIMUM (L, R: DIR_OPEN_STATUS) return DIR_OPEN_STATUS;
  -- function MAXIMUM (L, R: DIR_OPEN_STATUS) return DIR_OPEN_STATUS;
  
  type DIR_CREATE_STATUS is (
    STATUS_OK,
    STATUS_ITEM_EXISTS,
    STATUS_ACCESS_DENIED,
    STATUS_ERROR
  );
  -- The predefined operations for this type are as follows:
  -- function "="(anonymous, anonymous: DIR_CREATE_STATUS) return BOOLEAN;
  -- function "/="(anonymous, anonymous: DIR_CREATE_STATUS) return BOOLEAN;
  -- function "<"(anonymous, anonymous: DIR_CREATE_STATUS) return BOOLEAN;
  -- function "<="(anonymous, anonymous: DIR_CREATE_STATUS) return BOOLEAN;
  -- function ">"(anonymous, anonymous: DIR_CREATE_STATUS) return BOOLEAN;
  -- function ">="(anonymous, anonymous: DIR_CREATE_STATUS) return BOOLEAN;
  -- function MINIMUM (L, R: DIR_CREATE_STATUS) return DIR_CREATE_STATUS;
  -- function MAXIMUM (L, R: DIR_CREATE_STATUS) return DIR_CREATE_STATUS;
  
  type DIR_DELETE_STATUS is (
    STATUS_OK,
    STATUS_NO_DIRECTORY,
    STATUS_NOT_EMPTY,
    STATUS_ACCESS_DENIED,
    STATUS_ERROR
  );
  -- The predefined operations for this type are as follows:
  -- function "="(anonymous, anonymous: DIR_DELETE_STATUS) return BOOLEAN;
  -- function "/="(anonymous, anonymous: DIR_DELETE_STATUS) return BOOLEAN;
  -- function "<"(anonymous, anonymous: DIR_DELETE_STATUS) return BOOLEAN;
  -- function "<="(anonymous, anonymous: DIR_DELETE_STATUS) return BOOLEAN;
  -- function ">"(anonymous, anonymous: DIR_DELETE_STATUS) return BOOLEAN;
  -- function ">="(anonymous, anonymous: DIR_DELETE_STATUS) return BOOLEAN;
  -- function MINIMUM (L, R: DIR_DELETE_STATUS) return DIR_DELETE_STATUS;
  -- function MAXIMUM (L, R: DIR_DELETE_STATUS) return DIR_DELETE_STATUS;
  
  type FILE_DELETE_STATUS is (
    STATUS_OK, 
    STATUS_NO_FILE,
    STATUS_ACCESS_DENIED,
    STATUS_ERROR
  );
  -- The predefined operations for this type are as follows:
  -- function "="(anonymous, anonymous: FILE_DELETE_STATUS) return BOOLEAN;
  -- function "/="(anonymous, anonymous: FILE_DELETE_STATUS) return BOOLEAN;
  -- function "<"(anonymous, anonymous: FILE_DELETE_STATUS) return BOOLEAN;
  -- function "<="(anonymous, anonymous: FILE_DELETE_STATUS) return BOOLEAN;
  -- function ">"(anonymous, anonymous: FILE_DELETE_STATUS) return BOOLEAN;
  -- function ">="(anonymous, anonymous: FILE_DELETE_STATUS) return BOOLEAN;
  -- function MINIMUM (L, R: FILE_DELETE_STATUS) return FILE_DELETE_STATUS;
  -- function MAXIMUM (L, R: FILE_DELETE_STATUS) return FILE_DELETE_STATUS;
  
  procedure       DIR_OPEN(Dir : out DIRECTORY; Path : in STRING; Status : out DIR_OPEN_STATUS);
  impure function DIR_OPEN(Dir : out DIRECTORY; Path : in STRING;) return DIR_OPEN_STATUS;        %GREEN%[Requires out parameters in impure functions: LCS 002 ??]%ENDCOLOR%
  procedure       DIR_CLOSE(Dir : in DIRECTORY);                                                 -- used to deallocate internal values
  
  impure function DIR_ITEMEXISTS(Path : in STRING) return BOOLEAN;
  impure function DIR_ITEMISDIR(Path : in STRING) return BOOLEAN;
  impure function DIR_ITEMISFILE(Path : in STRING) return BOOLEAN;
  
  procedure       DIR_WORKINGDIR(Path : in STRING; Status : out DIR_OPEN_STATUS);
  impure function DIR_WORKINGDIR(Path : in STRING) return DIR_OPEN_STATUS;
  impure function DIR_WORKINGDIR return STRING;
  
  procedure       DIR_CREATEDIR(Path : in STRING; Status : out DIR_CREATE_STATUS);
  procedure       DIR_CREATEDIR(Path : in STRING; Parents : in BOOLEAN; Status : out DIR_CREATE_STATUS);
  impure function DIR_CREATEDIR(Path : in STRING; Parents : in BOOLEAN := FALSE) return DIR_CREATE_STATUS;
  procedure       DIR_DELETEDIR(Path : in STRING; Status : out DIR_DELETE_STATUS);
  procedure       DIR_DELETEDIR(Path : in STRING; Recursive : in BOOLEAN; Status : out DIR_DELETE_STATUS);
  impure function DIR_DELETEDIR(Path : in STRING; Recursive : in BOOLEAN := FALSE) return DIR_DELETE_STATUS;
  procedure       DIR_DELETEFILE(Path : in STRING; Status : out FILE_DELETE_STATUS);
  impure function DIR_DELETEFILE(Path : in STRING) return FILE_DELETE_STATUS;
  
  constant        DIR_SEPARATOR : STRING;%ENDCOLOR%
end package ENV;
</pre>

%GREEN%[Editor note: Three notes ...]%ENDCOLOR%

---+++ (006c.4) 16.5.2 Simulator API %GREEN%[NEW headline level]%ENDCOLOR%

Execution of the STOP procedures causes the same action by the host simulator as that caused by the =vhpi_control= function called with the argument %BR%
=vhpiStop= (see 23.5). Execution of the FINISH procedures causes the same action by the host simulator as that caused by the =vhpi_control= function %BR%
called with the argument =vhpiFinish= (see 23.5). Execution shall not return to the VHDL description after a call to the FINISH procedure. For the %BR%
procedures with the STATUS parameter, the value of the STATUS parameter may be used in an implementation defined manner by the host simulator. For the %BR%
procedures with no parameter, the effect is the same as that caused by the =vhpi_control= function with no additional arguments beyond the =vhpiStop= %BR%
or =vhpiFinish= argument.

The function RESOLUTION_LIMIT returns the value of the resolution limit (see 5.2.4.2).


---+++ 16.5.3 Date and Time API %GREEN%[NEW, see LCS-2016-011]%ENDCOLOR%
%GREEN%[Editor note: See LCS-2016-011 Data and Time]%ENDCOLOR%

---+++ (006c.5) 16.5.4 Directory API %GREEN%[NEW]%ENDCOLOR%
%RED%All directory operations shall accept relative and absolute paths for parameter Path of type STRING, if Path is present as a parameter.%ENDCOLOR%

%RED%The procedure DIR_OPEN, with parameters Dir, Path and Status, returns a record of type DIRECTORY, which describes the directory and its directory items, for a given Path. The output %BR%
parameter Status of type DIR_OPEN_STATUS returns the result of the operation. The status shall be STATUS_OK on success, STATUS_NOT_FOUND if the path doesn't exist, %BR%
STATUS_NO_DIRECTORY if the path doesn't denote a directory, STATUS_ACCESS_DENIED if the privilege level is not sufficient and STATUS_ERROR %BR%
for any other error condition raised by the implementation. The predefined record type DIRECTORY has two elements:%ENDCOLOR%
   * %RED% *Name* references a STRING object, which contains the fully resolved absolute path of the represented directory.%ENDCOLOR%
   * %RED% *Items* references an array of LINE objects (type DIRECTORY_ITEMS), which in turn reference STRING objects. Each string object contains the simple name of a directory item %BR%
     in the directory.%ENDCOLOR%
%RED%In case of no success, the returned record contains null values for each record element.%ENDCOLOR%

%RED%The impure function DIR_OPEN implements the same behavior as the procedure DIR_OPEN, with parameters Dir, Path and Status. The procedure's output parameter Status of %BR%
type DIR_OPEN_STATUS in the return value of the function.%ENDCOLOR%

%RED%The impure function DIR_CLOSE, with parameter Dir, deallocates DIRECTORY objects allocated by DIR_OPEN.%ENDCOLOR%

%RED%The impure function DIR_ITEMEXISTS, with parameter Path, returns TRUE if the given path exists.%ENDCOLOR%

%RED%The impure function DIR_ITEMISDIR, with parameter Path, returns TRUE if the given path exists and is a directory.%ENDCOLOR%

%RED%The impure function DIR_ITEMISFILE, with parameter Path, returns TRUE if the given path exists and is a file.%ENDCOLOR%

%RED%The procedure DIR_WORKINGDIR, with parameters Path and Status, sets the working directory for all file operations using a relative path. The result of the operation %BR%
is returned by the out parameter Status of type DIR_OPEN_STATUS. The status shall have the same value for the same conditions as for procedure DIR_OPEN.%ENDCOLOR%

%RED%The impure function DIR_WORKINGDIR, with parameter Path, implements the same behavior as the procedure DIR_WORKINGDIR. The procedure's output parameter Status of type DIR_OPEN_STATUS %BR%
in the return value of the function.%ENDCOLOR%

%RED%The impure function DIR_WORKINGDIR, without parameters, is an overload and returns the current working directory used for all file operations as a STRING. The working %BR%
directory shall initially be the same as the tool's working directory.%ENDCOLOR%

%RED%The procedure DIR_CREATEDIR, with parameters Path and Status, creates the directory specified by parameter Path. The result of the operation is returned by the out %BR%
parameter Status of type DIR_CREATE_STATUS. The status shall be STATUS_OK on success, STATUS_ITEM_EXISTS if the path already exists, STATUS_ACCESS_DENIED if the privilege level is not %BR%
sufficient and STATUS_ERROR for any other error condition raised by the implementation.%ENDCOLOR%

%RED%The procedure DIR_CREATEDIR, with parameters Path, Parent and Status, has almost the same behavior as the former procedure. In addition, if parameter Parents is set to TRUE, %BR%
all missing intermediate directories are created as well, so Path can be created.%ENDCOLOR%

%RED%The impure function DIR_CREATEDIR implements the same behavior as the procedure DIR_CREATEDIR, with parameters Path, Parent and Status. The procedure's output parameter Status %BR%
of type DIR_CREATE_STATUS in the return value of the function.%ENDCOLOR%

%RED%The procedure DIR_DELETEDIR, with parameters Path and Status, deletes an empty directory specified by parameter Path. The result of the operation is return by the out parameter %BR%
Status of type DIR_DELETE_STATUS. The status shall be STATUS_OK on success, STATUS_NO_DIRECTORY if the Path is not a directory, STATUS_NOT_EMPTY if the directories is not empty, %BR%
STATUS_ACCESS_DENIED if the privilege level is not sufficient and STATUS_ERROR for any other error condition raised by the implementation.%ENDCOLOR%

%RED%The procedure DIR_DELETEDIR, with parameters Path, Recursive and Status, has almost the same behavior as the former procedure. In addition, if the parameter Recursive is set to TRUE, %BR%
the directory content is deleted recursively.%ENDCOLOR%

%RED%The impure function DIR_DELETEDIR implements the same behavior as the procedure DIR_DELETEDIR, with parameters Path, Recursive and Status. The procedure's output parameter Status of %BR%
type DIR_DELETE_STATUS in the return value of the function.%ENDCOLOR%

%RED%The function DIR_DELETEFILE, with parameters Path and Status, deletes the file specified by parameter Path. The result of the operation is returned by the out parameter Status of type %BR%
FILE_DELETE_STATUS. The status shall be STATUS_OK on success, STATUS_NO_FILE if the Path is not a directory, STATUS_ACCESS_DENIED if the privilege level %BR%
is not sufficient and STATUS_ERROR for any other error condition raised by the implementation.%ENDCOLOR%

%RED%The impure function DIR_DELETEFILE implements the same behavior as the procedure DIR_DELETEFILE, with parameters Path and Status. The procedure's output parameter Status of type %BR%
FILE_DELETE_STATUS in the return value of the function.%ENDCOLOR%

%RED%The deferred constant DIR_SEPARATOR of type STRING contains the path separator symbol used by the host system.%ENDCOLOR%


---++ Comments
---+++ Version 1
Typo in =DIRECTOTY_CHILDS=

-- %BUBBLESIG{HendrikEeckhaut - 2017-01-23}%


Title is incorrect : &#34;Language Change Specification for Hierarchical Libraries&#34;

-- %BUBBLESIG{HendrikEeckhaut - 2017-01-23}%


Fixed typo and title. No version increment due to minor changes.

-- %BUBBLESIG{PatrickLehmann - 2017-01-23}%


Would suggest changing "CHILD" to "ITEM" throughout.

-- %BUBBLESIG{KevinJennings - 2017-02-09}%

---+++ Version 2
_Item_ is certainly better than _child_. However, the standard OS terminology would probably be _entry_.

The directory access interface relies on this *DIRECTORY* record. It is somewhat C-like containing the count of entries
and a pointer to the data. However, it diverts from what C programmers would know from the POSIX and many other APIs.
There you often have a set of functions like *opendir*, *readdir*, and *closedir* to implement the iteration over
directory entries without ever constructing a potentially large, comprehensive list. Other languages (like Python) often
use iterators for the very same incentive. I would also greatly favor an approach that does not have to construct this list.

If this record including a pointer to a comprehensive list of entries should find much approval, I am still wondering why
the API =record= *Directory* needs to contain an explicit *ItemCount*. Wouldn't this be equivalent to =Items.all'length=?
Also doing away with repeating the name of the queried directory would eliminate the need for the *DIRECTORY* =record=
altogether. Without this =record=, even an API using a comprehensive list of entries can be based on returning a =line_vector=
instead of inventing this other =access= =type= *DirectoryItems*.

-- %BUBBLESIG{ThomasPreusser - 2017-02-14}%


At first VHDL shall not provide a high level API for directories and files. This can be solved in an open source package.

At second, not all the world is build of old POSIX. There are other implementations available giving an abstract view to a
directory. The directory name itself is included in my DIRECTORY structure because VHDL offers no way to get a handle to a
parent directory. If can now be extracted by searching for the last delimiter sign. Not all directory APIs are iterator based.
Most implementations of iterators on top of static information.

That brings me to third: POSIX internally works on a block structure which is returned by =opendir=! =readdir= is an iterator on top of that basic data structure. %BR%
https://linux.die.net/man/3/opendir %BR%
http://sourceware.org/git/?p=glibc.git;a=blob;f=sysdeps/unix/dirstream.h;h=8303f07fab6f6efaa39e51411ef924e712d995e0;hb=fa39685d5c7df2502213418bead44e9543a9b9ec

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


Does *DIRECTORY.Name* _repeat_ the path argument of the *DIR_OPEN* call used to retrieve it?

Is *DIRECTORY.ItemCount* the _same_ as *DIRECTORY.Items.all'length*?

-- %BUBBLESIG{ThomasPreusser - 2017-02-15}%

Meeting 2017-02-16, resolved that ItemCount is redundant and can be removed.   

-- %BUBBLESIG{JimLewis - 2017-02-17}%
---+++ Version 3



=DIRECTORY.Name= does not repeat the =Path= argument passed to =DIR_OPEN=. If =Path= is a relative path, the returned =Name= value returns a resolved value.

=ItemCount= is now removed.

-- %BUBBLESIG{PatrickLehmann - 2017-02-17}%


1) There is small inconsistency. 16.5.1 defines procedures for DIR_CREATEDIR(...), DIR_DELETEDIR(...), and DIR_DELETEFILE(...) whereas 16.5.4 talks about functions with this name.

2) What is the rationale for having procedures instead of impure functions for DIR_WORKINGDIR(Path), DIR_CREATEDIR(...), DIR_DELETEDIR(...) and DIR_DELETEFILE(...)? All these
subprograms have only one output parameter which can be a return value instead. This would also simplify the usage of these subprograms, e.g.

<verbatim>
if DIR_CREATEDIR("test") /= STATUS_OK then report "Could not create directory." severity error; end if;
</verbatim>

instead of

<verbatim>
variable status : DIR_CREATE_STATUS;
...
DIR_CREATEDIR("test", status);
if status /= STATUS_OK then report "Could not create directory." severity error; end if;
</verbatim>

-- %BUBBLESIG{MartinZabel - 2017-02-17}%


Please, consider specifying =DIRECTORY.Name= as _canonical_ path of the directory
   a. in &#497;6.5.1 as the comment behind its declaration and
   a. in &#497;6.5.4 in the respective bullet point.

Why does the second bullet point in &#497;6.5.4 avoid the name =LINE= but instead talks about <i>access types referencing =STRING= objects</i>?

The statement _If the parameter Recursive is set to TRUE, all subdirectories and files are deleted, even if the directory is not empty._ is not sufficient. It should
probably be stated that =DIR_DELETEDIR= will not delete a directory that is not empty _unless_ the parameter Recursive is asserted, in which case all existing subitems will be
deleted as well.

PS: Fixed some grammar.

-- %BUBBLESIG{ThomasPreusser - 2017-02-19}%

*MZ:* 1) %BR%
*PL:* Fixed that by defining overloads, see 2)

*MZ:* 2) What is the rationale for having procedures instead of impure functions ... %BR%
*PL:* The existing APIs in VHDL are using procedures to offer a status parameter (e.g. FILE_OPEN). Procedures allow us to map the Status parameter to open. I'm now providing overloads.

-- %BUBBLESIG{PatrickLehmann - 2017-02-21}%


*TBP:* Please, consider specifying =DIRECTORY.Name= as _canonical_ path of the directory %BR%
*PL:* Done

*TBP:* Why does the second bullet point in    16.5.4 avoid the name =LINE= ... %BR%
*PL:* Changed.

*TBP:* The statement [...] is not sufficient. %BR%
*PL:* Change the wording.

-- %BUBBLESIG{PatrickLehmann - 2017-02-21}%


I think a mutable global working directory is problematic as it jeopardizes the isolation of modules.

I suggest to introduce a =function PATH_CANONIZE(Path : STRING; Base : STRING :!= ".") returns LINE= to canonize arbitrary paths, optionally relative to a specified base
directory. This would also allow to drop the implied canonization of =DIR_OPEN= and help other file-related LCSs.

-- %BUBBLESIG{ThomasPreusser - 2017-02-21}%

*TBP:* I think a mutable global working directory is problematic as it jeopardizes the isolation of modules. %BR%
*PL:* VHDL has no modules. Please define what you exactly mean. The change of the working directory does not affect the location of source files or other simulator related
files. Procedure =DIR_WORKINGDIR= only affects the file and directory API (=FILE_*= / =DIR_*=), nothing else.

*TBP:* I suggest to introduce a =function PATH_CANONIZE(...) returns LINE= [...]%BR%
A =PATH_CANONIZE= subprogram would require knowledge about symbolic links, mount points and junction points in the file system.

-- %BUBBLESIG{PatrickLehmann - 2017-02-22}%
---+++ Version 5



*PL*: VHDL has no modules. Procedure DIR_WORKINGDIR only affects the file and directory API (FILE_* / DIR_*), nothing else.

*TBP*: So make it all the concurrent control flows that make up the simulation and want to use the file system API independently.
A stateful system API (as thit one wrt. the working directory) hurts composability and reuse.

*PL*: A PATH_CANONIZE subprogram would require knowledge about symbolic links, mount points and junction points in the file system.

*TBP*: No, you just call the OS. For a weaker commitment, at least, allow to make a path absolute. This function is already included
in OPEN_DIR, and Jim is about to provide a merged variant of retrieving the current file name as well. Factor it out to for reuse
and simplification of the rest of the API.

-- %BUBBLESIG{ThomasPreusser - 2017-02-22}%


FILE_OPEN has status first.   Read has valid flag last.   I think DIR_OPEN, ... should have status as the first parameter following FILE_OPEN.

I am not excited about functions that return status and have something else as an out parameter.   In general, I hate side-effects
from function.  They lead to &#34;clever&#34; code.  I want &#34;readable&#34; code.   

OTOH, the following code is growing on me.   Note the boolean "OR" operator is a short circuit operator and the first one that returns
TRUE (= STATUS_OK) is the last one that will be evaluated (at least so says the LRM:
<pre>
AlertIfNot(DIR_OPEN(...) = STATUS_OK or DIR_OPEN(...) = STATUS_OK or DIR_OPEN(...) = STATUS_OK, 
                "Directory did not open", FAILURE) ; 
</pre>

Is this really what you what?  Keep in mind that each one can potentially update MyDir.  
-- %BUBBLESIG{JimLewis - 2017-02-24}%


To_string is also implicitly defined for all scalar values.  

-- %BUBBLESIG{JimLewis - 2017-02-24}%


Why status should be first:
WRT:
<pre>procedure DIR_CREATEDIR(Path : in STRING; Status : out DIR_CREATE_STATUS; Parents : in BOOLEAN := FALSE);</pre>

My preference is:
<pre>procedure DIR_CREATEDIR(Status : out DIR_CREATE_STATUS; Path : in STRING; Parents : in BOOLEAN := FALSE);</pre>

This follows the pattern of, acknowledging that out designates a target of an operation.
Also acknowledging that when the line parameter is second the value is an input and when it is first it appends to the target:
<pre>procedure WRITE (file F: TEXT; VALUE: in STRING);
procedure FILE_OPEN (Status: out FILE_OPEN_STATUS; file F: TEXT;External_Name: in STRING;Open_Kind: in FILE_OPEN_KIND := READ_MODE);
procedure READLINE (file F: TEXT; L: inout LINE);
procedure WRITE (L: inout LINE; VALUE: in BIT;JUSTIFIED: in SIDE:= RIGHT; FIELD: in WIDTH := 0);</pre>

That leaves all versions of READ as the odd duck in the situation.
What I see is that the READ was made consistent with WRITE, which also makes sense:
<pre>procedure READ (file F: TEXT; VALUE: out STRING);
procedure READ (L: inout LINE; VALUE: out BIT);
procedure READ (L: inout LINE; VALUE: out BIT_VECTOR;GOOD: out BOOLEAN);</pre>

OTOH, in a private conversation, you indicated that status could not be last, like read, due to the optional
parameter.   I disagree.   One simply has to work harder on the authoring side, but it can be done, and
I consider consistency of the use model most important:
<pre>procedure DIR_CREATEDIR(Path : in STRING; Parents : in BOOLEAN; Status : out DIR_CREATE_STATUS );
procedure DIR_CREATEDIR(Path : in STRING; Status : out DIR_CREATE_STATUS );</pre>

Back to functions, I don't feel great about them have generalized outputs, but I do like the 
use model of DIR_OPEN that I gave previously.   

-- %BUBBLESIG{JimLewis - 2017-02-27}%


All the procedures and functions follow these rules:
   * first parameter is the altered object (Dir, File, Line, ...)
   * second parameter is the path
   * more parameters if needed
   * =Status= is the last parameter
   * Optional parameters might be the last parameters, due to language restrictions

I'm strictly against =Status= being the first parameter. Moreover I consider =FILE_OPEN(Status ...)= a design fault. And I don't
want to redo a design fault just for consistency. If we look for other subprograms in VHDL, we'll see that status information is
provided as the last parameter if no optional parameters are present.

-- %BUBBLESIG{PatrickLehmann - 2017-02-28}%

Implemented optional parameters as procedure overloads to fulfill Jim's demands for coding style.

-- %BUBBLESIG{PatrickLehmann - 2017-03-02}%
---+++ Version 6



@PL_02-28:  Other than FILE_OPEN, what standard defined procedures return an enumerated value as status? What standard defined
procedures return boolean as status?

@PL_03-02:   Why do you think the definition order of FILE_OPEN a fault?

-- %BUBBLESIG{JimLewis - 2017-03-05}%


When you start a simulation running, some simulators move you to a directory other than the one in which you started. I think we
may need a way to get the directory of some reference point, such as current vhdl code or tool starting directory, ???.

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


24 years ago, FILE_OPEN was introduced to VHDL. You have not provided any insight why it is bad and causing you so many issues.    

I am big on consistency. Find a way to make things consistent. You could introduce a new overloaded FILE_OPEN, however, I
think first you need to support why you think the current FILE_OPEN is the wrong pattern.   

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


There is no consistency pattern, with only one existing subprogram in VHDL that has a status parameter of such form (plus one overload).

If we widen the scope and also look at =READ= subprograms, we see that the =Good= parameter is listed at the end of each subprogram,
if present. This strengths my point of view. In addition, 6 reviewers of this LCS have no problem with my proposed interface.

There is no issue with the =FILE_OPEN= procedure except for that it does not apply to common rules how to order parameters in an interface
as described in various books. Of cause these rules are not graved in stone, but I don&#39;t like to redo a design fault from VHDL-1993. I also
like consistency, that&#39;s why I propose this interface. But, consistency is no excuse to redo design faults!

If you like, I can propose similar overloads for the existing file API. But this would require another LCS ...

-- %BUBBLESIG{PatrickLehmann - 2017-03-06}%
%COMMENT%</sticky>

</noautolink>
Topic revision: r1 - 2017-07-23 - 22:33:51 - TWikiGuest
P1076