Language Change Specification for Reflection API

LCS Number:	LCS-2016-041
Version:	4
Date:	20-Jun-2017
Status:	Approved
Author:	Lieven Lemiengre Patrick Lehmann
Source Doc:	Record Introspection Type Reflection
More:	Proposal Examples LCS History
Summary:	Adds reflection over most types.

Style Notes

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

Reviewing Notes

Reflection allows the user to lift any VHDL value into a generic data type called VALUE_MIRROR. This value mirror is implemented as a protected type, it's implementation is simulator specific and completely hidden from the user. Only a public interface is provided in a package called REFLECTION. A value mirror holds a copy to the value that it encapsulates and a reference the meta data (or SUBTYPE_MIRROR) that describes the value. A SUBTYPE_MIRROR is a fully elaborated description of a subtype.

There are 9 kinds of value and type mirrors, one for each VHDL type (sub)class (enumeration, integer, record, array, ... see the TYPE_CLASS enumeration). You can cast a mirror to it's more precise type class mirror with the to_* methods.

The LCS content is structured as follows:

1. A general section introduces the concept of mirrors and lists the relation of all 20 mirrors.
2. The package declaration is given
3. The common/unspecific mirror pair is described.
   The LCS introduces a new form on how to describe protected type behavior. It's similar to attribute descriptions.
4. 9 more sections describe each specific mirror pair
5. Two examples are presented.

Reflection with mirrors is based on a paper by Gilad Bracha. See http://bracha.org/mirrors.pdf

Details of Language Change

16.2.2 Predefined attributes of types and objects

