Language Change Specification for Accessing FILE_NAME and LINE_NUMBER of a Named Entity

LCS Number:	LCS-2016-015b
Version:	1 {21-Feb-2017} 2 {22-Feb-2017} 3 {14-Mar-2017}
Date:	14-Mar-2017
Status:	Voting
Author:	Patrick Lehmann
Email:	Main.PatrickLehmann
Source Doc:	- - - -
Summary:	Get source code positions of named entities.

Voting Results: Cast your votes here

Yes:

1. Steve Grout - 2017-02-22 - ver 2
2. Patrick Lehmann - 2017-03-14 - ver 3
3. Jim Lewis- 2017-03-06 - ver 3.

No:

Abstain:

1. Lars Asplund- 2017-03-23 - ver 3 - Lacking use case

Style Notes

Changes are shown in red font.
Deletions are crossed out.
Editing or reviewing notes in green font.

Reviewing Notes

This is a competing idea on how to solve LCS 015a.

Version 2:

• Aligned with LCS 015 / 015a
• Fix meaning of file_line -> first lexical element

Version 1:
This version shows an attribute based approach to get to FILE_NAME and LINE_NUMBER of a named entity (see 7.2).

package pkg is
  function foo return boolean is
end package;

package body pkg is
  function foo return boolean is
  begin
    report "foo: " & INTEGER'image(foo'LINE_NUMBER);
  end function;
end package body;

This returns "foo: 6". But not

• "foo: 2" where the forward declaration appears and not
• "foo: 8" where the attribute is used.

The get the line of the report statement, a label before report or and an expression can be used: INTEGER'image(foo'LINE_NUMBER + 2).

Version 2:

• Changed FILE_NAME to FILE_PATH (full name)
• Added FILE_NAME for the simple file name
• Fixed section number and name

Details of Language Change

16.2.5 Predefined attributes of named entities

[Editor note: Insert the next table after table for E'PATH_NAME.]

E'FILE_NAME	Kind:	Value
	Prefix:	Any prefix E that denotes a named entity.
	Result type:	STRING.
	Result:	The name of the design file without the file path in which E was fully defined.
E'FILE_PATH	Kind:	Value
	Prefix:	Any prefix E that denotes a named entity.
	Result type:	STRING.
	Result:	The fully resolved absolute path without the file name of the design file in which E was fully defined.
E'FILE_LINE	Kind:	Value
	Prefix:	Any prefix E that denotes a named entity.
	Result type:	POSITIVE.
	Result:	The line number in the design file where the first lexical element of E appeared and E was fully defined.

Comments

Version 1

I do not see this proposal competing with LCS 015a as the latter provides a direct solution for the most common use case in error reporting. The label approach looks somewhat clumsy. Nonetheless, this proposal has an added value in flexibly accessing the file information of arbitrary accessible objects.

-- Thomas Preusser - 2017-02-21

JL: Why an attribute when a simple subprogram can return this information. *PL: I noticed this LCS doesn't return always the same values as LCS 015a.

As I explained in my email announcing both LCS 015a and LCS 015b, I wrote that attributes can be evaluated at analysis type and are globally static. That's not the case for your function based API.

My NO vote on LCS 015a was changed to a NO for a technical issue. I still think we need this LCS too, because LCS 015a doesn't give us where a named entity was defined, only where it's executed. So in conclusion I think we should have both complementary solutions.

-- Patrick Lehmann - 2017-03-07

PL: LCS 015a doesn't give us where a named entity was defined, only where it's executed

I get the point: attributes are globally static; functions are dynamic. Both are useful/needed. But the functions and attributes are the same, e.g. FILE_NAME. This is going to be incredibly confusing. I don't like the idea of proliferating identifiers any more than anyone else, but this is effectively overloading, but with different behaviours. (OTOH if you really want to overload, decide whether to use LINE_NUMBER or FILE_LINE).

-- Mark Zwolinski - 2017-03-07

I'll change that to whatever Jim uses.

-- Patrick Lehmann - 2017-03-07

What is E'LINE_NUMBER for an architecture declaration? Is it the end?

-- Jim Lewis - 2017-03-11

JL: What is E'LINE_NUMBER for an architecture declaration?
PL: Where architecture appears. I fixed the text in version 2.

-- Patrick Lehmann - 2017-03-14

@TODO: at meeting 16-Mar: Does lots of cool things. Got any compelling use models?

-- Jim Lewis - 2017-03-16

LCS 015 / 015a can only be used for sequential code. This LCS allows a user to get line and file information of all declared VHDL entities for reporting purposes.

-- Patrick Lehmann - 2017-03-20

For the use case of locating a log entry made by a report statement this becomes less convenient for the user when compared to having a function. Each report statement would need a unique label. For me the whole point is to get a location of a log entry without manually inserting such IDs.

Regardless if attributes or functions are used I wouldn't create many such report statements before I create a convenience function that inserts that automatically. In VUnit we solve that by preprocessing the VHDL code but the call path LCS is what I really need so that I can get the caller location.

Attributes can also provide the location of any entity but I think we need to identify the value adding use cases for that. Without a strong use case I don't think this will be worth the effort.

-- Lars Asplund - 2017-03-23