[Reviewer note: Add after O'SUBTYPE.]
T'REFLECT	Kind:	function
	Prefix:	Any type or subtype T.
	Result type:	STD.REFLECTION.SUBTYPE_MIRROR.
	Result:	An access value to a value of type SUBTYPE_MIRROR_PT mirroring T.
O'REFLECT	Kind:	function
	Prefix:	Any object O of type or subtype T.
	Result type:	STD.REFLECTION.VALUE_MIRROR.
	Result:	An access value to a value of type VALUE_MIRROR_PT mirroring O.

16.12 Reflection package [NEW]

16.12.1 General [NEW]

Package REFLECTION contains protected type declarations and access types to these protected types for a
reflection API.

The reflection API provides access to type and value information of VHDL types and objects. The
provided information is provided through protected type instances, which are called mirrors. It's said
that such a protected type mirrors the internal data and meta data of a tool and provides them for
the user. Mirrors allow a user to inspect objects and types in generic way.

Each VHDL object has two corresponding mirrors: A value mirror and a subtype mirror. Each VHDL type
or subtype has a corresponding subtype mirror. Mirror instances are created when the attribute 'REFLECT
is evaluated.

A value mirror contains a consistent copy of the mirrored object's value. This means, if the object's value
changes, the stored value in the mirror instance does not change. The protected type of a value mirror provides:

• access to the copied object value through a method
• the same operations as provided by object attributes in the form of methods
• a method to access the corresponding subtype of the mirrored object.

A subtype mirror represents the meta data accompanying a VHDL object or the meta data of a mirrored
VHDL type or subtype. The protected type of a subtype mirror provides:

• the same operations as provided by type or subtype attributes in the form of methods.

This API provides 10 value mirrors, one for each value's type class or subclass, as well as one common
value mirror representing untyped values. Similarly, the API provides 10 subtype mirrors, one for each type's
class or subclass and one common subtype mirror representing an unspecific type. The handling of
mirror instances is eased by providing access types for each mirror protected type.

The following table show all available mirror protected types and their relation:

Type (Sub)Class		Value Mirror	Corresponding Subtype Mirror
Unclassified		VALUE_MIRROR_PT	SUBTYPE_MIRROR_PT
Scalar
	Enumeration	ENUMERATION_VALUE_MIRROR_PT	ENUMERATION_SUBTYPE_MIRROR_PT
	Integer	INTEGER_VALUE_MIRROR_PT	INTEGER_SUBTYPE_MIRROR_PT
	Floating	FLOATING_VALUE_MIRROR_PT	FLOATING_SUBTYPE_MIRROR_PT
	Physical	PHYSICAL_VALUE_MIRROR_PT	PHYSICAL_SUBTYPE_MIRROR_PT
Record		RECORD_VALUE_MIRROR_PT	RECORD_SUBTYPE_MIRROR_PT
Array		ARRAY_VALUE_MIRROR_PT	ARRAY_SUBTYPE_MIRROR_PT
Access		ACCESS_VALUE_MIRROR_PT	ACCESS_SUBTYPE_MIRROR_PT
File		FILE_VALUE_MIRROR_PT	FILE_SUBTYPE_MIRROR_PT
Protected		PROTECTED_VALUE_MIRROR_PT	PROTECTED_SUBTYPE_MIRROR_PT

16.12.2 Package declaration [NEW]

package REFLECTION is
  type    INDEX           is       range INTEGER'low to INTEGER'high;
  subtype NATURAL_INDEX   is INDEX range 0 to INDEX'high;
  subtype POSITIVE_INDEX  is INDEX range 1 to INDEX'high;
  subtype DIMENSION       is INDEX range 1 to INDEX'high;
  type    INDEX_VECTOR    is array(DIMENSION range <>) of INDEX;

  -- Incomplete type declarations
  type VALUE_MIRROR;
  type SUBTYPE_MIRROR;

  
  -- Enumeration subtype/value mirror
  type ENUMERATION_SUBTYPE_MIRROR;
  type ENUMERATION_VALUE_MIRROR_PT is protected
    impure function get_subtype_mirror return ENUMERATION_SUBTYPE_MIRROR;
    impure function to_value_mirror    return VALUE_MIRROR;

    impure function pos   return INTEGER;
    impure function image return STRING;
  end protected;
  type ENUMERATION_VALUE_MIRROR is access ENUMERATION_VALUE_MIRROR_PT;
  
  type ENUMERATION_SUBTYPE_MIRROR_PT is protected
    impure function to_subtype_mirror return SUBTYPE_MIRROR;
    
    impure function enumeration_literal(literal_idx : NATURAL_INDEX) return ENUMERATION_VALUE_MIRROR;
    impure function enumeration_literal(literal_name : STRING)       return ENUMERATION_VALUE_MIRROR;
    
    impure function simple_name return STRING;
    impure function left        return ENUMERATION_VALUE_MIRROR;
    impure function right       return ENUMERATION_VALUE_MIRROR;
    impure function low         return ENUMERATION_VALUE_MIRROR;
    impure function high        return ENUMERATION_VALUE_MIRROR;
    impure function length      return POSITIVE_INDEX;
    impure function ascending   return BOOLEAN;
  end protected;
  type ENUMERATION_SUBTYPE_MIRROR is access ENUMERATION_SUBTYPE_MIRROR_PT;


  -- Integer subtype/value mirror
  type INTEGER_SUBTYPE_MIRROR;
  type INTEGER_VALUE_MIRROR_PT is protected
    impure function get_subtype_mirror return INTEGER_SUBTYPE_MIRROR;
    impure function to_value_mirror    return VALUE_MIRROR;

    impure function value return INTEGER;
    impure function image return STRING;
  end protected;
  type INTEGER_VALUE_MIRROR is access INTEGER_VALUE_MIRROR_PT;

  type INTEGER_SUBTYPE_MIRROR_PT is protected
    impure function to_subtype_mirror return SUBTYPE_MIRROR;

    impure function simple_name return STRING;
    impure function left        return INTEGER_VALUE_MIRROR;
    impure function right       return INTEGER_VALUE_MIRROR;
    impure function low         return INTEGER_VALUE_MIRROR;
    impure function high        return INTEGER_VALUE_MIRROR;
    impure function length      return INDEX;
    impure function ascending   return BOOLEAN;
  end protected;
  type INTEGER_SUBTYPE_MIRROR is access INTEGER_SUBTYPE_MIRROR_PT;


  -- Floating-point subtype/value mirror
  type FLOATING_SUBTYPE_MIRROR;
  type FLOATING_VALUE_MIRROR_PT is protected
    impure function get_subtype_mirror return FLOATING_SUBTYPE_MIRROR;
    impure function to_value_mirror    return VALUE_MIRROR;

    impure function value return REAL;
    impure function image return STRING;
  end protected;
  type FLOATING_VALUE_MIRROR is access FLOATING_VALUE_MIRROR_PT;
  
  type FLOATING_SUBTYPE_MIRROR_PT is protected
    impure function to_subtype_mirror return SUBTYPE_MIRROR;

    impure function simple_name return STRING;
    impure function left        return FLOATING_VALUE_MIRROR;
    impure function right       return FLOATING_VALUE_MIRROR;
    impure function low         return FLOATING_VALUE_MIRROR;
    impure function high        return FLOATING_VALUE_MIRROR;
    impure function ascending   return BOOLEAN;
  end protected;
  type FLOATING_SUBTYPE_MIRROR is access FLOATING_SUBTYPE_MIRROR_PT;


  -- Physical subtype/value mirror
  type PHYSICAL_SUBTYPE_MIRROR;
  type PHYSICAL_VALUE_MIRROR_PT is protected
    impure function get_subtype_mirror return PHYSICAL_SUBTYPE_MIRROR;
    impure function to_value_mirror    return VALUE_MIRROR;
    
    impure function unit_index return INDEX;
    impure function value      return INTEGER;
    impure function image      return STRING;
  end protected;
  type PHYSICAL_VALUE_MIRROR is access PHYSICAL_VALUE_MIRROR_PT;
  
  type PHYSICAL_SUBTYPE_MIRROR_PT is protected
    impure function to_subtype_mirror return SUBTYPE_MIRROR;
    
    impure function units_length                   return INDEX;
    impure function unit_name (unit_idx: INDEX)    return STRING;
    impure function unit_index(unit_name : STRING) return INDEX;
    impure function scale(unit_idx: INDEX)         return NATURAL;
    impure function scale(unit_name: INDEX)        return NATURAL;
    
    impure function simple_name return STRING;
    impure function left        return PHYSICAL_VALUE_MIRROR;
    impure function right       return PHYSICAL_VALUE_MIRROR;
    impure function low         return PHYSICAL_VALUE_MIRROR;
    impure function high        return PHYSICAL_VALUE_MIRROR;
    impure function length      return INDEX;
    impure function ascending   return BOOLEAN;
  end protected;
  type PHYSICAL_SUBTYPE_MIRROR is access PHYSICAL_SUBTYPE_MIRROR_PT;

  
  -- Record subtype/value mirror
  type RECORD_SUBTYPE_MIRROR;
  type RECORD_VALUE_MIRROR_PT is protected
    impure function get_subtype_mirror return RECORD_SUBTYPE_MIRROR;
    impure function to_value_mirror    return VALUE_MIRROR;

    impure function get(element_idx : INDEX)   return VALUE_MIRROR;
    impure function get(element_name : STRING) return VALUE_MIRROR;
  end protected;
  type RECORD_VALUE_MIRROR is access RECORD_VALUE_MIRROR_PT;
  
  type RECORD_SUBTYPE_MIRROR_PT is protected
    impure function to_subtype_mirror return SUBTYPE_MIRROR;

    impure function length                                 return INDEX;
    impure function element_name(element_idx : INDEX)      return STRING;
    impure function element_index(element_name : STRING)   return INDEX;
    impure function element_subtype(element_idx : INDEX)   return SUBTYPE_MIRROR;
    impure function element_subtype(element_name : STRING) return SUBTYPE_MIRROR;
    
    impure function simple_name return string;
  end protected;
  type RECORD_SUBTYPE_MIRROR is access RECORD_SUBTYPE_MIRROR_PT;


  -- Array subtype/value mirror
  type ARRAY_SUBTYPE_MIRROR;
  type ARRAY_VALUE_MIRROR_PT is protected
    impure function get_subtype_mirror return ARRAY_SUBTYPE_MIRROR;
    impure function to_value_mirror    return VALUE_MIRROR;

    impure function get(idx : INDEX)              return VALUE_MIRROR;
    impure function get(idx1, idx2 : INDEX)       return VALUE_MIRROR;
    impure function get(idx1, idx2, idx3 : INDEX) return VALUE_MIRROR;
    impure function get(idx : INDEX_VECTOR)       return VALUE_MIRROR;
  end protected;
  type ARRAY_VALUE_MIRROR is access ARRAY_VALUE_MIRROR_PT;
  
  type ARRAY_SUBTYPE_MIRROR_PT is protected
    impure function to_subtype_mirror return SUBTYPE_MIRROR;

    impure function dimensions                          return DIMENSION;
    impure function index_subtype(idx : DIMENSION := 1) return SUBTYPE_MIRROR;
    impure function element_subtype                     return SUBTYPE_MIRROR;
    
    impure function simple_name return string;
    impure function left(idx : DIMENSION := 1)      return INDEX;
    impure function right(idx : DIMENSION := 1)     return INDEX;
    impure function low(idx : DIMENSION := 1)       return INDEX;
    impure function high(idx : DIMENSION := 1)      return INDEX;
    impure function length(idx : DIMENSION := 1)    return INDEX;
    impure function ascending(idx : DIMENSION := 1) return BOOLEAN;
  end protected;
  type ARRAY_SUBTYPE_MIRROR is access ARRAY_SUBTYPE_MIRROR_PT;


  -- Access subtype/value mirror
  type ACCESS_SUBTYPE_MIRROR;
  type ACCESS_VALUE_MIRROR_PT is protected
    impure function get_subtype_mirror return ACCESS_SUBTYPE_MIRROR;
    impure function to_value_mirror    return VALUE_MIRROR;

    -- 
    impure function get return VALUE_MIRROR;
    impure function is_null return boolean;
  end protected;
  type ACCESS_VALUE_MIRROR is access ACCESS_VALUE_MIRROR_PT;
  
  type ACCESS_SUBTYPE_MIRROR_PT is protected
    impure function to_subtype_mirror return SUBTYPE_MIRROR;

    impure function simple_name        return STRING;
    impure function designated_subtype return SUBTYPE_MIRROR;
  end protected;
  type ACCESS_SUBTYPE_MIRROR is access ACCESS_SUBTYPE_MIRROR_PT;
  

  -- File subtype/value mirror
  type FILE_SUBTYPE_MIRROR;
  type FILE_VALUE_MIRROR_PT is protected
    impure function get_subtype_mirror return FILE_SUBTYPE_MIRROR;
    impure function to_value_mirror    return VALUE_MIRROR;
    
    impure function file_logical_name return STRING;
    impure function file_open_kind    return FILE_OPEN_KIND;
  end protected;
  type FILE_VALUE_MIRROR is access FILE_VALUE_MIRROR_PT;
  
  type FILE_SUBTYPE_MIRROR_PT is protected
    impure function to_subtype_mirror return SUBTYPE_MIRROR;
    
    impure function simple_name        return STRING;
    impure function designated_subtype return SUBTYPE_MIRROR;
  end protected;
  type FILE_SUBTYPE_MIRROR is access FILE_SUBTYPE_MIRROR_PT;
  

  -- Protected subtype/value mirror
  type PROTECTED_SUBTYPE_MIRROR;
  type PROTECTED_VALUE_MIRROR_PT is protected
    impure function get_subtype_mirror return PROTECTED_SUBTYPE_MIRROR;
    impure function to_value_mirror    return VALUE_MIRROR;
  end protected;
  type PROTECTED_VALUE_MIRROR is access PROTECTED_VALUE_MIRROR_PT;
  
  type PROTECTED_SUBTYPE_MIRROR_PT is protected
    impure function to_subtype_mirror return SUBTYPE_MIRROR;
    
    impure function simple_name return STRING;
  end protected;
  type PROTECTED_SUBTYPE_MIRROR is access PROTECTED_SUBTYPE_MIRROR_PT;

  
  -- Type classes and sub-classes
  type TYPE_CLASS is (
    CLASS_ENUMERATION,
    CLASS_INTEGER,
    CLASS_FLOATING,
    CLASS_PHYSICAL,
    CLASS_RECORD,
    CLASS_ARRAY,
    CLASS_ACCESS,
    CLASS_FILE,
    CLASS_PROTECTED
  );
  alias VALUE_CLASS is TYPE_CLASS;


  -- Subtype/value mirror
  type SUBTYPE_MIRROR_PT is protected
    impure function get_type_class return TYPE_CLASS;

    -- get the corresponding representation
    impure function to_enumeration return ENUMERATION_SUBTYPE_MIRROR;
    impure function to_integer     return INTEGER_SUBTYPE_MIRROR;
    impure function to_floating    return FLOATING_SUBTYPE_MIRROR;
    impure function to_physical    return PHYSICAL_SUBTYPE_MIRROR;
    impure function to_record      return RECORD_SUBTYPE_MIRROR;
    impure function to_array       return ARRAY_SUBTYPE_MIRROR;
    impure function to_access      return ACCESS_SUBTYPE_MIRROR;
    impure function to_file        return FILE_SUBTYPE_MIRROR;
    impure function to_protected   return PROTECTED_SUBTYPE_MIRROR;
    
    impure function simple_name return STRING;
  end protected;
  type SUBTYPE_MIRROR is access SUBTYPE_MIRROR_PT;

  type VALUE_MIRROR_PT is protected
    impure function get_value_class    return VALUE_CLASS;
    impure function get_subtype_mirror return SUBTYPE_MIRROR;

    -- get the corresponding representation
    impure function to_enumeration return ENUMERATION_VALUE_MIRROR;
    impure function to_integer     return INTEGER_VALUE_MIRROR;
    impure function to_floating    return FLOATING_VALUE_MIRROR;
    impure function to_physical    return PHYSICAL_VALUE_MIRROR;
    impure function to_record      return RECORD_VALUE_MIRROR;
    impure function to_array       return ARRAY_VALUE_MIRROR;
    impure function to_access      return ACCESS_VALUE_MIRROR;
    impure function to_file        return FILE_VALUE_MIRROR;
    impure function to_protected   return PROTECTED_VALUE_MIRROR;
  end protected;
  type VALUE_MIRROR is access VALUE_MIRROR_PT;
end package REFLECTION;


-- Implementation specific
-- -------------------------------------
-- package body REFLECTION is
-- end package body REFLECTION;

16.12.3 Package description [NEW]

16.12.3.1 General [NEW]

These methods of the protected types are described as follows. For each method, the following information is provided:

• Parameters, if any exists
• Return type
• Result of evaluating the method
• Errors that can occur
• Any further restrictions or comments that apply

16.12.3.2 Common subtype and value mirrors [NEW]

The integer type INDEX represents an index value used by the reflection API. The subtypes NATURAL_INDEX represent a natural and
POSITIVE_INDEX represent a positive index value. The subtype DIMENSION represents an array dimension. The array INDEX_VECTOR
represents a list of indices as used to index multi dimensional arrays.

The enumeration TYPE_CLASS contains one value per type class or subclass. The alias VALUE_CLASS denotes the same enumeration.

The protected type SUBTYPE_MIRROR_PT mirrors an arbitrary subtype. It provides the following methods:

get_type_class
Return type	TYPE_CLASS
Behavior	Returns a type class of the mirrored subtype.
to_enumeration
Return type	ENUMERATION_SUBTYPE_MIRROR
Behavior	Returns an ENUMERATION_SUBTYPE_MIRROR_PT instance of the specific subtype mirror.
Errors	It is an error if the specific subtype mirror is not an enumeration subtype mirror.
to_integer
Return type	INTEGER_SUBTYPE_MIRROR
Behavior	Returns an INTEGER_SUBTYPE_MIRROR_PT instance of the specific subtype mirror.
Errors	It is an error if the specific subtype mirror is not an integer subtype mirror.
to_floating
Return type	FLOATING_SUBTYPE_MIRROR
Behavior	Returns a FLOATING_SUBTYPE_MIRROR_PT instance of the specific subtype mirror.
Errors	It is an error if the specific subtype mirror is not a floating subtype mirror.
to_physical
Return type	PHYSICAL_SUBTYPE_MIRROR
Behavior	Returns a PHYSICAL_SUBTYPE_MIRROR_PT instance of the specific subtype mirror.
Errors	It is an error if the specific subtype mirror is not a physical subtype mirror.
to_record
Return type	RECORD_SUBTYPE_MIRROR
Behavior	Returns a RECORD_SUBTYPE_MIRROR_PT instance of the specific subtype mirror.
Errors	It is an error if the specific subtype mirror is not a record subtype mirror.
to_array
Return type	ARRAY_SUBTYPE_MIRROR
Behavior	Returns an ARRAY_SUBTYPE_MIRROR_PT instance of the specific subtype mirror.
Errors	It is an error if the specific subtype mirror is not an array subtype mirror.
to_access
Return type	ACCESS_SUBTYPE_MIRROR
Behavior	Returns an ACCESS_SUBTYPE_MIRROR_PT instance of the specific subtype mirror.
Errors	It is an error if the specific subtype mirror is not an access subtype mirror.
to_file
Return type	FILE_SUBTYPE_MIRROR
Behavior	Returns a FILE_SUBTYPE_MIRROR_PT instance of the specific subtype mirror.
Errors	It is an error if the specific subtype mirror is not a file subtype mirror.
to_protected
Return type	PROTECTED_SUBTYPE_MIRROR
Behavior	Returns a PROTECTED_SUBTYPE_MIRROR_PT instance of the specific subtype mirror.
Errors	It is an error if the specific subtype mirror is not a protected subtype mirror.
simple_name
Return type	STRING
Behavior	Returns the simple name of the corresponding subtype.

The protected type VALUE_MIRROR_PT mirrors an arbitrary value. It provides the following methods:

get_value_class
Return type	VALUE_CLASS
Behavior	Returns a value class of the mirrored value.
get_subtype_mirror
Return type	SUBTYPE_MIRROR
Behavior	Returns the corresponding subtype mirror.
to_enumeration
Return type	ENUMERATION_VALUE_MIRROR
Behavior	Returns an ENUMERATION_VALUE_MIRROR_PT instance of the specific value mirror.
Errors	It is an error if the specific value mirror is not an enumeration value mirror.
to_integer
Return type	INTEGER_VALUE_MIRROR
Behavior	Returns an INTEGER_VALUE_MIRROR_PT instance of the specific value mirror.
Errors	It is an error if the specific value mirror is not an integer value mirror.
to_floating
Return type	FLOATING_VALUE_MIRROR
Behavior	Returns a FLOATING_VALUE_MIRROR_PT instance of the specific value mirror.
Errors	It is an error if the specific value mirror is not a floating value mirror.
to_physical
Return type	PHYSICAL_VALUE_MIRROR
Behavior	Returns a PHYSICAL_VALUE_MIRROR_PT instance of the specific value mirror.
Errors	It is an error if the specific value mirror is not a physical value mirror.
to_record
Return type	RECORD_VALUE_MIRROR
Behavior	Returns a RECORD_VALUE_MIRROR_PT instance of the specific value mirror.
Errors	It is an error if the specific value mirror is not a record value mirror.
to_array
Return type	ARRAY_VALUE_MIRROR
Behavior	Returns an ARRAY_VALUE_MIRROR_PT instance of the specific value mirror.
Errors	It is an error if the specific value mirror is not an array value mirror.
to_access
Return type	ACCESS_VALUE_MIRROR
Behavior	Returns an ACCESS_VALUE_MIRROR_PT instance of the specific value mirror.
Errors	It is an error if the specific value mirror is not an access value mirror.
to_file
Return type	FILE_VALUE_MIRROR
Behavior	Returns a FILE_VALUE_MIRROR_PT instance of the specific value mirror.
Errors	It is an error if the specific value mirror is not a file value mirror.
to_protected
Return type	PROTECTED_VALUE_MIRROR
Behavior	Returns a PROTECTED_VALUE_MIRROR_PT instance of the specific value mirror.
Errors	It is an error if the specific value mirror is not a protected value mirror.

The access type SUBTYPE_MIRROR designates a SUBTYPE_MIRROR_PT. The access type VALUE_MIRROR designates a VALUE_MIRROR_PT.

16.12.3.3 Enumeration subtype and value mirrors [NEW]

The protected type ENUMERATION_SUBTYPE_MIRROR_PT mirrors an enumeration subtype. It provides the following methods:

to_subtype_mirror
Return type	SUBTYPE_MIRROR
Behavior	Returns a SUBTYPE_MIRROR_PT instance representing this mirror as a common subtype mirror.
enumeration_literal
Parameters	literal_idx : NATURAL_INDEX
Return type	ENUMERATION_VALUE_MIRROR
Behavior	Returns an ENUMERATION_VALUE_MIRROR_PT instance representing the literal_idx-th enumeration literal.
Errors	It is an error if the parameter literal_idx is not in the range denoted by ENUMERATION_SUBTYPE_MIRROR_PT.left to ENUMERATION_SUBTYPE_MIRROR_PT.right.
enumeration_literal
Parameters	literal_name : STRING
Return type	ENUMERATION_VALUE_MIRROR
Behavior	Returns an ENUMERATION_VALUE_MIRROR_PT instance, whose string representation matches the parameter literal_name.
Errors	It is an error if the parameter literal_name does not denote an enumeration literal of the enumeration type mirrored by ENUMERATION_SUBTYPE_MIRROR_PT.
simple_name
Return type	STRING
Behavior	Returns the simple name of the corresponding subtype.
left
Return type	ENUMERATION_VALUE_MIRROR
Behavior	Returns an ENUMERATION_VALUE_MIRROR_PT instance representing the left bound of the subtype.
right
Return type	ENUMERATION_VALUE_MIRROR
Behavior	Returns an ENUMERATION_VALUE_MIRROR_PT instance representing the right bound of the subtype.
low
Return type	ENUMERATION_VALUE_MIRROR
Behavior	Returns an ENUMERATION_VALUE_MIRROR_PT instance representing the lower bound of the subtype.
high
Return type	ENUMERATION_VALUE_MIRROR
Behavior	Returns an ENUMERATION_VALUE_MIRROR_PT instance representing the upper bound of the subtype.
length
Return type	POSITIVE_INDEX
Behavior	Returns the number of enumeration literals for the corresponding subtype.
ascending
Return type	BOOLEAN
Behavior	Returns a TRUE if the corresponding subtype's constraint range is in ascending order, otherwise FALSE.

The protected type ENUMERATION_VALUE_MIRROR_PT mirrors an enumeration type value. It provides the following methods:

get_subtype_mirror
Return type	ENUMERATION_SUBTYPE_MIRROR
Behavior	Returns the corresponding subtype mirror.
to_value_mirror
Return type	VALUE_MIRROR
Behavior	Returns the common value mirror for this mirror.
pos
Return type	INTEGER
Behavior	Returns the position number of the mirrored enumeration type value.
image
Return type	STRING
Behavior	Returns the string representation of the mirrored enumeration type value.

The access type ENUMERATION_SUBTYPE_MIRROR designates an ENUMERATION_SUBTYPE_MIRROR_PT. The access type
ENUMERATION_VALUE_MIRROR designates an ENUMERATION_VALUE_MIRROR_PT.

16.12.3.4 Integer subtype and value mirrors [NEW]

The protected type INTEGER_SUBTYPE_MIRROR_PT mirrors an integer subtype. It provides the following methods:

to_subtype_mirror
Return type	SUBTYPE_MIRROR
Behavior	Returns a SUBTYPE_MIRROR_PT instance representing this mirror as a common subtype mirror.
simple_name
Return type	STRING
Behavior	Returns the simple name of the corresponding subtype.
left
Return type	INTEGER_VALUE_MIRROR
Behavior	Returns an INTEGER_VALUE_MIRROR_PT instance representing the left bound of the subtype.
right
Return type	INTEGER_VALUE_MIRROR
Behavior	Returns an INTEGER_VALUE_MIRROR_PT instance representing the right bound of the subtype.
low
Return type	INTEGER_VALUE_MIRROR
Behavior	Returns an INTEGER_VALUE_MIRROR_PT instance representing the lower bound of the subtype.
high
Return type	INTEGER_VALUE_MIRROR
Behavior	Returns an INTEGER_VALUE_MIRROR_PT instance representing the upper bound of the subtype.
length
Return type	POSITIVE_INDEX
Behavior	Returns the number of position numbers in the range of the corresponding subtype.
ascending
Return type	BOOLEAN
Behavior	Returns a TRUE if the corresponding subtype's constraint range is in ascending order, otherwise FALSE.

The protected type INTEGER_VALUE_MIRROR_PT mirrors an integer type value. It provides the following methods:

get_subtype_mirror
Return type	INTEGER_SUBTYPE_MIRROR
Behavior	Returns the corresponding subtype mirror.
to_value_mirror
Return type	VALUE_MIRROR
Behavior	Returns the common value mirror for this mirror.
value
Return type	INTEGER
Behavior	Returns the position number of the mirrored integer value.
image
Return type	STRING
Behavior	Returns the string representation of the mirrored integer value.

The access type INTEGER_SUBTYPE_MIRROR designates an INTEGER_SUBTYPE_MIRROR_PT. The access type
INTEGER_VALUE_MIRROR designates an INTEGER_VALUE_MIRROR_PT.

16.12.3.5 Floating subtype and value mirrors [NEW]

The protected type FLOATING_SUBTYPE_MIRROR_PT mirrors a floating subtype. It provides the following methods:

to_subtype_mirror
Return type	SUBTYPE_MIRROR
Behavior	Returns a SUBTYPE_MIRROR_PT instance representing this mirror as a common subtype mirror.
simple_name
Return type	STRING
Behavior	Returns the simple name of the corresponding subtype.
left
Return type	FLOATING_VALUE_MIRROR
Behavior	Returns a FLOATING_VALUE_MIRROR_PT instance representing the left bound of the subtype.
right
Return type	FLOATING_VALUE_MIRROR
Behavior	Returns a FLOATING_VALUE_MIRROR_PT instance representing the right bound of the subtype.
low
Return type	FLOATING_VALUE_MIRROR
Behavior	Returns a FLOATING_VALUE_MIRROR_PT instance representing the lower bound of the subtype.
high
Return type	FLOATING_VALUE_MIRROR
Behavior	Returns a FLOATING_VALUE_MIRROR_PT instance representing the upper bound of the subtype.
ascending
Return type	BOOLEAN
Behavior	Returns a TRUE if the corresponding subtype's constraint range is in ascending order, otherwise FALSE.

The protected type FLOATING_VALUE_MIRROR_PT mirrors a floating type value. It provides the following methods:

get_subtype_mirror
Return type	FLOATING_SUBTYPE_MIRROR
Behavior	Returns the corresponding subtype mirror.
to_value_mirror
Return type	VALUE_MIRROR
Behavior	Returns the common value mirror for this mirror.
value
Return type	REAL
Behavior	Returns the real value of the mirrored floating type value.
image
Return type	STRING
Behavior	Returns the string representation of the mirrored floating type value.

The access type FLOATING_SUBTYPE_MIRROR designates a FLOATING_SUBTYPE_MIRROR_PT. The access type
FLOATING_VALUE_MIRROR designates a FLOATING_VALUE_MIRROR_PT.

16.12.3.6 Physical subtype and value mirrors [NEW]

The protected type PHYSICAL_SUBTYPE_MIRROR_PT mirrors a physical subtype. It provides the following methods:

to_subtype_mirror
Return type	SUBTYPE_MIRROR
Behavior	Returns a SUBTYPE_MIRROR_PT instance representing this mirror as a common subtype mirror.
simple_name
Return type	STRING
Behavior	Returns the simple name of the corresponding subtype.
left
Return type	PHYSICAL_VALUE_MIRROR
Behavior	Returns a PHYSICAL_VALUE_MIRROR_PT instance representing the left bound of the subtype.
right
Return type	PHYSICAL_VALUE_MIRROR
Behavior	Returns a PHYSICAL_VALUE_MIRROR_PT instance representing the right bound of the subtype.
low
Return type	PHYSICAL_VALUE_MIRROR
Behavior	Returns a PHYSICAL_VALUE_MIRROR_PT instance representing the lower bound of the subtype.
high
Return type	PHYSICAL_VALUE_MIRROR
Behavior	Returns a PHYSICAL_VALUE_MIRROR_PT instance representing the upper bound of the subtype.
length
Return type	POSITIVE_INDEX
Behavior	Returns the number of position numbers in the range of the corresponding subtype.
ascending
Return type	BOOLEAN
Behavior	Returns a TRUE if the corresponding subtype's constraint range is in ascending order, otherwise FALSE.

The protected type PHYSICAL_VALUE_MIRROR_PT mirrors a physical type value.

The index of a physical unit is determined by position of the corresponding unit declaration in the physical type definition. The index of the primary unit is zero; the index for each additional secondary unit is one more than that of its predecessor in the list.

The PHYSICAL_VALUE_MIRROR_PT provides the following methods:

get_subtype_mirror
Return type	PHYSICAL_SUBTYPE_MIRROR
Behavior	Returns the corresponding subtype mirror.
to_value_mirror
Return type	VALUE_MIRROR
Behavior	Returns the common value mirror for this mirror.
unit_index
Return type	INDEX
Behavior	Returns the index of the secondary unit of the mirrored physical type value.
value
Return type	INTEGER
Behavior	Returns the position number of the mirrored physical type value.
image
Return type	STRING
Behavior	Returns the string representation of the mirrored physical type value.

The access type PHYSICAL_SUBTYPE_MIRROR designates a PHYSICAL_SUBTYPE_MIRROR_PT. The access type
PHYSICAL_VALUE_MIRROR designates a PHYSICAL_VALUE_MIRROR_PT.

16.12.3.7 Record subtype and value mirrors [NEW]

The protected type RECORD_SUBTYPE_MIRROR_PT mirrors a record subtype.

The index of a record element is determined by position of the corresponding element declaration in the record type definition. The index of the record element of the first listed element declaration is zero; the index for each additional record element is one more than that of its predecessor in the list.

The RECORD_SUBTYPE_MIRROR_PT provides the following methods:

to_subtype_mirror
Return type	SUBTYPE_MIRROR
Behavior	Returns a SUBTYPE_MIRROR_PT instance representing this mirror as a common subtype mirror.
length
Return type	INDEX
Behavior	Returns the number of record elements in the corresponding subtype.
element_name
Parameters	element_idx : INDEX
Return type	STRING
Behavior	Returns the element name of the element_idx-th record element.
Errors	It is an error if the parameter element_idx is not in the range denoted by 0 to RECORD_SUBTYPE_MIRROR_PT.length minus 1.
element_index
Parameters	element_name : STRING
Return type	INDEX
Behavior	Returns the index of the record element, whose name matches element_name.
Errors	It is an error if the parameter element_name does not denote a record element of the record type mirrored by RECORD_SUBTYPE_MIRROR_PT.
element_subtype
Parameters	element_idx : INDEX
Return type	SUBTYPE_MIRROR
Behavior	Returns a SUBTYPE_MIRROR_PT instance representing the element_idx-th subtype.
Errors	It is an error if the parameter element_idx is not in the range denoted by 0 to RECORD_SUBTYPE_MIRROR_PT.length minus 1.
element_subtype
Parameters	element_name : STRING
Return type	SUBTYPE_MIRROR
Behavior	Returns a SUBTYPE_MIRROR_PT instance representing the element subtype.
Errors	It is an error if the parameter element_name does not denote a record element of the record type mirrored by RECORD_SUBTYPE_MIRROR_PT.
simple_name
Return type	STRING
Behavior	Returns the simple name of the corresponding subtype.

The protected type RECORD_VALUE_MIRROR_PT mirrors a record type value. It provides the following methods:

get_subtype_mirror
Return type	RECORD_SUBTYPE_MIRROR
Behavior	Returns the corresponding subtype mirror.
to_value_mirror
Return type	VALUE_MIRROR
Behavior	Returns the common value mirror for this mirror.
get
Parameters	element_idx : INDEX
Return type	VALUE_MIRROR
Behavior	Returns a value mirror for the element_idx-th record element.
Errors	It is an error if the parameter element_idx is not in the range denoted by 0 to RECORD_SUBTYPE_MIRROR_PT.length minus 1.
get
Parameters	element_name : STRING
Return type	VALUE_MIRROR
Behavior	Returns a value mirror for the record element, whose name matches the parameter element_name.
Errors	It is an error if the parameter element_name does not denote a record element of the record type mirrored by RECORD_SUBTYPE_MIRROR_PT.

The access type RECORD_SUBTYPE_MIRROR designates a RECORD_SUBTYPE_MIRROR_PT. The access type
RECORD_VALUE_MIRROR designates a RECORD_VALUE_MIRROR_PT.

16.12.3.8 Array subtype and value mirrors [NEW]

The protected type ARRAY_SUBTYPE_MIRROR_PT mirrors an array subtype. It provides the following methods:

to_subtype_mirror
Return type	SUBTYPE_MIRROR
Behavior	Returns a SUBTYPE_MIRROR_PT instance representing this mirror as a common subtype mirror.
dimensions
Return type	DIMENSION
Behavior	Returns the number of dimensions of the corresponding subtype.
index_subtype
Parameters	idx : INDEX := 1
Return type	SUBTYPE_MIRROR
Behavior	Returns a SUBTYPE_MIRROR_PT instance representing the idx-th index subtype.
Errors	It is an error if the parameter idx is not in the range denoted by ARRAY_SUBTYPE_MIRROR_PT.left to ARRAY_SUBTYPE_MIRROR_PT.right.
element_subtype
Return type	SUBTYPE_MIRROR
Behavior	Returns a SUBTYPE_MIRROR_PT instance representing the element subtype.
simple_name
Return type	STRING
Behavior	Returns the simple name of the corresponding subtype.
left
Parameters	idx : INDEX := 1
Return type	INDEX
Behavior	Returns the left bound of the corresponding subtype's idx-th index.
Errors	It is an error if the parameter idx is not in the range denoted by ARRAY_SUBTYPE_MIRROR_PT.left to ARRAY_SUBTYPE_MIRROR_PT.right.
right
Parameters	idx : INDEX := 1
Return type	INDEX
Behavior	Returns the right bound of the corresponding subtype's idx-th index.
Errors	It is an error if the parameter idx is not in the range denoted by ARRAY_SUBTYPE_MIRROR_PT.left to ARRAY_SUBTYPE_MIRROR_PT.right.
low
Parameters	idx : INDEX := 1
Return type	INDEX
Behavior	Returns the lower bound of the corresponding subtype's idx-th index.
Errors	It is an error if the parameter idx is not in the range denoted by ARRAY_SUBTYPE_MIRROR_PT.left to ARRAY_SUBTYPE_MIRROR_PT.right.
high
Parameters	idx : INDEX := 1
Return type	INDEX
Behavior	Returns the upper bound of the corresponding subtype's idx-th index.
Errors	It is an error if the parameter idx is not in the range denoted by ARRAY_SUBTYPE_MIRROR_PT.left to ARRAY_SUBTYPE_MIRROR_PT.right.
length
Parameters	idx : INDEX := 1
Return type	POSITIVE_INDEX
Behavior	Returns the length of the corresponding subtype's idx-th index.
Errors	It is an error if the parameter idx is not in the range denoted by ARRAY_SUBTYPE_MIRROR_PT.left to ARRAY_SUBTYPE_MIRROR_PT.right.
ascending
Parameters	idx : INDEX := 1
Return type	BOOLEAN
Behavior	Returns a TRUE if the corresponding subtype's idx-th index constraint is in ascending order, otherwise FALSE.
Errors	It is an error if the parameter idx is not in the range denoted by ARRAY_SUBTYPE_MIRROR_PT.left to ARRAY_SUBTYPE_MIRROR_PT.right.

The protected type ARRAY_VALUE_MIRROR_PT mirrors an array type value. It provides the following methods:

get_subtype_mirror
Return type	ARRAY_SUBTYPE_MIRROR
Behavior	Returns the corresponding subtype mirror.
to_value_mirror
Return type	VALUE_MIRROR
Behavior	Returns the common value mirror for this mirror.
get
Parameters	idx : INDEX
Return type	VALUE_MIRROR
Behavior	Returns a value mirror for the idx-th array element.
Errors	It is an error if the parameter idx is not in the range denoted by ARRAY_SUBTYPE_MIRROR_PT.left to ARRAY_SUBTYPE_MIRROR_PT.right.
get
Parameters	idx1, idx2 : INDEX
Return type	VALUE_MIRROR
Behavior	Returns a value mirror for the (idx1, idx2)-th array element.
Errors	It is an error if any of the parameters idx1 or idx2, specifying the indices of the first and second dimension, are not in the range denoted by ARRAY_SUBTYPE_MIRROR_PT.left(n) to ARRAY_SUBTYPE_MIRROR_PT.right(n), whereby n is the dimension.
get
Parameters	idx1, idx2, idx3 : INDEX
Return type	VALUE_MIRROR
Behavior	Returns a value mirror for the (idx1, idx2, idx3)-th array element.
Errors	It is an error if any of the parameters idx1, idx2 or idx3, specifying the indices of the first, second and third dimension, are not in the range denoted by ARRAY_SUBTYPE_MIRROR_PT.left(n) to ARRAY_SUBTYPE_MIRROR_PT.right(n), whereby n is the dimension.
get
Parameters	idx : INDEX_VECTOR
Return type	VALUE_MIRROR
Behavior	Returns a value mirror for the array element selected by the indices given by parameter idx.
Errors	It is an error if the indices given as an INDEX_VECTOR in parameter idx are not in the range denoted by ARRAY_SUBTYPE_MIRROR_PT.left(n) to ARRAY_SUBTYPE_MIRROR_PT.right(n), whereby n is the dimension and corresponds to the index's position in idx.

The access type ARRAY_SUBTYPE_MIRROR designates an ARRAY_SUBTYPE_MIRROR_PT. The access type
ARRAY_VALUE_MIRROR designates an ARRAY_VALUE_MIRROR_PT.

16.12.3.9 Access subtype and value mirrors [NEW]

The protected type ACCESS_SUBTYPE_MIRROR_PT mirrors an access subtype. It provides the following methods:

to_subtype_mirror
Return type	SUBTYPE_MIRROR
Behavior	Returns a SUBTYPE_MIRROR_PT instance representing this mirror as a common subtype mirror.
simple_name
Return type	STRING
Behavior	Returns the simple name of the corresponding subtype.
designated_subtype
Return type	SUBTYPE_MIRROR
Behavior	Returns a SUBTYPE_MIRROR_PT instance representing the designated subtype.

The protected type ACCESS_VALUE_MIRROR_PT mirrors an access type value. It provides the following methods:

get_subtype_mirror
Return type	ACCESS_SUBTYPE_MIRROR
Behavior	Returns the corresponding subtype mirror.
to_value_mirror
Return type	VALUE_MIRROR
Behavior	Returns the common value mirror for this mirror.
get
Return type	VALUE_MIRROR
Behavior	Returns a value mirror for the designated value.
is_null
Return type	BOOLEAN
Behavior	Returns TRUE if the mirrored access type value is null, otherwise FALSE.

The access type ACCESS_SUBTYPE_MIRROR designates an ACCESS_SUBTYPE_MIRROR_PT. The access type
ACCESS_VALUE_MIRROR designates an ACCESS_VALUE_MIRROR_PT.

16.12.3.10 File subtype and value mirrors [NEW]

The protected type FILE_SUBTYPE_MIRROR_PT mirrors a file subtype. It provides the following methods:

to_subtype_mirror
Return type	SUBTYPE_MIRROR
Behavior	Returns a SUBTYPE_MIRROR_PT instance representing this mirror as a common subtype mirror.
simple_name
Return type	STRING
Behavior	Returns the simple name of the corresponding subtype.
designated_subtype
Return type	SUBTYPE_MIRROR
Behavior	Returns a SUBTYPE_MIRROR_PT instance representing the designated subtype.

The protected type FILE_VALUE_MIRROR_PT mirrors a file type instance. It provides the following methods:

get_subtype_mirror
Return type	FILE_SUBTYPE_MIRROR
Behavior	Returns the corresponding subtype mirror.
to_value_mirror
Return type	VALUE_MIRROR
Behavior	Returns the common value mirror for this mirror.
file_logical_name
Return type	STRING
Behavior	Returns the file logical name of the mirrored file type instance.
file_open_kind
Return type	FILE_OPEN_KIND
Behavior	Returns the file open kind of the mirrored file type instance.

The access type FILE_SUBTYPE_MIRROR designates a FILE_SUBTYPE_MIRROR_PT. The access type
FILE_VALUE_MIRROR designates a FILE_VALUE_MIRROR_PT.

16.12.3.11 Protected subtype and value mirrors [NEW]

The protected type PROTECTED_SUBTYPE_MIRROR_PT mirrors a protected type subtype. It provides the following methods:

to_subtype_mirror
Return type	SUBTYPE_MIRROR
Behavior	Returns a SUBTYPE_MIRROR_PT instance representing this mirror as a common subtype mirror.
simple_name
Return type	STRING
Behavior	Returns the simple name of the corresponding subtype.

The protected type PROTECTED_VALUE_MIRROR_PT mirrors a protected type instance. It provides the following methods:

get_subtype_mirror
Return type	PROTECTED_SUBTYPE_MIRROR
Behavior	Returns the corresponding subtype mirror.
to_value_mirror
Return type	VALUE_MIRROR
Behavior	Returns the common value mirror for this mirror.

The access type PROTECTED_SUBTYPE_MIRROR designates a PROTECTED_SUBTYPE_MIRROR_PT. The access type
PROTECTED_VALUE_MIRROR designates a PROTECTED_VALUE_MIRROR_PT.

16.12.4 Examples [NEW]

16.12.4.1 General [NEW]

The following complex data type shall be converted to a string:

process
  type Rec is record
    I : INTEGER_VECTOR(0 to 3);
    R : REAL;
    T : TIME;
  end record;
 
  constant test : Rec := (
    I => (1, 3, 7, 9),
    R => 3.14,
    T => 25 ns
  );

  variable mirror : VALUE_MIRROR := test'reflect;
begin
  report to_string(mirror);
  wait;
end process;

-- result:
-- (I => (1, 3, 7, 9), R => 3.14, T => 25 ns)

16.12.4.1 Length of discrete types [NEW]

-- determines the length of a discrete type
function length(stm : SUBTYPE_MIRROR) return INDEX is
  constant class : TYPE_CLASS := stm.get_type_class;
begin
  case class is
    when CLASS_ENUMERATION => 
      return stm.to_enumeration.length;
    when CLASS_INTEGER =>
      return stm.to_integer.length;
    when others =>
      report TYPE_CLASS'image(class) & " doesn't have a length." severity FAILURE;
  end case;
  return -1;
end function;

16.12.4.2 Generic to_string [NEW]

-- can create a string for any value
function to_string(value : VALUE_MIRROR) return STRING is
  -- string-ify arrays
  function to_string(value : ARRAY_VALUE_MIRROR) return STRING is
    variable array_type : ARRAY_SUBTYPE_MIRROR;
    variable length : INDEX;
  begin
    array_type := value.get_subtype;
    length := length(array_type.index_subtype(1));
  
    if array_type.dimensions /= 1 then
      -- not supported in this example
      report "only 1D arrays are supported" severity FAILURE;
      return INDEX'image(array_type.dimensions) & "D array";
    end if;
    return "(" & to_string(value, 0, length, "") & ")";
  end function;
  
  -- string-ify array elements
  function to_string(value : ARRAY_VALUE_MIRROR; field_idx, length : INDEX; prefix : STRING) return STRING is
    variable index : index_vector;
  begin
    index := (0 => field_idx);
    block
      constant element_str : STRING := to_string(value.get(index));
    begin
      if field_idx < length - 1 then
        return to_string(value, field_idx + 1, length, prefix & element_str & ", ");
      elsif field_idx = length - 1 then
        return prefix & element_str;
      end if;
    end block;
  end function;
  
  -- string-ify records
  function to_string(value : RECORD_VALUE_MIRROR) return STRING is
  begin
    return "(" & to_string(value, 0, "") & ")";
  end function;
  
  -- string-ify record elements
  function to_string(value : RECORD_VALUE_MIRROR; element_idx : INDEX; prefix : STRING) return STRING is
    variable record_type : RECORD_SUBTYPE_MIRROR;
  begin
    record_type := value.get_subtype;
    block
      constant element_str : STRING := record_type.element_name(element_idx) & " => " & to_string(value.get(element_idx));
    begin
      if element_idx < record_type.length - 1 then
        return to_string(value, element_idx + 1, prefix & element_str & ", ");
      elsif element_idx = record_type.length - 1 then
        return prefix & element_str;
      end if;
    end block;
  end function;
  
  constant class : VALUE_CLASS := value.get_value_class;
begin
  case class is
    when CLASS_ENUMERATION =>
      return value.to_enumeration.image;
    when CLASS_INTEGER =>
      return INTEGER'image(value.to_integer.value);
    when CLASS_FLOATING =>
      return REAL'image(value.to_floating.value);
    when CLASS_PHYSICAL =>
      return value.to_physical.image;
    when CLASS_RECORD =>
      return to_string(value.to_record);
    when CLASS_ARRAY =>
      return to_string(value.to_array);
    when CLASS_ACCESS =>
      return "access type " & value.to_access.get_subtype.simple_name;
    when CLASS_FILE =>
      return "file type";
    when CLASS_PROTECTED =>
      return "protected type";
  end case;
end function;